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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): the scene's depth is something an effect can read
yhhac17f41a5b01
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d1228786b..753fd8d2a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,49 @@ published separately; it ships inside the editor.- **`estella.mjs export --minify`**, for the targets whose default it is not.+- **An effect can read the scene's DEPTH.** Nothing could: the depth attachment+ was written every frame and sampled by nothing, and on WebGPU it was not even+ sampleable — `createTexture` gave depth formats `RenderAttachment` alone, with+ a comment saying the engine never reads them. So the whole family of effects+ that needs to know how far away a pixel is — outlines that follow geometry,+ fog, depth of field, anything screen-space — had no way to exist.++ The scene's depth now reaches a PostProcess pass at texture unit 7. On WebGPU+ that meant three things a colour texture never needed: the texture carries+ `TextureBinding`; a **depth-only view** stands under the binding, and its+ format is the ASPECT's (`depth24plus`) rather than the texture's, which Dawn+ rejects as incompatible; and the bind-group layout learns which of its units+ are depth (`sampleType = Depth`) by scanning the WGSL for `texture_depth_2d`,+ with a depth dummy to back a declared-but-unbound one — a white RGBA8 dummy+ under a depth entry is a validation error, not a blank sample. Depth is read+ by texel (`texelFetch` / `textureLoad`): a fullscreen pass is 1:1 with the+ scene, and a depth texture is not filterable.++- **`depthOutline`, a post effect that outlines geometry rather than shading.**+ The existing `outline` runs a Sobel over scene luma, so it draws an edge+ wherever the picture changes — texture detail, a shadow's border, two shades+ of one wall — and misses a silhouette between two surfaces of the same colour.+ This one reads depth, so an edge is a place the geometry steps, at any+ contrast including none. Depth is compared as a RATIO to the nearest+ neighbour, which is what lets one threshold hold across the whole view: an+ absolute difference of 0.001 is a wall's thickness up close and a kilometre+ out.++ Two gates, both backends. `depth-outline` puts two SAME-COLOURED quads at+ different depths, so the edge in the middle of the frame came from depth or it+ came from nowhere — sabotage-verified by moving the near quad back to the far+ one's z, which is a change to the fixture and needs no rebuild.+ `depth-outline-flat` runs the same effect over a scene that writes no depth+ and requires the frame to come out exactly as it went in.++ **One thing that did not survive its own test.** The pipeline first forced the+ scene target to carry depth whenever an enabled effect read it — a sensible+ safety net that turned out to change nothing: with it removed, the flat gate+ still passed on both backends, because an unbound depth unit reads zero and an+ effect that finds no step draws no edge. It was deleted rather than kept, on+ the rule this repo already holds its budgets to: a guard nothing can fail is a+ guard nothing is checking.+- **The shadow atlas is a loan now, not a framebuffer held for the run.** It wascreated on the first frame that cast a shadow and never given back — 2048²with depth, ~32MB, for as long as the process lived, so a game that walked outdiff --git a/fixtures/scenes/depth-outline-flat.esscene b/fixtures/scenes/depth-outline-flat.esscenenew file mode 100644index 000000000..a3437c014--- /dev/null+++ b/fixtures/scenes/depth-outline-flat.esscene@@ -0,0 +1,87 @@+{+ "version": 4,+ "name": "DepthOutlineFlat",+ "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+ }+ },+ {+ "type": "PostProcessVolume",+ "data": {+ "isGlobal": true,+ "priority": 0,+ "weight": 1,+ "effects": [+ {+ "type": "depthOutline",+ "enabled": true,+ "uniforms": {+ "u_intensity": 1,+ "u_threshold": 0.01,+ "u_thickness": 4+ }+ }+ ]+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Sprite",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 5,+ "y": 5+ },+ "color": {+ "r": 0.9,+ "g": 0.4,+ "b": 0.1,+ "a": 1+ }+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/depth-outline.esscene b/fixtures/scenes/depth-outline.esscenenew file mode 100644index 000000000..abcaccece--- /dev/null+++ b/fixtures/scenes/depth-outline.esscene@@ -0,0 +1,121 @@+{+ "version": 4,+ "name": "DepthOutline",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true,+ "priority": 0+ }+ },+ {+ "type": "PostProcessVolume",+ "data": {+ "isGlobal": true,+ "priority": 0,+ "weight": 1,+ "effects": [+ {+ "type": "depthOutline",+ "enabled": true,+ "uniforms": {+ "u_intensity": 1,+ "u_threshold": 0.01,+ "u_thickness": 4+ }+ }+ ]+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Far",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -60,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "color": {+ "r": 0.8,+ "g": 0.2,+ "b": 0.2,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "opaque": true,+ "mesh": "/scenes/textured-quad.esmesh"+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Near",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 60,+ "y": 0,+ "z": 120+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "color": {+ "r": 0.8,+ "g": 0.2,+ "b": 0.2,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "opaque": true,+ "mesh": "/scenes/textured-quad.esmesh"+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/depth-outline.textures.json b/fixtures/scenes/depth-outline.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/fixtures/scenes/depth-outline.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex 2402a6f99..cff5a455e 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -178,6 +178,17 @@ registerEffect({],});+registerEffect({+ type: 'depthOutline',+ label: 'Depth Outline',+ factory: () => postProcessEffects.createDepthOutline(),+ uniforms: [+ { name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 1 },+ { name: 'u_threshold', label: 'Threshold', min: 0.0005, max: 0.2, step: 0.0005, defaultValue: 0.01 },+ { name: 'u_thickness', label: 'Thickness', min: 1, max: 4, step: 1, defaultValue: 1 },+ ],+});+registerEffect({type: 'lutGrade',label: 'LUT Grade',diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.tsindex 81160080c..433730d93 100644--- a/sdk/src/postprocess/postProcessEffects.ts+++ b/sdk/src/postprocess/postProcessEffects.ts@@ -668,6 +668,83 @@ fn lum(uv : vec2f) -> f32 {return Material.compileShader(source);},+ createDepthOutline(): ShaderHandle {+ // The silhouette, not the shading: `outline` Sobels scene LUMA and draws+ // an edge wherever the picture changes, while this reads DEPTH, so an+ // edge is a place the geometry steps — at any contrast, including none.++ // Depth is compared as a RATIO, which is what makes one threshold hold+ // across the view: an absolute 0.001 is a wall up close and a kilometre+ // out. Fetched by texel — the pass is 1:1 and depth is not filterable.+ const source = `#pragma shader "PP Depth Outline"+#pragma version 300 es+#pragma domain PostProcess+#pragma param u_intensity float default(1) range(0,1)+#pragma param u_threshold float default(0.01) range(0.0005,0.2)+#pragma param u_thickness float default(1) range(1,4)++#pragma fragment+precision highp float;++in vec2 v_texCoord;+uniform sampler2D u_texture;+uniform highp sampler2D u_sceneDepth;+out vec4 fragColor;++float depthAt(ivec2 texel, ivec2 size) {+ return texelFetch(u_sceneDepth, clamp(texel, ivec2(0), size - ivec2(1)), 0).r;+}++void main() {+ vec4 src = texture(u_texture, v_texCoord);+ ivec2 size = textureSize(u_sceneDepth, 0);+ ivec2 here = ivec2(gl_FragCoord.xy);+ int step = int(max(u_thickness, 1.0));++ float d = depthAt(here, size);+ // Nothing was drawn here: the cleared far plane has no silhouette to find,+ // and testing it would ring the whole frame in an outline.+ if (d >= 1.0) { fragColor = src; return; }++ float dl = depthAt(here + ivec2(-step, 0), size);+ float dr = depthAt(here + ivec2( step, 0), size);+ float dd = depthAt(here + ivec2(0, -step), size);+ float du = depthAt(here + ivec2(0, step), size);+ // The NEAREST neighbour only: an edge belongs to the surface in front, so+ // the far side of a silhouette does not get a second outline of its own.+ float far = max(max(dl, dr), max(dd, du));+ float edge = clamp(((far - d) / max(d, 1e-6) - u_threshold) * 20.0, 0.0, 1.0);+ fragColor = vec4(mix(src.rgb, vec3(0.0), edge * u_intensity), src.a);+}+#pragma end++#pragma fragment wgsl+fn depthAt(texel : vec2i, size : vec2i) -> f32 {+ return textureLoad(t7, clamp(texel, vec2i(0), size - vec2i(1)), 0);+}++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ let size = vec2i(textureDimensions(t7, 0));+ let here = vec2i(v.pos.xy);+ let step = i32(max(mc.u_thickness, 1.0));++ let d = depthAt(here, size);+ if (d >= 1.0) { return src; }++ let dl = depthAt(here + vec2i(-step, 0), size);+ let dr = depthAt(here + vec2i( step, 0), size);+ let dd = depthAt(here + vec2i(0, -step), size);+ let du = depthAt(here + vec2i(0, step), size);+ let far = max(max(dl, dr), max(dd, du));+ let edge = clamp(((far - d) / max(d, 1e-6) - mc.u_threshold) * 20.0, 0.0, 1.0);+ return vec4f(mix(src.rgb, vec3f(0.0), vec3f(edge * mc.u_intensity)), src.a);+}+#pragma end+`;+ return Material.compileShader(source);+ },+createPixelate(): ShaderHandle {// Snaps sampling to a grid of u_pixelSize-device-pixel blocks — the// canonical retro/mosaic 2D look. u_pixelSize <= 1 samples per-texeldiff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 8077d01a9..88182b183 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -394,6 +394,9 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex// input/scene as the t0/s0 and t1/s1 bind-group pairs.shader->setUniform("u_texture", 0);if (shader->hasUniform("u_sceneTexture")) shader->setUniform("u_sceneTexture", 1);+ if (shader->hasUniform("u_sceneDepth")) {+ shader->setUniform("u_sceneDepth", static_cast<i32>(kSceneDepthUnit));+ }}// #pragma-param effects: params ride the reflected MaterialConstants block@@ -433,7 +436,16 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContexdevice->setUniformBuffer(MATERIAL_CONSTANTS_BINDING, pass.paramUbo);}}- // Texture params (LUTs, masks) bind at their reflected material units;+ // Scene depth, bound whether or not this pass reads it: the WGSL twin+ // declares the unit either way, and the scene is already every pass's+ // declared read, so its depth lives exactly as long as it does.++ // A target with no depth binds nothing, and an effect over a scene that+ // wrote none then finds no edge — the right answer for a flat one.+ device->bindTexture(kSceneDepthUnit, graph_ ? graph_->depthTextureOf(sceneResource_)+ : TextureHandle::Invalid);++ // 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);@@ -453,6 +465,9 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex}u32 extraUnit = 2;for (const auto& [name, glId] : pass.textureUniforms) {+ // Stops below the scene-depth unit rather than walking into it: a+ // sixth loose texture would otherwise take the binding depth is on.+ if (extraUnit >= kSceneDepthUnit) break;if (glId != 0 && shader->hasUniform(name)) {device->bindTexture(extraUnit, TextureHandle{glId});shader->setUniform(name, static_cast<i32>(extraUnit));diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cppindex 09a55b64f..a8bbeccff 100644--- a/src/esengine/renderer/graph/RenderGraph.cpp+++ b/src/esengine/renderer/graph/RenderGraph.cpp@@ -221,6 +221,13 @@ TextureHandle RenderGraph::textureOf(ResourceId id) const {return resources_[id].texture;}+TextureHandle RenderGraph::depthTextureOf(ResourceId id) const {+ if (id >= resources_.size()) return TextureHandle::Invalid;+ const Resource& res = resources_[id];+ if (res.kind != Kind::Transient || res.pooled == kNoTarget) return TextureHandle::Invalid;+ return pool_.depthTextureOf(res.pooled);+}+void RenderGraph::releasePool() {for (auto& res : resources_) {res.pooled = kNoTarget;diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hppindex 0d05fba4a..1dba410cf 100644--- a/src/esengine/renderer/graph/RenderGraph.hpp+++ b/src/esengine/renderer/graph/RenderGraph.hpp@@ -153,6 +153,10 @@ public:* only while it holds a physical target. */TextureHandle textureOf(ResourceId id) const;+ /** Its depth attachment, for a resource declared with one. Invalid for an+ * import (the graph did not make it) and for a target without depth. */+ TextureHandle depthTextureOf(ResourceId id) const;+/** Drops every pooled target. For shutdown and for device loss, after which* the handles the pool holds name nothing. */void releasePool();diff --git a/src/esengine/renderer/graph/TargetPool.cpp b/src/esengine/renderer/graph/TargetPool.cppindex 221201112..1204d0002 100644--- a/src/esengine/renderer/graph/TargetPool.cpp+++ b/src/esengine/renderer/graph/TargetPool.cpp@@ -117,6 +117,11 @@ TextureHandle TargetPool::textureOf(TargetHandle handle) const {return entry ? entry->fbo->getColorAttachment() : TextureHandle::Invalid;}+TextureHandle TargetPool::depthTextureOf(TargetHandle handle) const {+ const Entry* entry = resolve(handle);+ return entry ? entry->fbo->getDepthAttachment() : TextureHandle::Invalid;+}+void TargetPool::age() {for (auto& entry : entries_) {if (!entry.fbo || entry.inUse) continue;diff --git a/src/esengine/renderer/graph/TargetPool.hpp b/src/esengine/renderer/graph/TargetPool.hppindex 6680be524..119e5b5e5 100644--- a/src/esengine/renderer/graph/TargetPool.hpp+++ b/src/esengine/renderer/graph/TargetPool.hpp@@ -77,6 +77,10 @@ public:FramebufferHandle framebufferOf(TargetHandle handle) const;TextureHandle textureOf(TargetHandle handle) const;+ /** The depth attachment, for a target that has one — an effect reading the+ * scene's depth samples this. Invalid when the shape carried no depth. */+ TextureHandle depthTextureOf(TargetHandle handle) const;+/*** @brief One tick of the clock every borrowed target is aged against.*diff --git a/src/esengine/renderer/store/MaterialConstants.hpp b/src/esengine/renderer/store/MaterialConstants.hppindex 45d388918..e6dbd5eaf 100644--- a/src/esengine/renderer/store/MaterialConstants.hpp+++ b/src/esengine/renderer/store/MaterialConstants.hpp@@ -25,4 +25,14 @@ inline constexpr const char* MATERIAL_CONSTANTS_BLOCK = "MaterialConstants";/** @brief First sampler unit a material texture parameter may use (batch owns units 0..7). */inline constexpr u32 MATERIAL_TEXTURE_UNIT_BASE = 8;+/**+ * @brief The unit a PostProcess pass reads the scene's DEPTH at.+ *+ * @details The top of the engine range on purpose: units 0 and 1 are the pass+ * input and the scene, and the loose-uniform path fills upward from 2,+ * so the last one is the only one nothing else can reach. A fullscreen+ * pass has no use for the batch's other units.+ */+inline constexpr u32 kSceneDepthUnit = 7;+} // namespace esenginediff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 4275a03fd..f98074553 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -218,6 +218,7 @@ void WebGPUDevice::releaseDeviceObjects() {group_layouts_.clear();dummy_ubo_ = BufferHandle{}; // the WGPUBuffer/WGPUTexture went with the maps abovedummy_texture_ = 0;+ dummy_depth_texture_ = 0;framebuffers_.clear();// Erase before release: aborting a pending map fires the callback, which must// miss the lookup rather than see a half-dead record.@@ -745,11 +746,11 @@ TextureHandle WebGPUDevice::createTexture(const TextureDesc& desc, const void* ptd.size = WGPUExtent3D{desc.width, desc.height, 1};td.mipLevelCount = 1;td.sampleCount = 1;- // Depth-stencil textures are attachment-only: writeTexture cannot fill them- // and the engine never samples its depth attachments. Color textures carry- // CopySrc so an offscreen target can serve the async readback seam.+ // Depth-stencil takes no upload and no readback (writeTexture cannot fill+ // it, CopySrc is refused on depth24plus) but IS sampled: an effect reads the+ // scene's depth. Colour carries CopySrc for the async readback seam.td.usage = isDepthFormat(td.format)- ? WGPUTextureUsage_RenderAttachment+ ? (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_RenderAttachment): (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst |WGPUTextureUsage_CopySrc | WGPUTextureUsage_RenderAttachment);@@ -759,8 +760,28 @@ TextureHandle WebGPUDevice::createTexture(const TextureDesc& desc, const void* preturn TextureHandle::Invalid;}+ WGPUTextureView view = wgpuTextureCreateView(texture, nullptr);+ // A depth-stencil texture has two aspects and a sample may name only one, so+ // the view a binding uses is depth-only. Every other format samples through+ // the view it already has — the two members alias, and cleanup knows it.+ WGPUTextureView sampleView = view;+ if (isDepthFormat(td.format)) {+ WGPUTextureViewDescriptor vd{};+ // The ASPECT's format, not the texture's: a depth-only view of a+ // depth24plus-stencil8 texture is a depth24plus view, and asking for it+ // under the combined format is rejected as incompatible.+ vd.format = td.format == WGPUTextureFormat_Depth24PlusStencil8+ ? WGPUTextureFormat_Depth24Plus+ : td.format;+ vd.dimension = WGPUTextureViewDimension_2D;+ vd.mipLevelCount = 1;+ vd.arrayLayerCount = 1;+ vd.aspect = WGPUTextureAspect_DepthOnly;+ sampleView = wgpuTextureCreateView(texture, &vd);+ }+const u32 id = next_id_++;- textures_[id] = TextureRec{texture, wgpuTextureCreateView(texture, nullptr),+ textures_[id] = TextureRec{texture, view, sampleView,desc.width, desc.height, td.format, desc.format,packSamplerKey(desc.minFilter, desc.magFilter,desc.wrapS, desc.wrapT)};@@ -826,7 +847,10 @@ TextureHandle WebGPUDevice::createCompressedTexture(const TextureDesc& desc, Gfx}const u32 id = next_id_++;- textures_[id] = TextureRec{texture, wgpuTextureCreateView(texture, nullptr),+ // A compressed texture is never a depth one, so it samples through the view+ // it already has — the two members alias, as they do for any colour format.+ WGPUTextureView view = wgpuTextureCreateView(texture, nullptr);+ textures_[id] = TextureRec{texture, view, view,desc.width, desc.height, wgpuFmt, desc.format,packSamplerKey(desc.minFilter, desc.magFilter,desc.wrapS, desc.wrapT)};@@ -847,6 +871,12 @@ TextureHandle WebGPUDevice::importExternalTexture(u32 nativeId, const TextureDesvoid WebGPUDevice::deleteTexture(TextureHandle texture) {auto it = textures_.find(static_cast<u32>(texture));if (it == textures_.end()) return;+ // The sample view first, and only when it is a view of its own: for a colour+ // texture it aliases `view`, and releasing that twice frees a live object.+ if (it->second.sampleView && it->second.sampleView != it->second.view) {+ evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(it->second.sampleView)));+ wgpuTextureViewRelease(it->second.sampleView);+ }if (it->second.view) {evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(it->second.view)));wgpuTextureViewRelease(it->second.view);@@ -974,6 +1004,8 @@ ShaderHandle WebGPUDevice::createProgram(const GfxShaderSource& source,scanWGSLBindingMask(source.fragmentSrc, 0);rec.group1Mask = scanWGSLBindingMask(source.vertexSrc, 1) |scanWGSLBindingMask(source.fragmentSrc, 1);+ rec.group1DepthMask = scanWGSLDepthTextureMask(source.vertexSrc, 1) |+ scanWGSLDepthTextureMask(source.fragmentSrc, 1);if (!rec.vertex || !rec.fragment) {if (rec.vertex) wgpuShaderModuleRelease(rec.vertex);if (rec.fragment) wgpuShaderModuleRelease(rec.fragment);@@ -1096,7 +1128,8 @@ WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {// objects flushBindGroup builds bind groups against, so declared-but-// unbound bindings are legal (dummy backfill) and group compatibility// holds by identity.- pd.layout = pipelineLayoutFor(progIt->second.group0Mask, progIt->second.group1Mask);+ pd.layout = pipelineLayoutFor(progIt->second.group0Mask, progIt->second.group1Mask,+ progIt->second.group1DepthMask);pd.vertex.module = progIt->second.vertex;pd.vertex.entryPoint = sv("vs_main");pd.vertex.bufferCount = slotCount;@@ -1314,8 +1347,12 @@ void WebGPUDevice::drawInternalClear(bool color, bool depth, bool stencil,bind_group_dirty_ = true;}-WGPUBindGroupLayout WebGPUDevice::groupLayoutFor(u32 group, u32 mask) {- const u64 key = (static_cast<u64>(group) << 32) | mask;+WGPUBindGroupLayout WebGPUDevice::groupLayoutFor(u32 group, u32 mask, u32 depthMask) {+ // depthMask is part of the key: the same bindings sampled as depth are a+ // DIFFERENT layout, and sharing one entry would bind a float texture under a+ // depth declaration.+ const u64 key = (static_cast<u64>(group) << 32) | mask+ ^ (static_cast<u64>(depthMask) << 48);auto cached = group_layouts_.find(key);if (cached != group_layouts_.end()) return cached->second;if (!device_) return nullptr;@@ -1345,7 +1382,9 @@ WGPUBindGroupLayout WebGPUDevice::groupLayoutFor(u32 group, u32 mask) {WGPUBindGroupLayoutEntry e{};e.binding = tb;e.visibility = WGPUShaderStage_Fragment;- e.texture.sampleType = WGPUTextureSampleType_Float;+ e.texture.sampleType = (depthMask & (1u << tb))+ ? WGPUTextureSampleType_Depth+ : WGPUTextureSampleType_Float;e.texture.viewDimension = WGPUTextureViewDimension_2D;entries[count++] = e;}@@ -1367,8 +1406,12 @@ WGPUBindGroupLayout WebGPUDevice::groupLayoutFor(u32 group, u32 mask) {return layout;}-WGPUPipelineLayout WebGPUDevice::pipelineLayoutFor(u32 group0Mask, u32 group1Mask) {- const u64 key = (static_cast<u64>(group1Mask) << 32) | group0Mask;+WGPUPipelineLayout WebGPUDevice::pipelineLayoutFor(u32 group0Mask, u32 group1Mask,+ u32 group1DepthMask) {+ // The depth mask changes the group-1 layout under this pipeline, so it has+ // to reach the key here too — see groupLayoutFor.+ const u64 key = ((static_cast<u64>(group1Mask) << 32) | group0Mask)+ ^ (static_cast<u64>(group1DepthMask) << 16);auto cached = pipeline_layouts_.find(key);if (cached != pipeline_layouts_.end()) return cached->second;if (!device_) return nullptr;@@ -1378,7 +1421,7 @@ WGPUPipelineLayout WebGPUDevice::pipelineLayoutFor(u32 group0Mask, u32 group1MasWGPUBindGroupLayout bgls[2];u32 count = 0;if (group0Mask != 0 || group1Mask != 0) bgls[count++] = groupLayoutFor(0, group0Mask);- if (group1Mask != 0) bgls[count++] = groupLayoutFor(1, group1Mask);+ if (group1Mask != 0) bgls[count++] = groupLayoutFor(1, group1Mask, group1DepthMask);WGPUPipelineLayoutDescriptor pld{};pld.bindGroupLayoutCount = count;@@ -1400,6 +1443,13 @@ void WebGPUDevice::ensureDummies() {TextureDesc td{};dummy_texture_ = static_cast<u32>(createTexture(td, white));}+ if (dummy_depth_texture_ == 0 || textures_.find(dummy_depth_texture_) == textures_.end()) {+ // Never written, only bound: a depth format takes no upload, and the+ // point is a texture of the right KIND under a declared depth binding.+ TextureDesc td{};+ td.format = GfxPixelFormat::Depth24Stencil8;+ dummy_depth_texture_ = static_cast<u32>(createTexture(td, nullptr));+ }}WGPUBindGroup WebGPUDevice::cachedBindGroup(u32 group, u32 mask, const u64* ids, u32 idCount,@@ -1484,6 +1534,9 @@ void WebGPUDevice::flushBindGroup() {if (prog->group1Mask != 0) {auto dummyIt = textures_.find(dummy_texture_);const TextureRec* dummy = (dummyIt != textures_.end()) ? &dummyIt->second : nullptr;+ auto depthDummyIt = textures_.find(dummy_depth_texture_);+ const TextureRec* depthDummy =+ (depthDummyIt != textures_.end()) ? &depthDummyIt->second : nullptr;WGPUBindGroupEntry texEntries[kTextureSlots * 2];u32 texCount = 0;@@ -1500,9 +1553,16 @@ void WebGPUDevice::flushBindGroup() {const u32 tb = textureBindingForUnit(unit);const u32 sb = samplerBindingForUnit(unit);if (prog->group1Mask & (1u << tb)) {+ // A depth declaration must be fed a depth texture even when the+ // unit is unbound: the white dummy under `sampleType = Depth` is+ // a validation error, not a blank sample.+ const bool wantsDepth = (prog->group1DepthMask & (1u << tb)) != 0;+ const TextureRec* src = rec;+ if (wantsDepth && !isDepthFormat(src->format)) src = depthDummy;+ if (!src) continue;WGPUBindGroupEntry e{};e.binding = tb;- e.textureView = rec->view;+ e.textureView = src->sampleView;texEntries[texCount++] = e;}if (prog->group1Mask & (1u << sb)) {@@ -1514,7 +1574,7 @@ void WebGPUDevice::flushBindGroup() {}WGPUBindGroupDescriptor tgd{};- tgd.layout = groupLayoutFor(1, prog->group1Mask);+ tgd.layout = groupLayoutFor(1, prog->group1Mask, prog->group1DepthMask);tgd.entryCount = texCount;tgd.entries = texEntries;u64 tids[kTextureSlots * 2];diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex dc69b2c6a..aa561980b 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -327,6 +327,10 @@ private:struct TextureRec {WGPUTexture texture = nullptr;WGPUTextureView view = nullptr; ///< Default full view, created with the texture.+ /// The view a SAMPLE binds. Depth-stencil textures cannot be sampled+ /// through an all-aspects view, so theirs is depth-only; for every other+ /// format this is `view` and is not released twice.+ WGPUTextureView sampleView = nullptr;u32 width = 0;u32 height = 0;WGPUTextureFormat format = WGPUTextureFormat_RGBA8Unorm;@@ -347,6 +351,8 @@ private:* so an unused declaration is as legal as in GLSL. */u32 group0Mask = 0;u32 group1Mask = 0;+ /// Which of group1Mask's bindings are `texture_depth_2d`.+ u32 group1DepthMask = 0;};struct PipelineRec {PipelineDesc desc;@@ -381,11 +387,11 @@ private:* are texture_2d/sampler pairs per the WebGPUMappings unit→binding* convention (engine units 0..7 at 0..7/8..15, material units 8..15* at 16..23/24..31). */- WGPUBindGroupLayout groupLayoutFor(u32 group, u32 mask);+ WGPUBindGroupLayout groupLayoutFor(u32 group, u32 mask, u32 depthMask = 0);/** @brief Returns the cached explicit pipeline layout for a program's masks.* A program with group-1 bindings but an empty group 0 still gets a* (zero-entry) group-0 layout, so group indices stay positional. */- WGPUPipelineLayout pipelineLayoutFor(u32 group0Mask, u32 group1Mask);+ WGPUPipelineLayout pipelineLayoutFor(u32 group0Mask, u32 group1Mask, u32 group1DepthMask = 0);/** @brief Lazily creates the dummy backfill resources: a zeroed uniform* buffer and a 1x1 white texture, standing in for declared-but-* unbound bindings (GL reads an unbound block/unit without@@ -563,6 +569,10 @@ private:std::unordered_map<u64, WGPUPipelineLayout> pipeline_layouts_;BufferHandle dummy_ubo_{}; ///< Zeroed backfill for declared-but-unbound UBO slots.u32 dummy_texture_ = 0; ///< 1x1 white backfill for declared-but-unbound units.+ /// The same for a depth unit: an RGBA8 dummy under a `sampleType = Depth`+ /// entry is a validation error, so a declared-but-unbound depth binding+ /// needs a depth texture to stand in.+ u32 dummy_depth_texture_ = 0;u32 next_id_ = 1;std::unordered_map<u32, BufferRec> buffers_;diff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hppindex 61f1c987d..db840088f 100644--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp@@ -402,6 +402,38 @@ inline u32 scanWGSLBindingMask(const char* source, u32 group) {return mask;}+/**+ * @brief Bit mask of the group's bindings a WGSL source declares as DEPTH textures.+ * @details A `texture_depth_2d` binding needs `sampleType = Depth` in its layout+ * entry and a depth-aspect view under it; bound as an ordinary float+ * texture WebGPU rejects the pipeline. Same source scan as+ * {@link scanWGSLBindingMask}, reading the declaration that follows.+ */+inline u32 scanWGSLDepthTextureMask(const char* source, u32 group) {+ if (!source) return 0;+ u32 mask = 0;+ for (const char* p = source; (p = std::strstr(p, "@group(")) != nullptr;) {+ p += 7;+ char* end = nullptr;+ const unsigned long g = std::strtoul(p, &end, 10);+ if (end == p) continue;+ p = end;+ if (g != group) continue;+ const char* b = std::strstr(p, "@binding(");+ if (!b) break;+ b += 9;+ const unsigned long idx = std::strtoul(b, &end, 10);+ if (end == b) continue;+ p = end;+ // The declaration this binding attributes: up to the `;` that ends it,+ // so a `texture_depth_2d` further down the file cannot be read as this one's.+ const char* semi = std::strchr(p, ';');+ const char* depth = std::strstr(p, "texture_depth_2d");+ if (idx < 32 && depth && (!semi || depth < semi)) mask |= (1u << idx);+ }+ return mask;+}+/// WriteBuffer's size (and offset) must be a 4-byte multiple; buffers are allocated/// rounded up so the slack exists. Callers supply exactly `size` bytes, so an/// unaligned size must be staged, never read up to `alignedWriteSize` in place.diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex b1ca6a917..e13bfcc66 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -13,6 +13,7 @@#include "ShaderParser.hpp"#include "../core/Log.hpp"+#include "../renderer/store/MaterialConstants.hpp"#include <sstream>#include <algorithm>@@ -766,10 +767,17 @@ const char* kTimeHeaderWGSL =// de-combined into texture_2d t0..t7 (bindings 0..7) + samplers s0..s7// (bindings 8..15) — the group-1 convention (WebGPUMappings). Bodies sample// `textureSampleLevel(t0, s0, uv, 0.0)` where GLSL reads u_textures[0].-std::string wgslBatchTextureDecls() {+std::string wgslBatchTextureDecls(bool postProcess) {std::string src;for (u32 i = 0; i < 8; ++i) {const std::string n = std::to_string(i);+ // A fullscreen pass reads the scene's DEPTH at the top engine unit, and a+ // depth texture is its own WGSL type with no sampler under it. PostProcess+ // only: unit 7 is an ordinary batch texture in every other domain.+ if (postProcess && i == kSceneDepthUnit) {+ src += "@group(1) @binding(" + n + ") var t" + n + " : texture_depth_2d;\n";+ continue;+ }src += "@group(1) @binding(" + n + ") var t" + n + " : texture_2d<f32>;\n";src += "@group(1) @binding(" + std::to_string(8 + i) + ") var s" + n + " : sampler;\n";}@@ -1340,7 +1348,7 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,// engine texture contract — fragment-only twins run under the batch// conventions (PostProcess reads its input/scene as t0/s0 and t1/s1).inject(parsed.domain == "PostProcess" ? wgslPPVSOut() : wgslCanonicalVSOut(lit));- inject(wgslBatchTextureDecls());+ inject(wgslBatchTextureDecls(parsed.domain == "PostProcess"));}inject(kFrameHeaderWGSL);inject(kTimeHeaderWGSL);diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 190568be0..6a7d1f68e 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -421,6 +421,14 @@ export const SCENES = [// Two quads crossing: one flat, one turned 60° about Y, so each is nearer on// one side. Painter's order cannot draw that — with `opaque` the halves resolve// by depth (left green, right red), and without it the later draw takes both.+ // Two quads of the SAME colour, one in front of the other: a luma Sobel has+ // nothing to find between them, so the edge in the middle of the frame came+ // from the scene's DEPTH or it came from nowhere.+ { id: "depth-outline", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/depth-outline.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/depth-outline.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2725,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.15,\"y\":0.5,\"rgb\":[204,51,51],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[204,51,51],\"tol\":20}]" } },+ // The same effect over a scene that writes no depth at all. Nothing to+ // find, so the frame must come out exactly as it went in — the picture is+ // identical to scale-sprites' own, probe for probe.+ { id: "depth-outline-flat", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/depth-outline-flat.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[230,102,26],\"tol\":20}]" } },{ id: "mesh-opaque", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-depth.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.58,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },{ id: "mesh-opaque-off", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":2,\"component\":\"MeshRenderer\",\"key\":\"opaque\",\"value\":false}", ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-depth.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.58,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40}]" } },// A normal map over FLAT normals: the quad faces the viewer, so without the map