Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(render): an unset texture array binds layers of its default - a textureArray param a material leaves unset was given the 2D white texture, which a sampler2DArray cannot read: on WebGL it read black, so a Planet with no layers packed yet, or any material whose array was not set, drew black where WebGPU drew white; the render context keeps white, black and flat-normal layers and MaterialStore::builtinDefault binds them for an array slot, in the scene and in post-processing alike

yhh36713a508064
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5fbb51a7d..72fa48c67 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,7 @@ published separately; it ships inside the editor.
### Fixed
+- **An unset texture array reads its default on WebGL.** A `textureArray` param a material left unset was given the plain white texture, which an array sampler cannot read, so on WebGL it read black (WebGPU already drew white). An unset array param now binds layers of its declared default: white, black or a flat normal.
- **Clearing an asset field from automation clears it.** `set_field` on an asset slot stored whatever it was given as text: 0 became the path "0" and null the path "null". The scene kept it, the editor drew nothing there, and an export failed to find an asset called 0. Nothing, however it is said (null, 0, false, the empty string, or "null" and "0" from a transport that sends values as text), now stores what the inspector's clear button stores: 0 in a handle-valued slot and the empty string in a Spine skeleton or atlas, which are string fields. Both ask one function for it (`emptyAssetValue`). Any other number is refused, since it names nothing a caller could have meant. `model_write`'s text also says what its report holds, to read `triangles` every time, and that `material.texture` may name a recipe.
- **A model's picture can be a recipe.** A model source's `material.texture` took a `.png`, `.jpg` or `.webp` and refused an `.esimage`, the recipe `image_write` answers as the picture's `ref`: a tree's branches named the pixels while the foliage material beside them named the layers, and a game shipped whichever was referenced. A recipe is now accepted there. Whether a path names a recipe is asked in one place, `sdk/src/asset/textureRecipePath.ts`, which reads nothing of the runtime: the registry that draws recipes, the packager deciding what ships and the model source's check each spelled the extension themselves.
- **A model's report is its steps as written, and names a step that undoes a decimate.** `report.steps` of a baked model listed every plain step its repeats came to, by an index among those: a spruce of thirteen rows of branches reported a hundred and thirty-eight steps, most the same line, and none under the index `model_edit` takes. It is now one entry for each step as written, by that index, a repeat counted once with how many steps it `made`, and each entry says the `triangles` the mesh had after it. And a step that splits faces to carry its own detail (a stain by a pattern, a displace, a sculpt) after a `decimate` took the decimate's triangles back in silence: a rock thinned to 1100 came out at 214,534, under the 300,000 the report calls heavy, and a field of them would have been gigabytes. The report now warns of each such step, with what it was given, what it left and which decimate it undid, and says how to keep the detail (before the decimate, carried by `normalBake`) or bound it (`detail`). The test also notes what the advice costs: a pattern stained before a decimate leaves colour seams the decimate will not cross, so it is `normalBake`'s `color: true` that carries it.
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 2a04d55c2..6f545c149 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -1111,7 +1111,7 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex
// Texture params (LUTs, masks) bind at their reflected material units;
// an unset param gets its declared default (white/black/flatnormal).
for (const auto& slot : layout->textures) {
- TextureHandle gpu = context_.materials().builtinDefault(slot.defaultTexture);
+ TextureHandle gpu = context_.materials().builtinDefault(slot);
if (temporal && (slot.name == "u_history" || slot.name == "u_feedback")
&& temporal->history[temporal->readIndex]) {
gpu = temporal->history[temporal->readIndex]->getColorAttachment();
@@ -1336,7 +1336,7 @@ void PostProcessPipeline::bindBlitInputs(const resource::ShaderHandle& handle) {
device_.setUniformBuffer(MATERIAL_CONSTANTS_BINDING, blitParamUbo_);
}
for (const auto& slot : layout->textures) {
- TextureHandle gpu = context_.materials().builtinDefault(slot.defaultTexture);
+ TextureHandle gpu = context_.materials().builtinDefault(slot);
if (slot.name == "u_displayLut" && lastPass && display_lut_texture_ != 0) gpu = TextureHandle{display_lut_texture_};
if (gpu != TextureHandle::Invalid) device_.bindTexture(slot.unit, gpu);
}
diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cpp
index 8276d8281..74e2fdfc3 100644
--- a/src/esengine/renderer/frame/RenderContext.cpp
+++ b/src/esengine/renderer/frame/RenderContext.cpp
@@ -52,6 +52,7 @@ void RenderContext::init() {
initFrameUbo();
materials_.setDevice(&device_);
materials_.setBuiltinDefaults(whiteTexture_, blackTexture_, flatNormalTexture_, ripplesTexture_);
+ materials_.setBuiltinDefaultArrays(whiteArrayTexture_, blackArrayTexture_, flatNormalArrayTexture_);
lights_.setDevice(&device_);
initialized_ = true;
@@ -62,7 +63,8 @@ void RenderContext::shutdown() {
return;
}
- for (TextureHandle* tex : {&whiteTexture_, &blackTexture_, &flatNormalTexture_, &ripplesTexture_}) {
+ for (TextureHandle* tex : {&whiteTexture_, &blackTexture_, &flatNormalTexture_, &ripplesTexture_, &whiteArrayTexture_,
+ &blackArrayTexture_, &flatNormalArrayTexture_}) {
if (*tex != TextureHandle::Invalid) {
device_.deleteTexture(*tex);
*tex = TextureHandle::Invalid;
@@ -96,13 +98,15 @@ void RenderContext::shutdown() {
ES_LOG_INFO("RenderContext shutdown");
}
-TextureHandle RenderContext::make1x1Texture(u32 rgba) {
+TextureHandle RenderContext::make1x1Texture(u32 rgba, u32 layers) {
TextureDesc desc;
desc.width = 1;
desc.height = 1;
+ desc.layers = layers;
desc.minFilter = TextureFilter::Nearest;
desc.magFilter = TextureFilter::Nearest;
- return device_.createTexture(desc, GfxContent::retained(), &rgba);
+ const std::vector<u32> texels(layers, rgba);
+ return device_.createTexture(desc, GfxContent::retained(), texels.data());
}
namespace {
@@ -143,6 +147,9 @@ void RenderContext::initDefaultTextures() {
whiteTexture_ = make1x1Texture(0xFFFFFFFF); // RGBA(255,255,255,255)
blackTexture_ = make1x1Texture(0xFF000000); // RGBA(0,0,0,255)
flatNormalTexture_ = make1x1Texture(0xFFFF8080); // RGB(128,128,255) → normal (0,0,1)
+ whiteArrayTexture_ = make1x1Texture(0xFFFFFFFF, 2);
+ blackArrayTexture_ = make1x1Texture(0xFF000000, 2);
+ flatNormalArrayTexture_ = make1x1Texture(0xFFFF8080, 2);
ripplesTexture_ = makeRipplesTexture();
ES_LOG_DEBUG("Default textures created (white {}, black {}, flatNormal {})",
static_cast<u32>(whiteTexture_), static_cast<u32>(blackTexture_),
diff --git a/src/esengine/renderer/frame/RenderContext.hpp b/src/esengine/renderer/frame/RenderContext.hpp
index 72634cdd2..0eb799172 100644
--- a/src/esengine/renderer/frame/RenderContext.hpp
+++ b/src/esengine/renderer/frame/RenderContext.hpp
@@ -228,7 +228,7 @@ public:
private:
void initDefaultTextures();
- TextureHandle make1x1Texture(u32 rgba);
+ TextureHandle make1x1Texture(u32 rgba, u32 layers = 1);
TextureHandle makeRipplesTexture();
void initFrameUbo();
@@ -238,6 +238,10 @@ private:
u64 program_epoch_ = 0;
TextureHandle whiteTexture_ = TextureHandle::Invalid;
+ /// Layers (two: one layer is a plain 2D texture) of white, black and a flat normal: what an unset `textureArray` param binds.
+ TextureHandle whiteArrayTexture_ = TextureHandle::Invalid;
+ TextureHandle blackArrayTexture_ = TextureHandle::Invalid;
+ TextureHandle flatNormalArrayTexture_ = TextureHandle::Invalid;
TextureHandle blackTexture_ = TextureHandle::Invalid;
TextureHandle flatNormalTexture_ = TextureHandle::Invalid;
TextureHandle ripplesTexture_ = TextureHandle::Invalid;
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index b9971f104..1eae17bc7 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -370,7 +370,7 @@ MaterialUniformLayout MaterialStore::layoutOf(const resource::ParsedShader& pars
// Resolve the param's `default(<name>)` to a built-in default texture, bound when
// a material leaves the param unset.
layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),
- materialDefaultByName(p.defaultValue) });
+ materialDefaultByName(p.defaultValue), p.layered });
}
} else if (p.std140Offset >= 0) {
MaterialParamSlot slot{ p.name, static_cast<u32>(p.std140Offset), paramArity(p.type) };
@@ -465,7 +465,7 @@ void MaterialStore::bindForDraw(u32 materialId, u32 samplerUnits) {
if (lit != layouts_.end()) {
for (const auto& slot : lit->second.textures) {
if (slot.unit < 32 && !((samplerUnits >> slot.unit) & 1u)) continue;
- TextureHandle gpu = builtinDefault(slot.defaultTexture);
+ TextureHandle gpu = builtinDefault(slot);
// What stood behind this draw, where the frame took a copy of it; a material that named a texture there keeps its own.
if (sceneColor_ != TextureHandle::Invalid && slot.name == "u_sceneColor") gpu = sceneColor_;
if (sceneDepth_ != TextureHandle::Invalid && slot.name == "u_sceneDepthMap") gpu = sceneDepth_;
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index 0eec77e1f..e93a1d170 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -77,6 +77,9 @@ struct MaterialTextureSlot {
/// rather than the resolved id: the built-ins are re-created when the device
/// is, and an id resolved at registration would outlive the texture it names.
MaterialDefaultTexture defaultTexture = MaterialDefaultTexture::White;
+ /// Declared `textureArray` (a `sampler2DArray`): left unset, it binds layers of its default's colour (setBuiltinDefaultArrays),
+ /// as a 2D default under an array sampler reads black on WebGL.
+ bool layered = false;
};
/** @brief A material's bound texture at a sampler unit. */
@@ -213,6 +216,19 @@ public:
/// The context's current fallback for a declared `default(...)`. One authority,
/// so the post-process pipeline's params fall back to the same textures.
TextureHandle builtinDefault(MaterialDefaultTexture which) const;
+ /// The context's layers of white, black and a flat normal: what an unset `textureArray` param binds.
+ void setBuiltinDefaultArrays(TextureHandle white, TextureHandle black, TextureHandle flatNormal) {
+ defaultWhiteArray_ = white;
+ defaultBlackArray_ = black;
+ defaultFlatNormalArray_ = flatNormal;
+ }
+ /// What an unset param of `slot` binds: its declared default, as layers for an array (ripples are white there).
+ TextureHandle builtinDefault(const MaterialTextureSlot& slot) const {
+ if (!slot.layered) return builtinDefault(slot.defaultTexture);
+ if (slot.defaultTexture == MaterialDefaultTexture::Black) return defaultBlackArray_;
+ if (slot.defaultTexture == MaterialDefaultTexture::FlatNormal) return defaultFlatNormalArray_;
+ return defaultWhiteArray_;
+ }
/**
* @brief Point each of @p shader's texture params at its unit.
@@ -578,6 +594,9 @@ private:
TextureHandle defaultBlack_ = TextureHandle::Invalid;
TextureHandle defaultFlatNormal_ = TextureHandle::Invalid;
TextureHandle defaultRipples_ = TextureHandle::Invalid;
+ TextureHandle defaultWhiteArray_ = TextureHandle::Invalid;
+ TextureHandle defaultBlackArray_ = TextureHandle::Invalid;
+ TextureHandle defaultFlatNormalArray_ = TextureHandle::Invalid;
};
} // namespace esengine
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 30f56ad65..503ea462a 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4820,4 +4820,6 @@ export const NOTED = {
{"note": "A run of mesh draws is one call on WebGL2."},
"feat(ecs): every component carries the tick of its last write, and an audit finds a write that left none - Registry::patch, markChanged, changedSince and anyChangedSince over stamps kept beside the components, the reader's tick from beginChangeRead, and setChangeAudit, which reports each component type written without a stamp; the first step toward a renderer that walks only what changed":
{"note": "Components carry the tick of their last write."},
+ "fix(render): an unset texture array binds layers of its default - a textureArray param a material leaves unset was given the 2D white texture, which a sampler2DArray cannot read: on WebGL it read black, so a Planet with no layers packed yet, or any material whose array was not set, drew black where WebGPU drew white; the render context keeps white, black and flat-normal layers and MaterialStore::builtinDefault binds them for an array slot, in the scene and in post-processing alike":
+ {"note": "An unset texture array reads its default on WebGL."},
};