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): a sampled depth can be put back in the world

yhhb06788a2b7bc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04d72b0ea..ea703db91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,33 @@ published separately; it ships inside the editor.
### Added
+- **A sampled depth can be put back in the world.** `FrameConstants` carries the
+ inverse of the matrix it already carries, and the injected shader header gains
+ `worldFromDepth(uv, depth)` in both languages. Depth-reading effects — fog,
+ depth of field, ambient occlusion — become ordinary shader work; before this a
+ sampled depth was a number with no length in it, which is why the one effect
+ that read depth compared raw samples as a RATIO instead of a distance.
+
+ The inverse uploaded is of the matrix the SHADER sees, not the engine's: what a
+ shader un-projects is the clip space its own device rasterised into. The GLSL
+ and WGSL helpers differ in exactly one line — GL clips z to [-1, 1] and WebGPU
+ to [0, 1] — because both draw the same screen triangle, where uv is the clip
+ position remapped and nothing else.
+
+- **`distanceFog`** — the first effect built on it, and the gate that holds it.
+ Fog is a DISTANCE, and the same depth sample is a metre away up close and a
+ hundred out; this un-projects twice, at the sample and at the near plane along
+ the same ray, so it needs no eye point and works under both projections.
+
+ Its pixel gate is the interesting part. Two of its four points are on the SAME
+ flat wall at ONE constant depth, where a 90-degree eye stands 1.41x further
+ from the frame's edge than from its centre — so an effect reading depth rather
+ than distance paints them alike, and the tolerance does not reach between them.
+ Verified by sabotage in both directions: measuring along z instead of along the
+ ray leaves the two quads passing and turns that one point red. webgl2, WebGPU
+ and the software rasterizer agree on all four to the byte.
+
+
- **`view.frameCanvas` — "Frame Design Screen" is a command now.** The viewport
has had the button since design mode shipped and nothing behind it, so the
command palette, a keybinding and a driver could all reach every other view
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 426195332..905d19134 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -134,10 +134,18 @@ Fifo 把每一帧量成刷新间隔的整数倍 —— 51 ms 和 1.7 ms 读作
「有游戏端到端认证了,但还没被拿来定级」。那是一次**读**,不是一次**建**。12 个
experimental 对创作者读起来是「大半个引擎没做完」,哪怕其中几个下面压着两个出货游戏。
-**一个便宜且已标好的改动。** `src/esengine/renderer/frame/FrameConstants.hpp` 只有
-`viewProjection`(相机位置是从它反解出来的),没有 near/far。fog 和 DOF 要线性深度。
-那个头文件自己写着「后面的成员往后追加不需要 std140 padding」。改完之后 SSAO / fog / DOF
-就都是普通 shader 活,不是引擎活。
+**~~一个便宜且已标好的改动~~ 已落地 2026-08-27。** `FrameConstants` 现在带上它自己那个
+矩阵的**逆**(不是 near/far —— 逆更通用:一个成员同时喂 fog、DOF、SSAO,而 near/far 只对
+透视成立)。注入头两侧都加了 `worldFromDepth(uv, depth)`,两边只差一行:GL 的 clip z 是
+[-1,1]、WebGPU 是 [0,1];xy 是共用的,因为两边画的是同一个屏幕三角形。
+
+**上传的是着色器看到的那个矩阵的逆**,不是引擎自己那份 —— 着色器反投影的是它自己的设备
+光栅化进去的那个 clip 空间。
+
+第一个消费者是 `distanceFog`,连着它的双后端像素门禁一起落地。门禁四个点里有两个在
+**同一面平墙**上、深度完全相同,而 90 度的眼睛离画面边缘比离中心远 1.41 倍 —— 一个读深度
+而不是读距离的实现会把这两点画成一样,容差够不到它们之间。双向 sabotage 验过:改成沿 z 量
+而不是沿射线量,两块方块照样过、那一个点变红。webgl2 / WebGPU / 软件光栅化器四个点逐字节一致。
## 5. 两处小的,但正在削弱「清单是真的」〔已落地 2026-08-27〕
@@ -154,6 +162,19 @@ experimental 对创作者读起来是「大半个引擎没做完」,哪怕其
「0.57 exit criteria」的清单下发的。一个存在理由就是「不让清单和检查漂移」的文件,
不能自己成为版本号的第二处来源。
+## 6. 一个既有的红:`sprite-seam-off` 在 webgpu 上
+
+2026-08-27 发现。`node tools/verify-render.mjs --backend webgpu` 是 108/109,唯一的红是
+`sprite-seam-off`:seam ratio **1.6832844574779984**,要求 ≥ 2.5,而且**每次都是同一个数**
+(不是抖动)。把引擎改动 stash 掉重建后是**同一个数**,所以它不是这次改出来的。
+
+**为什么它一直没人管**:本地 `pnpm verify` 不跑像素门禁,而像素门禁的 webgpu 那一半只有
+本机有真适配器时才跑得动(CI runner 没有)。所以这是一个「没有任何东西在采样它」的洞 ——
+和 [[gates-cannot-see-what-they-do-not-sample]] 同一类。webgl2 那边 111/111 全绿。
+
+查它的起点是 `2d-seams-three-mechanisms` 那条记录:内部误差 vs 边界误差能区分三种机制,
+而 `pixelPerfect` 只贴位置、不贴缩放。
+
## 明确不做的(省得重新评估)
- **shadow pass 变成声明的 pass。** 它本来要买的东西(可采样 depth、atlas 的生命周期)
diff --git a/examples/effects-gallery/assets/materials/dissolve.esshader b/examples/effects-gallery/assets/materials/dissolve.esshader
index 392624d67..8308b3ee5 100644
--- a/examples/effects-gallery/assets/materials/dissolve.esshader
+++ b/examples/effects-gallery/assets/materials/dissolve.esshader
@@ -40,7 +40,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0a687499da49fe50
-// assembled-hash: 7bc51eca6fb86039
+// assembled-hash: 568d4738969a1eda
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -49,6 +49,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -114,7 +115,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0a687499da49fe50
-// assembled-hash: 7bc51eca6fb86039
+// assembled-hash: 568d4738969a1eda
struct MaterialConstants {
u_progress: f32,
u_edgeColor: vec4<f32>,
@@ -125,6 +126,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/examples/effects-gallery/assets/materials/hit-flash.esshader b/examples/effects-gallery/assets/materials/hit-flash.esshader
index eef0f1c84..d706fedfb 100644
--- a/examples/effects-gallery/assets/materials/hit-flash.esshader
+++ b/examples/effects-gallery/assets/materials/hit-flash.esshader
@@ -25,7 +25,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 674537b45fb865fb
-// assembled-hash: bf2ee752bac0effb
+// assembled-hash: 99d7f7ea2ccf332b
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -34,6 +34,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -97,7 +98,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 674537b45fb865fb
-// assembled-hash: bf2ee752bac0effb
+// assembled-hash: 99d7f7ea2ccf332b
struct MaterialConstants {
u_flash: f32,
u_flashColor: vec4<f32>,
@@ -106,6 +107,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/examples/effects-gallery/assets/materials/outline.esshader b/examples/effects-gallery/assets/materials/outline.esshader
index 180c33f05..d6b8d3006 100644
--- a/examples/effects-gallery/assets/materials/outline.esshader
+++ b/examples/effects-gallery/assets/materials/outline.esshader
@@ -34,7 +34,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 7ed4f4686c6bfd8d
-// assembled-hash: f983bee1ae396aeb
+// assembled-hash: ef95e088165b545d
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -43,6 +43,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -106,7 +107,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 7ed4f4686c6bfd8d
-// assembled-hash: f983bee1ae396aeb
+// assembled-hash: ef95e088165b545d
struct MaterialConstants {
u_outlineColor: vec4<f32>,
u_outlineWidth: f32,
@@ -115,6 +116,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/examples/effects-gallery/assets/materials/pixelate.esshader b/examples/effects-gallery/assets/materials/pixelate.esshader
index f9fb954ea..b76830727 100644
--- a/examples/effects-gallery/assets/materials/pixelate.esshader
+++ b/examples/effects-gallery/assets/materials/pixelate.esshader
@@ -23,7 +23,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0c2fb4b31599ec7a
-// assembled-hash: d1e48ec6aa8015bd
+// assembled-hash: d93ca8d8cf534600
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -32,6 +32,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -94,7 +95,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0c2fb4b31599ec7a
-// assembled-hash: d1e48ec6aa8015bd
+// assembled-hash: d93ca8d8cf534600
struct MaterialConstants {
u_pixels: f32,
}
@@ -102,6 +103,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esshader b/examples/effects-gallery/assets/materials/uv-scroll.esshader
index 7502a83c9..3edfee4be 100644
--- a/examples/effects-gallery/assets/materials/uv-scroll.esshader
+++ b/examples/effects-gallery/assets/materials/uv-scroll.esshader
@@ -24,7 +24,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 301c5b2b73d966f3
-// assembled-hash: 7f98802590e57b54
+// assembled-hash: 4e56eee430ca22da
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -33,6 +33,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -95,7 +96,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 301c5b2b73d966f3
-// assembled-hash: 7f98802590e57b54
+// assembled-hash: 4e56eee430ca22da
struct TimeConstants {
u_time: vec4<f32>,
u_viewport: vec4<f32>,
@@ -108,6 +109,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
var<private> v_texCoord_1: vec2<f32>;
diff --git a/fixtures/scenes/depth-layers/opaque.esshader b/fixtures/scenes/depth-layers/opaque.esshader
index 78802ac21..ee2bc7537 100644
--- a/fixtures/scenes/depth-layers/opaque.esshader
+++ b/fixtures/scenes/depth-layers/opaque.esshader
@@ -24,7 +24,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 930787555114ce9c
-// assembled-hash: 93cd59afc700f3e6
+// assembled-hash: 70cacfe42f3b2a27
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -33,6 +33,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -89,10 +90,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 930787555114ce9c
-// assembled-hash: 93cd59afc700f3e6
+// assembled-hash: 70cacfe42f3b2a27
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/fixtures/scenes/distance-fog.esscene b/fixtures/scenes/distance-fog.esscene
new file mode 100644
index 000000000..474d5be6b
--- /dev/null
+++ b/fixtures/scenes/distance-fog.esscene
@@ -0,0 +1,172 @@
+{
+ "version": 4,
+ "name": "DistanceFog",
+ "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": 0,
+ "fov": 90,
+ "nearPlane": 0.1,
+ "farPlane": 1000,
+ "isActive": true,
+ "priority": 0
+ }
+ },
+ {
+ "type": "PostProcessVolume",
+ "data": {
+ "isGlobal": true,
+ "priority": 0,
+ "weight": 1,
+ "effects": [
+ {
+ "type": "distanceFog",
+ "enabled": true,
+ "uniforms": {
+ "u_fogNear": 150,
+ "u_fogFar": 700,
+ "u_intensity": 1
+ }
+ }
+ ]
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Far",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -60,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 0.15,
+ "y": 0.15,
+ "z": 1
+ }
+ }
+ },
+ {
+ "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
+ },
+ "scale": {
+ "x": 0.15,
+ "y": 0.15,
+ "z": 1
+ }
+ }
+ },
+ {
+ "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": 3,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -150
+ },
+ "scale": {
+ "x": 5,
+ "y": 5,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "color": {
+ "r": 0.2,
+ "g": 0.7,
+ "b": 0.3,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true,
+ "opaque": true,
+ "mesh": "/scenes/textured-quad.esmesh"
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/mat-builtin-lit/lit.esshader b/fixtures/scenes/mat-builtin-lit/lit.esshader
index ab0404656..9b416dfed 100644
--- a/fixtures/scenes/mat-builtin-lit/lit.esshader
+++ b/fixtures/scenes/mat-builtin-lit/lit.esshader
@@ -27,7 +27,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 5330079245724fa2
-// assembled-hash: 31848f68bca90a99
+// assembled-hash: 416df6c37e7dcbce
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -36,6 +36,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -107,10 +108,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 5330079245724fa2
-// assembled-hash: 31848f68bca90a99
+// assembled-hash: 416df6c37e7dcbce
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct Light {
diff --git a/fixtures/scenes/mat-dissolve/dissolve.esshader b/fixtures/scenes/mat-dissolve/dissolve.esshader
index 392624d67..8308b3ee5 100644
--- a/fixtures/scenes/mat-dissolve/dissolve.esshader
+++ b/fixtures/scenes/mat-dissolve/dissolve.esshader
@@ -40,7 +40,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0a687499da49fe50
-// assembled-hash: 7bc51eca6fb86039
+// assembled-hash: 568d4738969a1eda
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -49,6 +49,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -114,7 +115,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0a687499da49fe50
-// assembled-hash: 7bc51eca6fb86039
+// assembled-hash: 568d4738969a1eda
struct MaterialConstants {
u_progress: f32,
u_edgeColor: vec4<f32>,
@@ -125,6 +126,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/fixtures/scenes/mat-graph/graph-tint.esshader b/fixtures/scenes/mat-graph/graph-tint.esshader
index d675cbee6..8ab803576 100644
--- a/fixtures/scenes/mat-graph/graph-tint.esshader
+++ b/fixtures/scenes/mat-graph/graph-tint.esshader
@@ -39,7 +39,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 5382212ba4021113
-// assembled-hash: 511cb30d250c2195
+// assembled-hash: 948218796d1bc56c
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -48,6 +48,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -112,7 +113,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 5382212ba4021113
-// assembled-hash: 511cb30d250c2195
+// assembled-hash: 948218796d1bc56c
struct MaterialConstants {
u_tint: vec4<f32>,
}
@@ -120,6 +121,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/fixtures/scenes/mat-lit-flatnormal/lit-fn.esshader b/fixtures/scenes/mat-lit-flatnormal/lit-fn.esshader
index 8bd5bb45b..1f60e4a09 100644
--- a/fixtures/scenes/mat-lit-flatnormal/lit-fn.esshader
+++ b/fixtures/scenes/mat-lit-flatnormal/lit-fn.esshader
@@ -47,7 +47,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: a8853729e0f76d55
-// assembled-hash: f77daff5647fc8c1
+// assembled-hash: ea3b72b665a606f0
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -56,6 +56,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -119,10 +120,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: a8853729e0f76d55
-// assembled-hash: f77daff5647fc8c1
+// assembled-hash: ea3b72b665a606f0
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct Light {
diff --git a/fixtures/scenes/mat-lit-normal/lit-normal.esshader b/fixtures/scenes/mat-lit-normal/lit-normal.esshader
index 46cea06a2..a3b9596c3 100644
--- a/fixtures/scenes/mat-lit-normal/lit-normal.esshader
+++ b/fixtures/scenes/mat-lit-normal/lit-normal.esshader
@@ -47,7 +47,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 577c1ff7b66006ff
-// assembled-hash: 6c873636f6370bde
+// assembled-hash: 9509ac04f870562e
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -56,6 +56,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -119,10 +120,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 577c1ff7b66006ff
-// assembled-hash: 6c873636f6370bde
+// assembled-hash: 9509ac04f870562e
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct Light {
diff --git a/fixtures/scenes/mat-lit/lit.esshader b/fixtures/scenes/mat-lit/lit.esshader
index 7a8cf29f0..45e4242d3 100644
--- a/fixtures/scenes/mat-lit/lit.esshader
+++ b/fixtures/scenes/mat-lit/lit.esshader
@@ -53,7 +53,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 8c118f2b442c055e
-// assembled-hash: 0ba8aa3b4cf73844
+// assembled-hash: 8e1e08bccdcce94f
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -62,6 +62,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -121,10 +122,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 8c118f2b442c055e
-// assembled-hash: 0ba8aa3b4cf73844
+// assembled-hash: 8e1e08bccdcce94f
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct Light {
diff --git a/fixtures/scenes/mat-sw/switched.esshader b/fixtures/scenes/mat-sw/switched.esshader
index 7aa823d7b..315603270 100644
--- a/fixtures/scenes/mat-sw/switched.esshader
+++ b/fixtures/scenes/mat-sw/switched.esshader
@@ -38,7 +38,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0ba3d3644597ce83
-// assembled-hash: a0520dbaf543ff35
+// assembled-hash: eb67150bbfaf17cb
#ifdef USE_GREEN
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
@@ -48,6 +48,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -100,6 +101,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -150,11 +152,12 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 0ba3d3644597ce83
-// assembled-hash: a0520dbaf543ff35
+// assembled-hash: eb67150bbfaf17cb
#ifdef USE_GREEN
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -186,6 +189,7 @@ fn fs_main(@location(0) v_color: vec4<f32>) -> @location(0) vec4<f32> {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/fixtures/scenes/mat-tex/masked.esshader b/fixtures/scenes/mat-tex/masked.esshader
index 6530d827d..1adff28c1 100644
--- a/fixtures/scenes/mat-tex/masked.esshader
+++ b/fixtures/scenes/mat-tex/masked.esshader
@@ -38,7 +38,7 @@ void main() {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 11b26db499fb2fc6
-// assembled-hash: a07ea4e1a5de3243
+// assembled-hash: 995c87fac03d97a3
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -47,6 +47,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -105,10 +106,11 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 11b26db499fb2fc6
-// assembled-hash: a07ea4e1a5de3243
+// assembled-hash: 995c87fac03d97a3
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/fixtures/scenes/mat-tint/tint.esshader b/fixtures/scenes/mat-tint/tint.esshader
index 4a52d597c..692585474 100644
--- a/fixtures/scenes/mat-tint/tint.esshader
+++ b/fixtures/scenes/mat-tint/tint.esshader
@@ -78,7 +78,7 @@ struct VSOut {
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 7be4a77f9921c078
-// assembled-hash: 60e4f729b9069a7a
+// assembled-hash: 153358b0bdd2ce6a
struct gl_PerVertex {
@builtin(position) gl_Position: vec4<f32>,
gl_PointSize: f32,
@@ -87,6 +87,7 @@ struct gl_PerVertex {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
@@ -147,7 +148,7 @@ fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>,
// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
// Regenerate after changing the GLSL stages above.
// source-hash: 7be4a77f9921c078
-// assembled-hash: 60e4f729b9069a7a
+// assembled-hash: 153358b0bdd2ce6a
struct MaterialConstants {
u_tint: vec4<f32>,
}
@@ -155,6 +156,7 @@ struct MaterialConstants {
struct FrameConstants {
u_projection: mat4x4<f32>,
u_camera: vec4<f32>,
+ u_inverseViewProjection: mat4x4<f32>,
}
struct TimeConstants {
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index cff5a455e..bc2434e62 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -189,6 +189,19 @@ registerEffect({
],
});
+registerEffect({
+ type: 'distanceFog',
+ label: 'Distance Fog',
+ factory: () => postProcessEffects.createDistanceFog(),
+ uniforms: [
+ { name: 'u_fogNear', label: 'Near', min: 0, max: 500, step: 0.5, defaultValue: 10 },
+ { name: 'u_fogFar', label: 'Far', min: 0, max: 500, step: 0.5, defaultValue: 60 },
+ { name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 1 },
+ ],
+ // u_fogColor keeps its shader default: EffectDef surfaces floats and textures,
+ // and a colour row is an editor surface of its own rather than part of this.
+});
+
registerEffect({
type: 'lutGrade',
label: 'LUT Grade',
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 433730d93..7a6cb6c29 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -745,6 +745,62 @@ fn depthAt(texel : vec2i, size : vec2i) -> f32 {
return Material.compileShader(source);
},
+ createDistanceFog(): ShaderHandle {
+ // Fog is a DISTANCE and a depth sample is not one: the same 0.9 is a
+ // metre away up close and a hundred out. `worldFromDepth` (injected with
+ // FrameConstants) puts the sample back in the world, so one setting holds.
+
+ // The cleared far plane is not a surface — it is the absence of one, and
+ // fogging it to full would paint the sky the fog colour at any range.
+ const source = `#pragma shader "PP Distance Fog"
+#pragma version 300 es
+#pragma domain PostProcess
+#pragma param u_fogColor color default(0.6,0.68,0.78,1)
+#pragma param u_fogNear float default(10) range(0,500)
+#pragma param u_fogFar float default(60) range(0,500)
+#pragma param u_intensity float default(1) range(0,1)
+
+#pragma fragment
+precision highp float;
+
+in vec2 v_texCoord;
+uniform sampler2D u_texture;
+uniform highp sampler2D u_sceneDepth;
+out vec4 fragColor;
+
+void main() {
+ vec4 src = texture(u_texture, v_texCoord);
+ float depth = texelFetch(u_sceneDepth, ivec2(gl_FragCoord.xy), 0).r;
+ if (depth >= 1.0) { fragColor = src; return; }
+
+ // Un-projected twice, at the sample and at the near plane along the SAME ray.
+ // An orthographic eye has no point to measure from, and this needs none: the
+ // near plane is one, per pixel, and it is where fog should start anyway.
+ vec3 world = worldFromDepth(v_texCoord, depth);
+ vec3 entry = worldFromDepth(v_texCoord, 0.0);
+ float dist = length(world - entry);
+ float t = clamp((dist - u_fogNear) / max(u_fogFar - u_fogNear, 1e-4), 0.0, 1.0);
+ fragColor = vec4(mix(src.rgb, u_fogColor.rgb, t * u_intensity), src.a);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+ let depth = textureLoad(t7, vec2i(v.pos.xy), 0);
+ if (depth >= 1.0) { return src; }
+
+ let world = worldFromDepth(v.v_texCoord, depth);
+ let entry = worldFromDepth(v.v_texCoord, 0.0);
+ let dist = length(world - entry);
+ let t = clamp((dist - mc.u_fogNear) / max(mc.u_fogFar - mc.u_fogNear, 1e-4), 0.0, 1.0);
+ return vec4f(mix(src.rgb, mc.u_fogColor.rgb, vec3f(t * 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/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hpp
index a6b22696e..e515fb26b 100644
--- a/src/esengine/renderer/frame/FrameConstants.hpp
+++ b/src/esengine/renderer/frame/FrameConstants.hpp
@@ -29,14 +29,21 @@ namespace esengine {
/**
* @brief CPU mirror of the GLSL FrameConstants block (std140).
- * @details A mat4 at offset 0 and a vec4 at 64 need no std140 padding. Append future
- * fields here and in ShaderParser's injected block in the same order.
- * camera: w = 1 means xyz is the eye's world position (perspective), w = 0
- * that xyz points at the viewer (orthographic has no eye point).
+ * @details A mat4 at 0, a vec4 at 64 and a mat4 at 80 need no std140 padding.
+ * Append future fields here and in ShaderParser's injected block in the
+ * same order. camera: w = 1 means xyz is the eye's world position
+ * (perspective), w = 0 that xyz points at the viewer.
*/
struct FrameConstants {
glm::mat4 viewProjection{1.0f};
glm::vec4 camera{0.0f, 0.0f, 1.0f, 0.0f};
+ /**
+ * The inverse of the matrix ABOVE, so a shader holding a depth sample can put
+ * it back in the world — of the UPLOADED one, since what a shader un-projects
+ * is the clip space its own device rasterised into. Without it a sampled
+ * depth is a number with no length in it.
+ */
+ glm::mat4 inverseViewProjection{1.0f};
};
/**
diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cpp
index 2ceb7c73c..1bf91698e 100644
--- a/src/esengine/renderer/frame/RenderContext.cpp
+++ b/src/esengine/renderer/frame/RenderContext.cpp
@@ -169,7 +169,10 @@ void RenderContext::updateFrameConstants(const glm::mat4& viewProjection) {
// to "where is the eye" that the rest of the engine also holds.
void RenderContext::uploadFrameConstants(const glm::mat4& upload, const glm::mat4& engine) {
viewProjection_ = engine;
- const FrameConstants frame{upload, cameraFromViewProjection(engine)};
+ // The viewpoint from `engine` and the un-projection from `upload`: the two
+ // agree about where the eye is, but only the uploaded one describes the clip
+ // space a shader will hand back.
+ const FrameConstants frame{upload, cameraFromViewProjection(engine), glm::inverse(upload)};
device_.updateBuffer(frameUbo_, 0, &frame, sizeof(FrameConstants));
// Re-arm the params fallback for this pass: a post-process or custom-draw
// commit from the previous pass left its own (differently sized) buffer on
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index e13bfcc66..3674a066f 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -752,11 +752,21 @@ const char* wgslTypeName(ShaderPropertyType t) {
// kTimeHeader's twin. Injected into every WGSL stage; the device's explicit
// layouts make a declared-but-unused block legal, same as GL.
const char* kFrameHeaderWGSL =
- "struct FrameConstants { projection : mat4x4f, camera : vec4f };\n"
+ "struct FrameConstants {\n"
+ " projection : mat4x4f,\n"
+ " camera : vec4f,\n"
+ " inverseViewProjection : mat4x4f,\n"
+ "};\n"
"@group(0) @binding(0) var<uniform> frame : FrameConstants;\n"
"fn viewDirection(worldPos : vec3f) -> vec3f {\n"
" if (frame.camera.w > 0.5) { return normalize(frame.camera.xyz - worldPos); }\n"
" return frame.camera.xyz;\n"
+ "}\n"
+ // The z line is the twin's whole difference: this device clips z to [0, 1].
+ "fn worldFromDepth(uv : vec2f, depth : f32) -> vec3f {\n"
+ " let clip = vec4f(uv * 2.0 - 1.0, depth, 1.0);\n"
+ " let world = frame.inverseViewProjection * clip;\n"
+ " return world.xyz / world.w;\n"
"}\n";
const char* kTimeHeaderWGSL =
@@ -1446,13 +1456,22 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// The per-frame view-projection, injected identically into every stage (a block
// declared two ways does not link) and engine-owned, so it cannot drift from the
// std140 mirror in FrameConstants.hpp. highp: fragment has no default this early.
+ // worldFromDepth takes the fullscreen pass's v_texCoord and a raw sample.
+ // `depth * 2 - 1` is the ONE thing its WGSL twin spells differently: GL clips
+ // z to [-1, 1], WebGPU to [0, 1]. The xy is shared — one screen triangle.
static const char* kFrameHeader =
"layout(std140) uniform FrameConstants {\n"
" highp mat4 u_projection;\n"
" highp vec4 u_camera;\n" // xyz = eye (w=1) or direction toward it (w=0)
+ " highp mat4 u_inverseViewProjection;\n"
"};\n"
"highp vec3 viewDirection(in highp vec3 worldPos) {\n"
" return u_camera.w > 0.5 ? normalize(u_camera.xyz - worldPos) : u_camera.xyz;\n"
+ "}\n"
+ "highp vec3 worldFromDepth(in highp vec2 uv, in highp float depth) {\n"
+ " highp vec4 clip = vec4(uv * 2.0 - 1.0, depth * 2.0 - 1.0, 1.0);\n"
+ " highp vec4 world = u_inverseViewProjection * clip;\n"
+ " return world.xyz / world.w;\n"
"}\n";
assembled << kFrameHeader;
headerLines += countNewlines(kFrameHeader);
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 825d2d68b..3d88da5c7 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -433,6 +433,10 @@ export const SCENES = [
// 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.
+ // The first two points are on the SAME flat wall at one constant depth, where
+ // a 90-degree eye is 1.41x further from the frame's edge than from its centre:
+ // an effect reading depth paints them alike, and tol 10 does not reach between.
+ { id: "distance-fog", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/distance-fog.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.5, \"y\": 0.5, \"rgb\": [107, 176, 143], \"tol\": 10}, {\"x\": 0.0625, \"y\": 0.5, \"rgb\": [134, 174, 176], \"tol\": 10}, {\"x\": 0.4375, \"y\": 0.5, \"rgb\": [190, 85, 92], \"tol\": 14}, {\"x\": 0.6875, \"y\": 0.5, \"rgb\": [200, 60, 62], \"tol\": 14}]" } },
{ 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}]" } },