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): a shadow pass draws depth, not what the material says

yhh701df0cf4763
diff --git a/desktop/public/scenes/mesh-shadow-material.esscene b/desktop/public/scenes/mesh-shadow-material.esscene
new file mode 100644
index 000000000..96e3dce2a
--- /dev/null
+++ b/desktop/public/scenes/mesh-shadow-material.esscene
@@ -0,0 +1,150 @@
+{
+ "version": 1,
+ "name": "MeshShadowMaterial",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Ground",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -200
+ },
+ "scale": {
+ "x": 600,
+ "y": 600,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "/scenes/shadow-quad.esmesh",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": true,
+ "opaque": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Blocker",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 150,
+ "y": 150,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "/scenes/shadow-quad.esmesh",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": true,
+ "opaque": true,
+ "enabled": true,
+ "material": "/scenes/mesh-shadow-material/blockmat.esmaterial"
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "direction": {
+ "x": 0.5,
+ "y": 0
+ },
+ "meshShadows": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterial b/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterial
new file mode 100644
index 000000000..1f4b27b18
--- /dev/null
+++ b/desktop/public/scenes/mesh-shadow-material/blockmat.esmaterial
@@ -0,0 +1,9 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "blockmat.esshader",
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true,
+ "properties": {}
+}
diff --git a/desktop/public/scenes/mesh-shadow-material/blockmat.esshader b/desktop/public/scenes/mesh-shadow-material/blockmat.esshader
new file mode 100644
index 000000000..c131bbf31
--- /dev/null
+++ b/desktop/public/scenes/mesh-shadow-material/blockmat.esshader
@@ -0,0 +1,24 @@
+#pragma shader "BlockerMaterial"
+#pragma version 300 es
+#pragma domain Unlit2D
+
+#pragma fragment
+precision mediump float;
+
+out vec4 fragColor;
+
+// A constant, so the pixel says one thing only: the material ran, in the pass it
+// belongs to. What it must NOT do is run in the shadow pass — an occluder there
+// writes packed depth, and a material that reached it would write this red into
+// the atlas instead (and sample the atlas it was writing, through the shadow
+// sampler its mesh variant declares).
+void main() {
+ fragColor = vec4(1.0, 0.0, 0.0, 1.0);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ return vec4f(1.0, 0.0, 0.0, 1.0);
+}
+#pragma end
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index fea0879a5..63d78d11e 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -234,22 +234,14 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
if (stencil != GfxStencilMode::Off) {
device.setStencilReference(cmd.stencil_ref);
}
- // The batch shader declares 8 samplers, and WebGL2 invalidates a draw if any
- // referenced sampler unit lacks a complete texture — even units the per-vertex
- // branch never samples. For the Batch layout, fill the unused slots with a
- // STABLE white texture: those units then stay pinned across draws, so the
- // per-slot bind cache makes them no-ops and only slot 0 rebinds per texture
- // change (filling with this draw's own tex re-pointed all 8 units each time).
- // Other layouts bind only the samplers they declare.
- if (cmd.layout_id == LayoutId::Batch) {
+ // A draw that samples binds every unit its shader declares, not only the
+ // ones it reads: an untouched unit holds what the last draw put there, in
+ // any pass. The fill is a STABLE white, so unused units cost no rebind.
+ if (cmd.texture_count > 0) {
for (u8 slot = 0; slot < MAX_CMD_TEXTURE_SLOTS; ++slot) {
u32 tex = (slot < cmd.texture_count) ? cmd.texture_ids[slot] : white_texture_id;
device.bindTexture(slot, TextureHandle{tex});
}
- } else {
- for (u8 slot = 0; slot < cmd.texture_count; ++slot) {
- device.bindTexture(slot, TextureHandle{cmd.texture_ids[slot]});
- }
}
if (cmd.hasPersistentGeometry()) {
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index a47369f2d..37b7336b4 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -248,19 +248,6 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
}
if (mesh.cullBackfaces) key.cull = static_cast<u8>(CullMode::Back);
- // Casting into a shadow map: every occluder is opaque and depth-tested for
- // this pass whatever it is in the camera's, because the map holds the
- // NEAREST occluder and a blended one would let a later draw overwrite it.
- if (ctx.shadow_pass) {
- key.stage = RenderStage::Opaque;
- key.blend = BlendMode::None;
- key.depthTest = true;
- key.depthWrite = true;
- key.materialId = 0;
- key.shadowTextureId = 0;
- key.envTextureId = 0;
- }
-
// Material resolve mirrors SpritePlugin: an unregistered handle falls back to
// the default batch shader; a material owns shading fully, so it takes
// precedence over the lit toggle.
@@ -278,6 +265,19 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
if (litProgram != 0) key.shaderId = litProgram;
}
+ // Casting into a shadow map: opaque and depth-tested whatever the camera's
+ // pass makes it, and none of the three ways to describe a surface — lit, a
+ // normal map, a material. LAST, so the pass outranks all three.
+ if (ctx.shadow_pass) {
+ key.stage = RenderStage::Opaque;
+ key.blend = BlendMode::None;
+ key.depthTest = true;
+ key.depthWrite = true;
+ key.materialId = 0;
+ key.shadowTextureId = 0;
+ key.envTextureId = 0;
+ }
+
// Resident geometry: only the transform is written for the frame. Its
// vertices are local-space and untouched, so the CPU loop below — which
// exists to bake world space into every vertex — is skipped entirely.
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 282f6065c..9656ec850 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -1481,7 +1481,13 @@ void WebGPUDevice::flushBindGroup() {
WGPUBindGroupEntry texEntries[kTextureSlots * 2];
u32 texCount = 0;
for (u32 unit = 0; unit < kTextureSlots; ++unit) {
- auto it = textures_.find(texture_slots_[unit]);
+ // A pass may not sample what it draws into: WebGPU rejects the whole
+ // COMMAND BUFFER for it, not the draw. The dummy stands in — reading
+ // one's own attachment is undefined under every backend anyway.
+ const u32 bound = texture_slots_[unit];
+ const bool feedback = bound != 0 && (bound == pass_color_texture_ ||
+ bound == pass_depth_texture_);
+ auto it = feedback ? textures_.end() : textures_.find(bound);
const TextureRec* rec = (it != textures_.end()) ? &it->second : dummy;
if (!rec) continue;
const u32 tb = textureBindingForUnit(unit);
@@ -1580,6 +1586,8 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
WGPUTextureView dsView = nullptr;
pass_ds_format_ = WGPUTextureFormat_Undefined;
pass_color_format_ = surface_format_;
+ pass_color_texture_ = 0;
+ pass_depth_texture_ = 0;
pass_is_surface_ = desc.target == FramebufferHandle::Default;
if (desc.target != FramebufferHandle::Default) {
auto fbIt = framebuffers_.find(static_cast<u32>(desc.target));
@@ -1594,6 +1602,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
}
targetView = texIt->second.view;
pass_color_format_ = texIt->second.format;
+ pass_color_texture_ = fbIt->second.color0;
pass_width_ = texIt->second.width;
pass_height_ = texIt->second.height;
if (fbIt->second.depthStencil != 0) {
@@ -1601,6 +1610,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
if (dsIt != textures_.end()) {
dsView = dsIt->second.view;
pass_ds_format_ = dsIt->second.format;
+ pass_depth_texture_ = fbIt->second.depthStencil;
}
}
} else {
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 84023f6e6..2792d9bfc 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -467,6 +467,10 @@ private:
u32 pass_height_ = 0;
WGPUTextureFormat pass_ds_format_ = WGPUTextureFormat_Undefined;
WGPUTextureFormat pass_color_format_ = WGPUTextureFormat_RGBA8Unorm;
+ /// What this pass draws INTO, so flushBindGroup can refuse to also sample it.
+ /// 0 = none (the surface, which nothing can hold as a texture anyway).
+ u32 pass_color_texture_ = 0;
+ u32 pass_depth_texture_ = 0;
WGPUCommandEncoder encoder_ = nullptr;
WGPURenderPassEncoder pass_ = nullptr;
void* surface_window_ = nullptr; ///< Native window the surface was made for.
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index 34daf6758..d90423da0 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -101,8 +101,8 @@ TEST_CASE("appendIndexedDraw: non-Batch stream uses its own stride for baseVerte
REQUIRE(h.list.commandCount() == 2);
CHECK(h.list.command(0).layout_id == LayoutId::Shape);
- // A textureless non-Batch draw must not claim a sampler slot (execute() binds
- // only texture_count units for non-Batch layouts).
+ // A textureless draw must not claim a sampler slot: texture_count is what
+ // execute() binds, and zero of them is what "declares no sampler" looks like.
CHECK(h.list.command(0).texture_count == 0);
CHECK(h.list.command(1).vertex_byte_offset == 4 * sizeof(TestShapeVertex));
// Indices rebased by the SHAPE stride (4 records), not the Batch stride.
@@ -377,6 +377,51 @@ TEST_CASE("execute: a merged mesh draw asks the device for its instances in one
CHECK(h.device.lastDrawIndexCount == 36);
}
+TEST_CASE("execute: a sampling draw pins every sampler unit it does not use") {
+ // A unit a draw leaves alone keeps what the draw BEFORE it bound, across passes
+ // and frames. So a draw states its whole sampler block or none of it: one that
+ // leaves unit 2 alone samples the shadow atlas a shadow pass is drawing into.
+ Harness h;
+ MaterialStore materials;
+ const u32 white = 99;
+
+ BatchDrawKey key = meshKey(5, /*textureId=*/7); // albedo only: texture_count == 1
+ pushMeshInstance(h, key, 1.0f);
+ h.list.finalize(h.pool);
+ h.pool.upload();
+ h.list.execute(h.device, h.pool, materials, white);
+
+ u32 boundAt[MAX_CMD_TEXTURE_SLOTS] = {};
+ bool seen[MAX_CMD_TEXTURE_SLOTS] = {};
+ for (const auto& [unit, tex] : h.device.bindLog) {
+ REQUIRE(unit < MAX_CMD_TEXTURE_SLOTS);
+ boundAt[unit] = static_cast<u32>(tex);
+ seen[unit] = true;
+ }
+ for (u32 unit = 0; unit < MAX_CMD_TEXTURE_SLOTS; ++unit) {
+ CHECK(seen[unit]); // no unit left to whatever ran before
+ CHECK(boundAt[unit] == (unit == 0 ? 7u : white));
+ }
+}
+
+TEST_CASE("execute: a textureless stream declares no sampler and is left alone") {
+ // The other half of the same rule: the shape stream samples nothing, so it
+ // declares nothing, so there is no binding for stale state to land in.
+ Harness h;
+ MaterialStore materials;
+
+ TestShapeVertex sverts[4] = {};
+ BatchDrawKey key = quadKey(0);
+ key.layoutId = LayoutId::Shape;
+ appendIndexedDraw(h.pool, h.list, h.clips, sverts, 4, BATCH_QUAD_INDICES, 6, key);
+
+ h.list.finalize(h.pool);
+ h.pool.upload();
+ h.list.execute(h.device, h.pool, materials, 99);
+
+ CHECK(h.device.bindLog.empty());
+}
+
TEST_CASE("clip state is stamped onto commands from every stream") {
Harness h;
Entity clipped{5};
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 5927b13f8..0a386d43a 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -72,6 +72,11 @@ export const SCENES = [
// The blocker itself stays lit — shadowing one's own caster is the classic bug.
{ id: "mesh-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
+ // The same scene with a MATERIAL on the occluder, over three frames because a
+ // stale sampler unit needs a previous frame. Red at the centre says the material
+ // ran in the CAMERA's pass; black at 0.708 says the occluder still cast.
+ { id: "mesh-shadow-material", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-material.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "3", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
+
// The same question through a PERSPECTIVE camera, which is what a 3D scene uses:
// coverage derived from the camera's NDC z=0 slice is the whole view for the
// orthographic one above and a sliver near the near plane for this one.