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.

feat(render): the scene's depth is something an effect can read

yhhac17f41a5b01
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 was
created 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 out
diff --git a/fixtures/scenes/depth-outline-flat.esscene b/fixtures/scenes/depth-outline-flat.esscene
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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-texel
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 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::PassContex
device->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.cpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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.hpp
index 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 esengine
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 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 above
dummy_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* p
td.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* p
return 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 TextureDes
void 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 group1Mas
WGPUBindGroupLayout 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.hpp
index 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.hpp
index 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.cpp
index 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.mjs
index 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