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): a sampled depth can be put back in the world
yhhb06788a2b7bc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 viewporthas had the button since design mode shipped and nothing behind it, so thecommand palette, a keybinding and a driver could all reach every other viewdiff --git a/docs/ROADMAP.md b/docs/ROADMAP.mdindex 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.esshaderindex 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: 568d4738969a1edastruct 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: 568d4738969a1edastruct 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.esshaderindex 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: 99d7f7ea2ccf332bstruct 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: 99d7f7ea2ccf332bstruct 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.esshaderindex 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: ef95e088165b545dstruct 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: ef95e088165b545dstruct 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.esshaderindex 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: d93ca8d8cf534600struct 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: d93ca8d8cf534600struct 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.esshaderindex 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: 4e56eee430ca22dastruct 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: 4e56eee430ca22dastruct 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.esshaderindex 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: 70cacfe42f3b2a27struct 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: 70cacfe42f3b2a27struct 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.esscenenew file mode 100644index 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.esshaderindex 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: 416df6c37e7dcbcestruct 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: 416df6c37e7dcbcestruct 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.esshaderindex 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: 568d4738969a1edastruct 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: 568d4738969a1edastruct 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.esshaderindex 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: 948218796d1bc56cstruct 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: 948218796d1bc56cstruct 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.esshaderindex 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: ea3b72b665a606f0struct 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: ea3b72b665a606f0struct 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.esshaderindex 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: 9509ac04f870562estruct 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: 9509ac04f870562estruct 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.esshaderindex 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: 8e1e08bccdcce94fstruct 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: 8e1e08bccdcce94fstruct 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.esshaderindex 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_GREENstruct 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_GREENstruct 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.esshaderindex 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: 995c87fac03d97a3struct 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: 995c87fac03d97a3struct 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.esshaderindex 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: 153358b0bdd2ce6astruct 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: 153358b0bdd2ce6astruct 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.tsindex 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.tsindex 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-texeldiff --git a/src/esengine/renderer/frame/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hppindex 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.cppindex 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 ondiff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 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.mjsindex 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}]" } },