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(gi): dynamic GI on the GPU - card lighting, 8x8 screen probes traced through the distance field, applied to the picture; no leak in the sealed room and 0.54-1.08 of Cycles in the lab rooms

yhhbc5443fb417b
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index 80d829d16..54d2d0172 100644
--- a/cmake/ESEngineSources.cmake
+++ b/cmake/ESEngineSources.cmake
@@ -113,6 +113,7 @@ if(ES_ENABLE_POSTPROCESS)
list(APPEND ESENGINE_SOURCES
${ESENGINE_ROOT}/src/esengine/renderer/frame/PostProcessPipeline.cpp
${ESENGINE_ROOT}/src/esengine/renderer/frame/VoxelGI.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/frame/DynamicGI.cpp
)
endif()
diff --git a/docs/GI_LUMEN_DESIGN.md b/docs/GI_LUMEN_DESIGN.md
index 9676a518e..47e0712eb 100644
--- a/docs/GI_LUMEN_DESIGN.md
+++ b/docs/GI_LUMEN_DESIGN.md
@@ -113,7 +113,7 @@
|---|---|---|
| P0 | 网格 SDF 烘焙 + `.esmeshsdf` 资源类型与加载器 + 全局距离场 clipmap + 公共 WGSL 追踪 | 球、盒、薄墙的距离和追踪与闭式解比对;WGSL 追踪由 `tools/gi/check-sdf-wgsl.mjs` 在无头 WebGPU 上校验。**已落地(2026-11-11)**:`pipeline/src/assets/meshSdf.ts`、`MeshSdfAssetLoader`、`sdk/src/gi/globalSdf.ts`;导入设置 `dynamicGI`(默认关)。**未做**:clipmap 接到渲染帧的网格实例、上传 GPU 存储缓冲、编辑器导入开关 |
| P1 | 表面缓存:card 烘焙、直接光 + 自发光、命中点取光 | 卡面亮度与 Lambert 闭式值一致,SDF 遮挡产生阴影,自发光出现在命中点取光里。**CPU 参考已落地(2026-11-11)**:`pipeline/src/assets/meshCards.ts`(`.esmeshcards`,6 个轴向 card)、`MeshCardsAssetLoader`、`sdk/src/gi/surfaceCache.ts`(`light`、`lookup`)、`pipeline/tests/surface-cache.test.ts`。**未做**:基色贴图不读(只用材质基色与顶点色)、图集分配、GPU 刷新通道 |
-| P2 | 屏幕探针 + SDF 追踪 + 时间/空间滤波,单次反弹 | `gi_leak` 为 0;`gi_room` 阴影区 0.6–1.1。**CPU 参考已落地并对 Cycles 验证(2026-11-11)**:`sdk/src/gi/screenProbes.ts`(8×8 八面体探针、半球积分、多次反弹迭代),`pipeline/tests/gi-lab.test.ts`。实测:`gi_leak` 室内最亮 0(体素 GI 为 0.005);`gi_room` 与 `gi_away` 为 Cycles 的 0.46–1.89 倍,屏幕内外一致(体素 GI 是 0.1–1.7 与 0.31–0.52)。**未做**:GPU 通道(探针追踪/插值到像素/时间滤波)、渲染帧实例接入;精度偏差(天花板 1.9、侧墙 0.5)主要来自 25 cm 的 card 和每探针 64 条光线 |
+| P2 | 屏幕探针 + SDF 追踪 + 时间/空间滤波,单次反弹 | `gi_leak` 为 0;`gi_room` 阴影区 0.6–1.1。**CPU 参考已落地并对 Cycles 验证(2026-11-11)**:`sdk/src/gi/screenProbes.ts`(8×8 八面体探针、半球积分、多次反弹迭代),`pipeline/tests/gi-lab.test.ts`。实测:`gi_leak` 室内最亮 0(体素 GI 为 0.005);`gi_room` 与 `gi_away` 为 Cycles 的 0.46–1.89 倍,屏幕内外一致(体素 GI 是 0.1–1.7 与 0.31–0.52)。**未做**:GPU 通道(探针追踪/插值到像素/时间滤波)、渲染帧实例接入;精度偏差(天花板 1.9、侧墙 0.5)主要来自 25 cm 的 card 和每探针 64 条光线 | **GPU 通道已落地(2026-11-11)**:`DynamicGI.cpp`(卡面光照、8×8 探针、应用三个 compute 通道)、`postprocess_setGIScene` 绑定、`dynamicGISystem.ts`(把 MeshRenderer 的内置立方体喂给 GPU)、后效 `dynamicGI`。无头 WebGPU(swiftshader)上对 Cycles 实测:`gi_leak` 室内 0;`gi_room` 阴影区 0.54–1.08(遮挡面 0.6,体素 GI 为 0.1);`gi_away` 0.54–0.86(体素 GI 为 0.31–0.52)。**未做**:材质自发光进 card(`gi_emissive` 为 0)、带 `.esmeshsdf/.esmeshcards` 的网格接入、多级 clipmap、点光/聚光、时间重投影、手机成本
| P3 | 表面缓存吃上一帧间接光(多次反弹)+ 世界辐射缓存 | `gi_room` 0.8–1.1;`gi_away` ≥ 0.8;`gi_emissive` ≥ 0.8 |
| P4 | 成本:自适应探针、光线预算、QualityConfig 档位、手机与桌面实测 | 帧时间达标;gate 内加成本断言(同阴影通道做法) |
| P5 | 编辑器:设置面板、调试视图(SDF、card、探针)、文档;`esengine/fx-gi` 分组与包体 | 编辑器检查;包体断言 |
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 3dbdf5f00..681bf8d60 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -124,6 +124,7 @@ export interface NativeEngineApi {
postprocess_resize?(width: number, height: number): void;
postprocess_setBypass?(bypass: boolean): void;
postprocess_setDisplayLut?(textureHandle: number, amount: number): void;
+ postprocess_setGIScene?(headerPtr: number, headerCount: number, sdfPtr: number, sdfCount: number, instancesPtr: number, instanceCount: number, pixelsPtr: number, pixelCount: number): boolean;
postprocess_setMsaaSamples?(samples: number): void;
postprocess_setOutputTransform?(transform: number): void;
postprocess_setOutputViewport?(x: number, y: number, w: number, h: number): void;
@@ -478,6 +479,7 @@ export function createNativeEngineApi(
bind('postprocess_resize', 'es_postprocess_resize', false);
bind('postprocess_setBypass', 'es_postprocess_setBypass', false);
bind('postprocess_setDisplayLut', 'es_postprocess_setDisplayLut', false);
+ bind('postprocess_setGIScene', 'es_postprocess_setGIScene', false);
bind('postprocess_setMsaaSamples', 'es_postprocess_setMsaaSamples', false);
bind('postprocess_setOutputTransform', 'es_postprocess_setOutputTransform', false);
bind('postprocess_setOutputViewport', 'es_postprocess_setOutputViewport', false);
diff --git a/sdk/src/gi/dynamicGISystem.ts b/sdk/src/gi/dynamicGISystem.ts
new file mode 100644
index 000000000..371c75e9f
--- /dev/null
+++ b/sdk/src/gi/dynamicGISystem.ts
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file dynamicGISystem.ts
+ * @brief Feeds the dynamic GI the scene (docs/GI_LUMEN_DESIGN.md): the instances in the world, composed and handed to the engine when they change.
+ *
+ * @details Runs only while a PostProcessVolume carries an enabled `dynamicGI` effect. What it sees of the scene is the MeshRenderers whose mesh
+ * is the built-in cube: each is a box of its world scale, with its colour, and a box needs no baked file (analyticBox). A mesh
+ * with a baked `.esmeshsdf` / `.esmeshcards` beside it is the next step; until then it is not in the GI's scene.
+ * The sun is the first enabled directional light.
+ *
+ * Composition is JavaScript work on the cells the instances touch and runs when the scene changes (a key of the instances'
+ * transforms and colours and the sun), not every frame.
+ */
+import type { App } from '../app/app';
+import { defineSystem } from '../ecs/system';
+import { Query } from '../ecs/query';
+import { MeshRenderer, Transform, Light, PostProcessVolume, type MeshRendererData, type TransformData, type LightData, type PostProcessVolumeData } from '../ecs/component';
+import { LightType } from '../wasm/wasm.generated';
+import { Assets } from '../asset/AssetPlugin';
+import type { Entity } from '../types';
+import { withScratch } from '../wasm/wasmScratch';
+import { analyticBox, packGPUScene, type GIInstance, type GILight } from './gpuScene';
+
+const CUBE = 100; // the built-in cube is 100 units across
+
+function matrixOf(t: TransformData): number[] {
+ const { x, y, z, w } = t.worldRotation, p = t.worldPosition;
+ return [
+ 1 - 2 * (y * y + z * z), 2 * (x * y + z * w), 2 * (x * z - y * w), 0,
+ 2 * (x * y - z * w), 1 - 2 * (x * x + z * z), 2 * (y * z + x * w), 0,
+ 2 * (x * z + y * w), 2 * (y * z - x * w), 1 - 2 * (x * x + y * y), 0,
+ p.x, p.y, p.z, 1,
+ ];
+}
+
+function wantsDynamicGI(volumes: Iterable<[Entity, PostProcessVolumeData]>): boolean {
+ for (const [, v] of volumes) {
+ for (const e of v.effects as Array<{ type: string; enabled?: boolean }>) if (e.type === 'dynamicGI' && e.enabled !== false) return true;
+ }
+ return false;
+}
+
+export function dynamicGISystem(app: App) {
+ let cube = 0, loading = false, lastKey = '';
+ return defineSystem(
+ [Query(MeshRenderer, Transform), Query(Light, Transform), Query(PostProcessVolume)],
+ (meshes: Iterable<[Entity, MeshRendererData, TransformData]>, lights: Iterable<[Entity, LightData, TransformData]>,
+ volumes: Iterable<[Entity, PostProcessVolumeData]>) => {
+ if (!wantsDynamicGI(volumes)) { lastKey = ''; return; }
+ const m = app.wasmModule;
+ if (!m?.postprocess_setGIScene) return;
+ if (cube === 0) {
+ if (!loading && app.hasResource(Assets)) {
+ loading = true;
+ const assets = app.getResource(Assets) as unknown as { loadTyped?(type: string, ref: string): Promise<{ handle: number }> };
+ void assets.loadTyped?.('mesh', 'builtin:cube').then((r) => { cube = r.handle; }, () => { loading = false; });
+ }
+ return;
+ }
+ let light: GILight | null = null;
+ for (const [, l, t] of lights) {
+ if (!l.enabled || l.intensity <= 0 || l.type !== LightType.Directional) continue;
+ const q = t.worldRotation;
+ const ax = -(2 * (q.x * q.z + q.w * q.y)), ay = -(2 * (q.y * q.z - q.w * q.x)), az = -(1 - 2 * (q.x * q.x + q.y * q.y));
+ const n = Math.hypot(ax, ay, az) || 1;
+ light = { toLight: [-ax / n, -ay / n, -az / n], radiance: [l.color.r * l.intensity, l.color.g * l.intensity, l.color.b * l.intensity] };
+ break;
+ }
+ const boxes: Array<{ matrix: number[]; size: [number, number, number]; colour: [number, number, number] }> = [];
+ let key = light ? `${light.toLight.join(',')}|${light.radiance.join(',')}` : 'dark';
+ for (const [, r, t] of meshes) {
+ if (!r.enabled || r.mesh !== cube) continue;
+ const s = t.worldScale, matrix = matrixOf(t);
+ const size: [number, number, number] = [s.x * CUBE, s.y * CUBE, s.z * CUBE];
+ const colour: [number, number, number] = [r.color.r, r.color.g, r.color.b];
+ boxes.push({ matrix, size, colour });
+ key += `|${matrix.slice(0, 3).concat(matrix.slice(12, 15)).map((v) => v.toFixed(3)).join(',')};${size.join(',')};${colour.join(',')}`;
+ }
+ if (key === lastKey || boxes.length === 0) return;
+ lastKey = key;
+ const extent = Math.max(...boxes.flatMap((b) => b.size));
+ const instances: GIInstance[] = boxes.map((b) => {
+ // A box of the field's own cell size: fine enough that a wall a tenth of a metre thick is still more than a cell.
+ const cell = Math.max(extent / 60, 1e-3);
+ const { cards, ...sdf } = analyticBox(b.size, b.colour, cell, extent / 20);
+ return { sdf, cards, worldFromLocal: b.matrix };
+ });
+ const scene = packGPUScene(instances, light);
+ if (!scene) return;
+ withScratch(m, (alloc) => {
+ const put = (data: ArrayBufferView): number => {
+ const ptr = alloc(data.byteLength);
+ m.HEAPU8.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), ptr);
+ return ptr;
+ };
+ m.postprocess_setGIScene!(put(scene.header), scene.header.length, put(scene.sdf), scene.sdf.length,
+ put(scene.instances), scene.instances.length, put(scene.pixels), scene.pixels.length);
+ });
+ },
+ { name: 'DynamicGISystem', runWhenPaused: true },
+ );
+}
diff --git a/sdk/src/gi/gpuScene.ts b/sdk/src/gi/gpuScene.ts
new file mode 100644
index 000000000..09acc12db
--- /dev/null
+++ b/sdk/src/gi/gpuScene.ts
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file gpuScene.ts
+ * @brief The scene as the dynamic GI's compute passes read it: the arrays handed to `postprocess_setGIScene` (src/esengine/renderer/frame/DynamicGI.hpp).
+ *
+ * @details Layouts (all little-endian numbers, the engine copies them as they are):
+ *
+ * header (floats) dim, cell, origin x y z (cells), reach, instances, card pixels, sun toLight x y z, sun on, sun radiance r g b,
+ * ray bias, ray range, card tolerance, sky r g b, hit fraction
+ * sdf dim^3 floats, toroidal like GlobalSdf's level
+ * instance (20 vec4 = 80 floats) 0-3 local to world (column major) | 4-6 world to local rows, w the translation, scale divided out |
+ * 7 world box min, w scale | 8 world box max, w card pixel size | 9 local box min, w emission scale | 10 local box max |
+ * 11-16 the six faces (width, height, first pixel) | 17-19 spare
+ * pixel (4 words) 0: depth16 | normal x i8 << 16 | normal y i8 << 24; 1: normal z i8 | albedo rgb << 8; 2: emission rgb; 3: instance << 3 | face
+ *
+ * The CPU twins (globalSdf.ts, surfaceCache.ts, screenProbes.ts) are checked against Cycles; the kernels are the same arithmetic.
+ */
+import { GlobalSdf, type SdfInstance } from './globalSdf';
+import { CARD_AXES, NO_DEPTH, type MeshCards } from './cardFormat';
+import type { MeshSdf } from './meshSdfFormat';
+
+export interface GIInstance {
+ sdf: MeshSdf;
+ cards: MeshCards;
+ /** Column-major 4x4, local to world: rotation, translation and one uniform scale. */
+ worldFromLocal: ArrayLike<number>;
+}
+
+export interface GILight {
+ /** Unit vector toward the sun. */
+ toLight: readonly [number, number, number];
+ radiance: readonly [number, number, number];
+}
+
+export interface GPUScene {
+ header: Float32Array;
+ sdf: Float32Array;
+ instances: Float32Array;
+ pixels: Uint32Array;
+}
+
+export const GI_HEADER_FLOATS = 24;
+export const GI_INSTANCE_FLOATS = 80;
+
+/** A box of the given size centred on the origin, as a distance field and as cards, without any mesh: what a primitive is to the GI. */
+export function analyticBox(size: readonly [number, number, number], colour: readonly [number, number, number], cell: number, cardCell: number, maxResolution = 24): GIInstance['sdf'] & { cards: MeshCards } {
+ const h = size.map((s) => s / 2);
+ const inflate = 0.5 * cell, pad = 2;
+ const dims = size.map((s) => Math.max(Math.ceil(s / cell), 1) + 2 * pad) as [number, number, number];
+ const origin = h.map((v) => -v - pad * cell) as [number, number, number];
+ const distance = new Float32Array(dims[0] * dims[1] * dims[2]);
+ for (let z = 0; z < dims[2]; z++) for (let y = 0; y < dims[1]; y++) for (let x = 0; x < dims[0]; x++) {
+ const q = [origin[0] + (x + 0.5) * cell, origin[1] + (y + 0.5) * cell, origin[2] + (z + 0.5) * cell].map((v, k) => Math.abs(v) - h[k]!);
+ const d = Math.hypot(Math.max(q[0]!, 0), Math.max(q[1]!, 0), Math.max(q[2]!, 0)) + Math.min(Math.max(q[0]!, q[1]!, q[2]!), 0);
+ distance[x + y * dims[0] + z * dims[0] * dims[1]] = d - inflate;
+ }
+ const cards: MeshCards = { aabbMin: h.map((v) => -v) as [number, number, number], aabbMax: h as [number, number, number], cell: cardCell, emissiveScale: 1, cards: [] };
+ const cap = Math.max(...size) / maxResolution, px = Math.max(cardCell, cap);
+ for (const { axis, sign, u, v } of CARD_AXES) {
+ const width = Math.max(1, Math.min(maxResolution, Math.ceil(size[u]! / px))), height = Math.max(1, Math.min(maxResolution, Math.ceil(size[v]! / px)));
+ const n = width * height, normal = new Int8Array(n * 3), albedo = new Uint8Array(n * 3);
+ for (let i = 0; i < n; i++) {
+ normal[i * 3 + axis] = 127 * sign;
+ for (let k = 0; k < 3; k++) albedo[i * 3 + k] = Math.round(Math.min(Math.max(colour[k]!, 0), 1) * 255);
+ }
+ cards.cards.push({ width, height, depth: new Uint16Array(n), normal, albedo, emissive: new Uint8Array(n * 3) });
+ }
+ return { dims, cell, origin, distance, inflate, cards };
+}
+
+const scaleOf = (m: ArrayLike<number>): number => Math.hypot(m[0]!, m[1]!, m[2]!);
+
+/** Composes the instances into one distance field window and lays everything out for the engine. */
+export function packGPUScene(instances: readonly GIInstance[], light: GILight | null, options: { dim?: number; sky?: readonly [number, number, number]; bias?: number } = {}): GPUScene | null {
+ if (instances.length === 0) return null;
+ const dim = options.dim ?? 128;
+ // The window covers the instances' boxes: the cell is the smallest power-free size that fits them, with the border a trace needs.
+ const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+ for (const inst of instances) {
+ const m = inst.worldFromLocal, { aabbMin, aabbMax } = inst.cards;
+ for (let c = 0; c < 8; c++) {
+ const l = [c & 1 ? aabbMax[0] : aabbMin[0], c & 2 ? aabbMax[1] : aabbMin[1], c & 4 ? aabbMax[2] : aabbMin[2]];
+ for (let k = 0; k < 3; k++) {
+ const w = m[k]! * l[0]! + m[4 + k]! * l[1]! + m[8 + k]! * l[2]! + m[12 + k]!;
+ min[k] = Math.min(min[k]!, w); max[k] = Math.max(max[k]!, w);
+ }
+ }
+ }
+ const extent = Math.max(max[0]! - min[0]!, max[1]! - min[1]!, max[2]! - min[2]!);
+ const cell = (extent * 1.15) / (dim - 4);
+ const sdf = new GlobalSdf([{ dim, cell }]);
+ sdf.setCenter([(min[0]! + max[0]!) / 2, (min[1]! + max[1]!) / 2, (min[2]! + max[2]!) / 2]);
+ instances.forEach((inst, id) => { const s: SdfInstance = { id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }; sdf.update(s); });
+ const level = sdf.levels[0]!;
+
+ const pixelTotal = instances.reduce((a, inst) => a + inst.cards.cards.reduce((b, c) => b + c.width * c.height, 0), 0);
+ const header = new Float32Array(GI_HEADER_FLOATS);
+ const instanceData = new Float32Array(instances.length * GI_INSTANCE_FLOATS);
+ const pixels = new Uint32Array(pixelTotal * 4);
+ let pixel = 0;
+ instances.forEach((inst, i) => {
+ const m = inst.worldFromLocal, scale = scaleOf(m), b = i * GI_INSTANCE_FLOATS, { cards } = inst;
+ for (let k = 0; k < 16; k++) instanceData[b + k] = m[k]!;
+ // World to local = (R^T (p - t)) / scale, with R = the matrix's columns over the scale.
+ for (let row = 0; row < 3; row++) {
+ for (let col = 0; col < 3; col++) instanceData[b + 16 + row * 4 + col] = m[row * 4 + col]! / (scale * scale);
+ instanceData[b + 16 + row * 4 + 3] = -(m[row * 4]! * m[12]! + m[row * 4 + 1]! * m[13]! + m[row * 4 + 2]! * m[14]!) / (scale * scale);
+ }
+ const wmin = [Infinity, Infinity, Infinity], wmax = [-Infinity, -Infinity, -Infinity];
+ for (let c = 0; c < 8; c++) {
+ const l = [c & 1 ? cards.aabbMax[0] : cards.aabbMin[0], c & 2 ? cards.aabbMax[1] : cards.aabbMin[1], c & 4 ? cards.aabbMax[2] : cards.aabbMin[2]];
+ for (let k = 0; k < 3; k++) {
+ const w = m[k]! * l[0]! + m[4 + k]! * l[1]! + m[8 + k]! * l[2]! + m[12 + k]!;
+ wmin[k] = Math.min(wmin[k]!, w); wmax[k] = Math.max(wmax[k]!, w);
+ }
+ }
+ for (let k = 0; k < 3; k++) { instanceData[b + 28 + k] = wmin[k]!; instanceData[b + 32 + k] = wmax[k]!; instanceData[b + 36 + k] = cards.aabbMin[k]!; instanceData[b + 40 + k] = cards.aabbMax[k]!; }
+ instanceData[b + 31] = scale;
+ instanceData[b + 35] = cards.cell;
+ instanceData[b + 39] = cards.emissiveScale;
+ cards.cards.forEach((card, face) => {
+ instanceData[b + 44 + face * 4] = card.width;
+ instanceData[b + 44 + face * 4 + 1] = card.height;
+ instanceData[b + 44 + face * 4 + 2] = pixel;
+ for (let j = 0; j < card.width * card.height; j++, pixel++) {
+ const o = pixel * 4, depth = card.depth[j]!;
+ const nx = card.normal[j * 3]! & 255, ny = card.normal[j * 3 + 1]! & 255, nz = card.normal[j * 3 + 2]! & 255;
+ pixels[o] = ((depth === NO_DEPTH ? 65535 : depth) | (nx << 16) | (ny << 24)) >>> 0;
+ pixels[o + 1] = (nz | (card.albedo[j * 3]! << 8) | (card.albedo[j * 3 + 1]! << 16) | (card.albedo[j * 3 + 2]! << 24)) >>> 0;
+ pixels[o + 2] = (card.emissive[j * 3]! | (card.emissive[j * 3 + 1]! << 8) | (card.emissive[j * 3 + 2]! << 16)) >>> 0;
+ pixels[o + 3] = ((i << 3) | face) >>> 0;
+ }
+ });
+ });
+
+ const bias = options.bias ?? Math.max(cell * 1.6, 0.5);
+ const set = (i: number, ...v: number[]) => { v.forEach((x, k) => { header[i + k] = x; }); };
+ set(0, dim, cell, level.origin[0]!, level.origin[1]!, level.origin[2]!, cell * GlobalSdf.REACH_CELLS, instances.length, pixelTotal);
+ set(8, ...(light?.toLight ?? [0, 1, 0]), light ? 1 : 0, ...(light?.radiance ?? [0, 0, 0]), bias, extent * 2.5, cell * 3);
+ set(18, ...(options.sky ?? [0, 0, 0]), 0.25);
+ return { header, sdf: level.data, instances: instanceData, pixels };
+}
diff --git a/sdk/src/postprocess/PostProcessPlugin.ts b/sdk/src/postprocess/PostProcessPlugin.ts
index ddfdd4af0..74b891850 100644
--- a/sdk/src/postprocess/PostProcessPlugin.ts
+++ b/sdk/src/postprocess/PostProcessPlugin.ts
@@ -18,6 +18,7 @@ import type { Entity } from '../types';
import { resolvedLightingSky } from './volumeSystem';
import { SkyEnvironment, skyParamsOf, skySunOf } from './skyEnvironment';
import { probeCaptureSystem } from './probeCapture';
+import { dynamicGISystem } from '../gi/dynamicGISystem';
/** Toward the sun from the first directional light that shines: the way the sky's shader finds it (the light's aim reversed). */
function sunFromLights(lights: Iterable<[Entity, LightData, TransformData]>): [number, number, number] | null {
@@ -86,6 +87,7 @@ export class PostProcessPlugin implements Plugin {
app.addSystemToSchedule(Schedule.PostUpdate, skyEnvironmentSystem(app, sky));
// After the sky: a volume filled at run time shows the sky that lights the scene where it sees it.
app.addSystemToSchedule(Schedule.PostUpdate, probeCaptureSystem(() => app.wasmModule, () => sky.panorama));
+ app.addSystemToSchedule(Schedule.PostUpdate, dynamicGISystem(app));
}
cleanup(app?: App): void {
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index f700ed489..e25b7f971 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -565,6 +565,21 @@ registerEffect({
],
});
+// Diffuse global illumination from the scene's distance field and surface cache (docs/GI_LUMEN_DESIGN.md): rays traced through the field,
+// the light of the surfaces they meet read from cards the engine keeps lit, probes of 8 x 8 pixels interpolated to the picture. Compute passes the
+// engine declares itself, so WebGPU only; the scene it traces is fed by sdk/src/gi/dynamicGISystem.ts. Leaves no light through a wall.
+registerEffect({
+ type: 'dynamicGI',
+ label: 'Dynamic GI',
+ native: 'dynamicGI',
+ uniforms: [
+ // How much of the gathered light is added over the picture.
+ { name: 'u_intensity', label: 'Intensity', min: 0, max: 4, step: 0.01, defaultValue: 1, neutralValue: 0 },
+ // How much of each frame replaces what the cards and probes held; lower is smoother and slower to follow a change.
+ { name: 'u_blend', label: 'Temporal Blend', min: 0.02, max: 1, step: 0.01, defaultValue: 0.3 },
+ ],
+});
+
// A compute effect on a device with a compute stage (WebGPU); a fragment pass of the same arithmetic stands in for it on one without (WebGL2).
registerEffect({
type: 'sharpen',
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 901aab6cb..2acbbc3e8 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -556,6 +556,7 @@ export interface ESEngineModule {
postprocess_addComputePass?(name: string, wgsl: string, params: string, workgroupX: number, workgroupY: number): number;
postprocess_supportsCompute?(): boolean;
postprocess_addNativePass?(name: string, kind: string): number;
+ postprocess_setGIScene?(headerPtr: number, headerCount: number, sdfPtr: number, sdfCount: number, instancesPtr: number, instanceCount: number, pixelsPtr: number, pixelCount: number): boolean;
postprocess_setPassScale(name: string, scale: number): void;
postprocess_setPassContinuesEffect(name: string): void;
postprocess_requestSkyCapture?(passName: string, width: number, height: number): void;
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index f08c1231f..b504981c9 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -7,6 +7,7 @@
#include "BoundarySpan.hpp"
#include "../renderer/rhi/GfxDevice.hpp"
#include "../renderer/frame/PostProcessPipeline.hpp"
+#include "../renderer/frame/DynamicGI.hpp"
#include "../renderer/frame/RenderContext.hpp"
#include "../renderer/frame/RenderFrame.hpp"
#include "../renderer/draw/ImmediateDraw.hpp"
@@ -87,6 +88,22 @@ u32 postprocess_addNativePass(const std::string& name, const std::string& kind)
return g_postProcessPipeline->addNativePass(name, kind);
}
+bool postprocess_setGIScene(uintptr_t headerPtr, u32 headerCount, uintptr_t sdfPtr, u32 sdfCount, uintptr_t instancesPtr, u32 instanceCount,
+ uintptr_t pixelsPtr, u32 pixelCount) {
+ const f32* header = boundarySpan<f32>(headerPtr, headerCount, "postprocess_setGIScene.header");
+ const f32* sdf = boundarySpan<f32>(sdfPtr, sdfCount, "postprocess_setGIScene.sdf");
+ const f32* instances = boundarySpan<f32>(instancesPtr, instanceCount, "postprocess_setGIScene.instances");
+ const u32* pixels = boundarySpan<u32>(pixelsPtr, pixelCount, "postprocess_setGIScene.pixels");
+ if (!header || !sdf || !instances || !pixels || headerCount < 22) return false;
+ DynamicGIScene& scene = dynamicGIScene();
+ scene.header.assign(header, header + headerCount);
+ scene.sdf.assign(sdf, sdf + sdfCount);
+ scene.instances.assign(instances, instances + instanceCount);
+ scene.pixels.assign(pixels, pixels + pixelCount);
+ ++scene.version;
+ return true;
+}
+
bool postprocess_supportsCompute() {
return g_postProcessPipeline ? g_postProcessPipeline->supportsCompute() : (g_device && g_device->supportsCompute());
}
diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hpp
index 7fb2d5e5f..e418633b7 100644
--- a/src/esengine/bindings/PostProcessBindings.hpp
+++ b/src/esengine/bindings/PostProcessBindings.hpp
@@ -26,6 +26,13 @@ bool postprocess_supportsCompute();
* @details On a device with no compute stage the pass is left out of the chain and the picture goes through as it was.
*/
u32 postprocess_addNativePass(const std::string& name, const std::string& kind);
+/**
+ * @brief Hands the dynamic GI the scene it traces: the header, the distance field, the instances and the card pixels, laid out as
+ * sdk/src/gi/gpuScene.ts writes them (see DynamicGI.hpp). The engine copies them; the pointers are free after the call.
+ * @return false when a count does not match what the header says.
+ */
+bool postprocess_setGIScene(uintptr_t headerPtr, u32 headerCount, uintptr_t sdfPtr, u32 sdfCount, uintptr_t instancesPtr, u32 instanceCount,
+ uintptr_t pixelsPtr, u32 pixelCount);
/** The project's multisampling request for the scene target; 1 = off. Clamped
* by what the device supports — the device answers capability, not policy. */
void postprocess_setMsaaSamples(u32 samples);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 1fefed055..ac33b3bba 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -607,6 +607,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("postprocess_addComputePass", &esengine::postprocess_addComputePass);
emscripten::function("postprocess_supportsCompute", &esengine::postprocess_supportsCompute);
emscripten::function("postprocess_addNativePass", &esengine::postprocess_addNativePass);
+ emscripten::function("postprocess_setGIScene", &esengine::postprocess_setGIScene);
emscripten::function("postprocess_setPassScale", &esengine::postprocess_setPassScale);
emscripten::function("postprocess_setPassContinuesEffect", &esengine::postprocess_setPassContinuesEffect);
emscripten::function("postprocess_requestSkyCapture", &esengine::postprocess_requestSkyCapture);
diff --git a/src/esengine/renderer/frame/DynamicGI.cpp b/src/esengine/renderer/frame/DynamicGI.cpp
new file mode 100644
index 000000000..cc28fa88b
--- /dev/null
+++ b/src/esengine/renderer/frame/DynamicGI.cpp
@@ -0,0 +1,659 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "./DynamicGI.hpp"
+#include "./RenderContext.hpp"
+#include "../rhi/GfxDevice.hpp"
+#include "../../core/Log.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+#include <string>
+
+namespace esengine {
+
+DynamicGIScene& dynamicGIScene() {
+ static DynamicGIScene scene;
+ return scene;
+}
+
+namespace {
+
+constexpr u32 kInstanceVec4 = 20;
+constexpr u32 kProbeSize = 8;
+constexpr u32 kProbeTexels = 3; // the vector that integrates a probe against a normal, one texel a colour channel
+
+/// The header the SDK writes (sdk/src/gi/gpuScene.ts), by index.
+enum Header : u32 {
+ kDim = 0, kCell, kOriginX, kOriginY, kOriginZ, kReach, kInstances, kPixels,
+ kSunX, kSunY, kSunZ, kSunOn, kSunR, kSunG, kSunB, kBias, kRange, kTolerance, kSkyR, kSkyG, kSkyB, kHit, kHeaderSize
+};
+
+struct ParamsBlock {
+ f32 sdf[4];
+ i32 origin[4];
+ u32 counts[4];
+ f32 sunDir[4];
+ f32 sunRad[4];
+ f32 trace[4];
+ f32 sky[4];
+};
+static_assert(sizeof(ParamsBlock) == 112, "the GI block is seven vec4s");
+
+#ifdef ES_ENABLE_WEBGPU
+// The CPU twin of what is here is in sdk/src/gi (globalSdf.ts sphereTrace, surfaceCache.ts lookup, screenProbes.ts tracePoint);
+// pipeline/tests/gi-lab.test.ts holds the twin to Cycles, and tools/gi/check-sdf-wgsl.mjs ran the trace of this on a GPU.
+//
+// An instance is 20 vec4: 0-3 the matrix local to world; 4-6 the rows of world to local (w the translation, the scale already divided
+// out); 7 the world box min and w the scale; 8 the world box max and w the card pixel size; 9 the local box min and w the emission
+// scale; 10 the local box max; 11-16 the six faces (width, height, first pixel in the card pixel array).
+const char* kCommon = R"WGSL(
+struct Frame { projection : mat4x4f, camera : vec4f, inverseViewProjection : mat4x4f, renderOrigin : vec4f };
+struct GI {
+ sdf : vec4f, // x: cells per axis, y: cell size, z: reach, w: intensity
+ origin : vec4i, // xyz: the window's first cell; w: the frame
+ counts : vec4u, // x: instances, y: card pixels, z: probe tiles x, w: probe tiles y
+ sunDir : vec4f, // xyz: toward the sun; w: 1 when there is one
+ sunRad : vec4f, // rgb: radiance; w: how far off a surface a ray starts
+ trace : vec4f, // x: how far a ray looks, y: card tolerance, z: blend, w: hit fraction of a cell
+ sky : vec4f, // rgb: what a ray that meets nothing brings
+};
+@group(0) @binding(0) var<uniform> frame : Frame;
+@group(0) @binding(1) var<uniform> gi : GI;
+@group(0) @binding(2) var<storage, read> sdfData : array<f32>;
+@group(0) @binding(3) var<storage, read> insts : array<vec4f>;
+@group(0) @binding(4) var<storage, read> cardPix : array<vec4u>;
+@group(0) @binding(5) var<storage, read> radIn : array<vec4f>;
+
+const PI : f32 = 3.14159265;
+
+fn cellValue(c : vec3i) -> f32 {
+ let d = i32(gi.sdf.x);
+ let w = c & vec3i(d - 1);
+ return sdfData[u32(w.x + w.y * d + w.z * d * d)];
+}
+fn sdfSample(p : vec3f) -> f32 {
+ let g = p / gi.sdf.y - vec3f(0.5);
+ let i0 = vec3i(floor(g));
+ let f = g - vec3f(i0);
+ let c000 = cellValue(i0);
+ let c100 = cellValue(i0 + vec3i(1, 0, 0));
+ let c010 = cellValue(i0 + vec3i(0, 1, 0));
+ let c110 = cellValue(i0 + vec3i(1, 1, 0));
+ let c001 = cellValue(i0 + vec3i(0, 0, 1));
+ let c101 = cellValue(i0 + vec3i(1, 0, 1));
+ let c011 = cellValue(i0 + vec3i(0, 1, 1));
+ let c111 = cellValue(i0 + vec3i(1, 1, 1));
+ return mix(mix(mix(c000, c100, f.x), mix(c010, c110, f.x), f.y), mix(mix(c001, c101, f.x), mix(c011, c111, f.x), f.y), f.z);
+}
+fn inField(p : vec3f) -> bool {
+ let c = p / gi.sdf.y - vec3f(gi.origin.xyz);
+ return all(c >= vec3f(1.0)) && all(c <= vec3f(gi.sdf.x - 1.0));
+}
+// Distance along dir to the first surface within maxT, or -1. A ray that starts inside a body hits at 0.
+fn sdfTrace(origin : vec3f, dir : vec3f, maxT : f32) -> f32 {
+ var t = 0.0;
+ let cell = gi.sdf.y;
+ for (var i = 0; i < 160; i = i + 1) {
+ if (t >= maxT) { return -1.0; }
+ let p = origin + dir * t;
+ if (!inField(p)) { return -1.0; }
+ let d = sdfSample(p);
+ if (d < cell * gi.trace.w) { return t; }
+ t = t + max(d, cell * 0.25);
+ }
+ return -1.0;
+}
+
+fn instBase(i : u32) -> u32 { return i * 20u; }
+fn faceAxes(face : u32) -> vec2u {
+ let axis = face / 2u;
+ if (axis == 0u) { return vec2u(1u, 2u); }
+ if (axis == 1u) { return vec2u(0u, 2u); }
+ return vec2u(0u, 1u);
+}
+fn comp(v : vec3f, k : u32) -> f32 { return select(select(v.z, v.y, k == 1u), v.x, k == 0u); }
+fn setComp(v : vec3f, k : u32, x : f32) -> vec3f {
+ var r = v;
+ if (k == 0u) { r.x = x; } else if (k == 1u) { r.y = x; } else { r.z = x; }
+ return r;
+}
+fn unpackNormal(w0 : u32, w1 : u32) -> vec3f {
+ let nx = f32(bitcast<i32>((w0 >> 16u) << 24u) >> 24u) / 127.0;
+ let ny = f32(bitcast<i32>((w0 >> 24u) << 24u) >> 24u) / 127.0;
+ let nz = f32(bitcast<i32>(w1 << 24u) >> 24u) / 127.0;
+ return vec3f(nx, ny, nz);
+}
+fn unpackColour(w : u32) -> vec3f {
+ return vec3f(f32(w & 255u), f32((w >> 8u) & 255u), f32((w >> 16u) & 255u)) / 255.0;
+}
+
+// What a ray brings back from the surface it hit at point, travelling along dir: the cards that face it, blended by how squarely each
+// does, from the pixel whose surface is within the tolerance of the point; of the instances that hold the point, the nearest wins.
+fn lookup(point : vec3f, dir : vec3f) -> vec3f {
+ var best = vec3f(0.0);
+ var bestError = 1e30;
+ let tol = gi.trace.y;
+ for (var i = 0u; i < gi.counts.x; i = i + 1u) {
+ let b = instBase(i);
+ let wmin = insts[b + 7u];
+ let wmax = insts[b + 8u];
+ if (any(point < wmin.xyz - vec3f(tol)) || any(point > wmax.xyz + vec3f(tol))) { continue; }
+ let r0 = insts[b + 4u]; let r1 = insts[b + 5u]; let r2 = insts[b + 6u];
+ let local = vec3f(dot(r0.xyz, point) + r0.w, dot(r1.xyz, point) + r1.w, dot(r2.xyz, point) + r2.w);
+ var d = vec3f(dot(r0.xyz, dir), dot(r1.xyz, dir), dot(r2.xyz, dir));
+ d = d / max(length(d), 1e-9);
+ let lmin = insts[b + 9u].xyz;
+ let lmax = insts[b + 10u].xyz;
+ let scale = wmin.w;
+ let cell = wmax.w;
+ var sum = vec3f(0.0);
+ var total = 0.0;
+ var error = 0.0;
+ for (var axis = 0u; axis < 3u; axis = axis + 1u) {
+ let da = comp(d, axis);
+ let weight = abs(da);
+ if (weight < 0.05) { continue; }
+ let face = axis * 2u + select(0u, 1u, da > 0.0);
+ let uv = faceAxes(face);
+ let lu = comp(local, uv.x); let lv = comp(local, uv.y);
+ if (lu < comp(lmin, uv.x) - cell || lu > comp(lmax, uv.x) + cell || lv < comp(lmin, uv.y) - cell || lv > comp(lmax, uv.y) + cell) { continue; }
+ let f = insts[b + 11u + face];
+ let fu = clamp((lu - comp(lmin, uv.x)) / max(comp(lmax, uv.x) - comp(lmin, uv.x), 1e-9), 0.0, 0.99999);
+ let fv = clamp((lv - comp(lmin, uv.y)) / max(comp(lmax, uv.y) - comp(lmin, uv.y), 1e-9), 0.0, 0.99999);
+ let px = u32(floor(fu * f.x));
+ let py = u32(floor(fv * f.y));
+ let idx = u32(f.z) + px + py * u32(f.x);
+ let pix = cardPix[idx];
+ let depth16 = pix.x & 0xffffu;
+ if (depth16 == 65535u) { continue; }
+ let ext = comp(lmax, axis) - comp(lmin, axis);
+ let sgn = face % 2u == 0u;
+ let la = comp(local, axis);
+ let pointDepth = select(la - comp(lmin, axis), comp(lmax, axis) - la, sgn);
+ let cardDepth = f32(depth16) / 65534.0 * ext;
+ let off = abs(cardDepth - pointDepth) * scale;
+ if (off > tol) { continue; }
+ error = max(error, off);
+ sum = sum + weight * radIn[idx].xyz;
+ total = total + weight;
+ }
+ if (total > 0.0 && error < bestError) { bestError = error; best = sum / total; }
+ }
+ return best;
+}
+
+fn hash3(a : u32, b : u32, c : u32) -> f32 {
+ var h = (a * 73856093u) ^ (b * 19349663u) ^ (c * 83492791u);
+ h = (h ^ (h >> 16u)) * 0x45d9f3bu;
+ h = h ^ (h >> 16u);
+ return f32(h) / 4294967296.0;
+}
+fn octahedral(u : f32, v : f32) -> vec3f {
+ let x = u * 2.0 - 1.0; let y = v * 2.0 - 1.0;
+ var p = vec2f(x, y);
+ let z = 1.0 - abs(x) - abs(y);
+ if (z < 0.0) { p = vec2f((1.0 - abs(y)) * select(-1.0, 1.0, x >= 0.0), (1.0 - abs(x)) * select(-1.0, 1.0, y >= 0.0)); }
+ return normalize(vec3f(p.x, p.y, z));
+}
+// One ray of a probe about normal n: the octahedral cell (i, j), jittered inside it, folded into n's hemisphere.
+fn probeRay(i : u32, j : u32, n : vec3f, seed : u32, frame : u32) -> vec3f {
+ let jx = hash3(i, j, seed * 31u + frame * 7u + 1u);
+ let jy = hash3(i, j, seed * 17u + frame * 13u + 2u);
+ var d = octahedral((f32(i) + jx) / 8.0, (f32(j) + jy) / 8.0);
+ let dn = dot(d, n);
+ if (dn < 0.0) { d = d - 2.0 * dn * n; }
+ return d;
+}
+// The light a ray from origin along d brings.
+fn rayRadiance(origin : vec3f, d : vec3f) -> vec3f {
+ let t = sdfTrace(origin, d, gi.trace.x);
+ if (t < 0.0) { return gi.sky.xyz; }
+ if (t < 0.001) { return vec3f(0.0); }
+ return lookup(origin + d * t, d);
+}
+)WGSL";
+
+const char* kCardLight = R"WGSL(
+@group(0) @binding(6) var<storage, read_write> radOut : array<vec4f>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id : vec3u) {
+ let p = id.x;
+ if (p >= gi.counts.y) { return; }
+ let pix = cardPix[p];
+ let depth16 = pix.x & 0xffffu;
+ if (depth16 == 65535u) { radOut[p] = vec4f(0.0); return; }
+ let instance = pix.w >> 3u;
+ let face = pix.w & 7u;
+ let b = instBase(instance);
+ let f = insts[b + 11u + face];
+ let idx = p - u32(f.z);
+ let w = u32(f.x);
+ let px = idx % w;
+ let py = idx / w;
+ let lmin = insts[b + 9u].xyz;
+ let lmax = insts[b + 10u].xyz;
+ let axis = face / 2u;
+ let uv = faceAxes(face);
+ var local = vec3f(0.0);
+ local = setComp(local, uv.x, comp(lmin, uv.x) + (f32(px) + 0.5) / f.x * (comp(lmax, uv.x) - comp(lmin, uv.x)));
+ local = setComp(local, uv.y, comp(lmin, uv.y) + (f32(py) + 0.5) / f.y * (comp(lmax, uv.y) - comp(lmin, uv.y)));
+ let depth = f32(depth16) / 65534.0 * (comp(lmax, axis) - comp(lmin, axis));
+ local = setComp(local, axis, select(comp(lmin, axis) + depth, comp(lmax, axis) - depth, face % 2u == 0u));
+ let m0 = insts[b]; let m1 = insts[b + 1u]; let m2 = insts[b + 2u]; let m3 = insts[b + 3u];
+ let pos = m0.xyz * local.x + m1.xyz * local.y + m2.xyz * local.z + m3.xyz;
+ let scale = insts[b + 7u].w;
+ let nl = unpackNormal(pix.x, pix.y);
+ let n = normalize((m0.xyz * nl.x + m1.xyz * nl.y + m2.xyz * nl.z) / scale);
+ let albedo = unpackColour(pix.y >> 8u);
+ let emissive = unpackColour(pix.z) * insts[b + 9u].w;
+
+ var direct = vec3f(0.0);
+ if (gi.sunDir.w > 0.5) {
+ let ndl = dot(n, gi.sunDir.xyz);
+ if (ndl > 0.0) {
+ let t = sdfTrace(pos + n * gi.sunRad.w, gi.sunDir.xyz, gi.trace.x);
+ if (t < 0.0) { direct = gi.sunRad.xyz * ndl; }
+ }
+ }
+ let origin = pos + n * gi.sunRad.w;
+ var sum = vec3f(0.0);
+ let frameIndex = u32(gi.origin.w);
+ for (var j = 0u; j < 8u; j = j + 1u) {
+ for (var i = 0u; i < 8u; i = i + 1u) {
+ let d = probeRay(i, j, n, p, frameIndex);
+ sum = sum + rayRadiance(origin, d) * dot(d, n);
+ }
+ }
+ let indirect = sum * (2.0 / 64.0);
+ let now = albedo * (direct + indirect) + emissive;
+ let blend = select(gi.trace.z, 1.0, gi.origin.w < 2);
+ radOut[p] = vec4f(mix(radIn[p].xyz, now, blend), 1.0);
+}
+)WGSL";
+
+const char* kSurface = R"WGSL(
+fn worldFromDepth(uv : vec2f, depth : f32) -> vec3f {
+ let clip = vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth, 1.0);
+ let world = frame.inverseViewProjection * clip;
+ return world.xyz / world.w;
+}
+fn decodeNormal(g : vec4f) -> vec3f {
+ let f = g.rg * 2.0 - 1.0;
+ var n = vec3f(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));
+ let k = clamp(-n.z, 0.0, 1.0);
+ n = vec3f(n.x + select(k, -k, n.x >= 0.0), n.y + select(k, -k, n.y >= 0.0), n.z);
+ return normalize(n);
+}
+fn viewDirection(p : vec3f) -> vec3f {
+ if (frame.camera.w > 0.5) { return normalize(frame.camera.xyz - p); }
+ return frame.camera.xyz;
+}
+)WGSL";
+
+// One workgroup is one probe: its 64 threads are the 64 rays, reduced to the vector V = 2/64 * sum(L d) per colour channel, with which
+// the diffuse light for any normal n is max(V.n, 0) (exact for the probe's own normal, and linear in n around it).
+const char* kProbe = R"WGSL(
+@group(0) @binding(6) var depthTex : texture_depth_2d;
+@group(0) @binding(7) var gbuffer : texture_2d<f32>;
+@group(0) @binding(8) var probeOut : texture_storage_2d<rgba16float, write>;
+@group(0) @binding(9) var probeHist : texture_2d<f32>;
+
+var<workgroup> shR : array<vec3f, 64>;
+var<workgroup> shG : array<vec3f, 64>;
+var<workgroup> shB : array<vec3f, 64>;
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(workgroup_id) wg : vec3u, @builtin(local_invocation_id) lid3 : vec3u, @builtin(local_invocation_index) lid : u32) {
+ let size = vec2i(textureDimensions(depthTex));
+ let t = min(vec2i(wg.xy) * 8 + vec2i(4), size - vec2i(1));
+ let depth = textureLoad(depthTex, t, 0);
+ let g = textureLoad(gbuffer, t, 0);
+ let valid = depth < 1.0 && g.a > 0.7;
+ var contribution = array<vec3f, 3>(vec3f(0.0), vec3f(0.0), vec3f(0.0));
+ var eyeDistance = 0.0;
+ if (valid) {
+ var n = decodeNormal(g);
+ let pos = worldFromDepth((vec2f(t) + 0.5) / vec2f(size), depth);
+ if (dot(n, viewDirection(pos)) < 0.0) { n = -n; }
+ eyeDistance = length(pos - frame.camera.xyz);
+ let d = probeRay(lid3.x, lid3.y, n, wg.x + wg.y * gi.counts.z, u32(gi.origin.w));
+ let L = rayRadiance(pos + n * gi.sunRad.w, d);
+ contribution = array<vec3f, 3>(d * L.x, d * L.y, d * L.z);
+ }
+ shR[lid] = contribution[0]; shG[lid] = contribution[1]; shB[lid] = contribution[2];
+ workgroupBarrier();
+ for (var s = 32u; s > 0u; s = s >> 1u) {
+ if (lid < s) { shR[lid] = shR[lid] + shR[lid + s]; shG[lid] = shG[lid] + shG[lid + s]; shB[lid] = shB[lid] + shB[lid + s]; }
+ workgroupBarrier();
+ }
+ if (lid == 0u) {
+ let k = 2.0 / 64.0;
+ var vr = shR[0] * k; var vg = shG[0] * k; var vb = shB[0] * k;
+ let base = vec2i(i32(wg.x) * 3, i32(wg.y));
+ // The last frames agree where the probe still looks at the same surface (its distance from the eye is the key, kept in w).
+ let hr = textureLoad(probeHist, base, 0);
+ if (valid && hr.w > 0.0 && abs(hr.w - eyeDistance) < 0.02 * eyeDistance && gi.origin.w > 1) {
+ let a = gi.trace.z;
+ vr = mix(textureLoad(probeHist, base, 0).xyz, vr, a);
+ vg = mix(textureLoad(probeHist, base + vec2i(1, 0), 0).xyz, vg, a);
+ vb = mix(textureLoad(probeHist, base + vec2i(2, 0), 0).xyz, vb, a);
+ }
+ textureStore(probeOut, base, vec4f(vr, eyeDistance));
+ textureStore(probeOut, base + vec2i(1, 0), vec4f(vg, 0.0));
+ textureStore(probeOut, base + vec2i(2, 0), vec4f(vb, 0.0));
+ }
+}
+)WGSL";
+
+const char* kApply = R"WGSL(
+@group(0) @binding(6) var depthTex : texture_depth_2d;
+@group(0) @binding(7) var gbuffer : texture_2d<f32>;
+@group(0) @binding(8) var albedoTex : texture_2d<f32>;
+@group(0) @binding(9) var probes : texture_2d<f32>;
+@group(0) @binding(10) var sceneTex : texture_2d<f32>;
+@group(0) @binding(11) var outTex : texture_storage_2d<rgba16float, write>;
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) id : vec3u) {
+ let size = vec2i(textureDimensions(depthTex));
+ let p = vec2i(id.xy);
+ if (p.x >= size.x || p.y >= size.y) { return; }
+ let scene = textureLoad(sceneTex, p, 0);
+ let depth = textureLoad(depthTex, p, 0);
+ let g = textureLoad(gbuffer, p, 0);
+ let albedo = textureLoad(albedoTex, p, 0);
+ if (depth >= 1.0 || g.a <= 0.7 || albedo.a <= 0.5) { textureStore(outTex, p, scene); return; }
+ var n = decodeNormal(g);
+ let pos = worldFromDepth((vec2f(p) + 0.5) / vec2f(size), depth);
+ if (dot(n, viewDirection(pos)) < 0.0) { n = -n; }
+ let tiles = vec2i(gi.counts.zw);
+ // The four probes round the pixel: probe (tx, ty) stands at pixel (tx * 8 + 4, ty * 8 + 4).
+ let q = (vec2f(p) - vec2f(4.0)) / 8.0;
+ let q0 = vec2i(floor(q));
+ let f = q - vec2f(q0);
+ var E = vec3f(0.0);
+ var total = 0.0;
+ var nearestE = vec3f(0.0);
+ var nearestW = -1.0;
+ for (var k = 0; k < 4; k = k + 1) {
+ let o = vec2i(k & 1, k >> 1);
+ let tile = clamp(q0 + o, vec2i(0), tiles - vec2i(1));
+ let pp = min(tile * 8 + vec2i(4), size - vec2i(1));
+ let pd = textureLoad(depthTex, pp, 0);
+ let pg = textureLoad(gbuffer, pp, 0);
+ if (pd >= 1.0 || pg.a <= 0.7) { continue; }
+ let ppos = worldFromDepth((vec2f(pp) + 0.5) / vec2f(size), pd);
+ var pn = decodeNormal(pg);
+ if (dot(pn, viewDirection(ppos)) < 0.0) { pn = -pn; }
+ let eye = max(length(pos - frame.camera.xyz), 1.0);
+ let plane = abs(dot(n, ppos - pos)) / (0.02 * eye);
+ let bilinear = select(1.0 - f.x, f.x, o.x == 1) * select(1.0 - f.y, f.y, o.y == 1);
+ let w = bilinear / (1.0 + plane * plane) * pow(max(dot(pn, n), 0.0), 8.0);
+ let base = vec2i(tile.x * 3, tile.y);
+ let vr = textureLoad(probes, base, 0).xyz;
+ let vg = textureLoad(probes, base + vec2i(1, 0), 0).xyz;
+ let vb = textureLoad(probes, base + vec2i(2, 0), 0).xyz;
+ let e = max(vec3f(dot(vr, n), dot(vg, n), dot(vb, n)), vec3f(0.0));
+ E = E + e * w;
+ total = total + w;
+ if (w > nearestW) { nearestW = w; nearestE = e; }
+ }
+ if (total > 1e-5) { E = E / total; } else { E = nearestE; }
+ textureStore(outTex, p, vec4f(scene.rgb + albedo.rgb * E * gi.sdf.w, scene.a));
+}
+)WGSL";
+#else
+const char* kCommon = "";
+const char* kCardLight = "";
+const char* kSurface = "";
+const char* kProbe = "";
+const char* kApply = "";
+#endif
+
+std::string join(const char* a, const char* b, const char* c = "") {
+ return std::string(a) + b + c;
+}
+
+} // namespace
+
+DynamicGI::DynamicGI(GfxDevice& device, RenderContext& context) : device_(device), context_(context) {}
+
+DynamicGI::~DynamicGI() {
+ release();
+}
+
+void DynamicGI::release() {
+ for (BufferHandle* b : {&params_, &sdf_, &instances_, &pixels_, &radiance_[0], &radiance_[1]}) {
+ if (*b != BufferHandle::Invalid) device_.deleteBuffer(*b);
+ *b = BufferHandle::Invalid;
+ }
+ for (TextureHandle& t : probes_) {
+ if (t != TextureHandle::Invalid) device_.deleteTexture(t);
+ t = TextureHandle::Invalid;
+ }
+ for (ComputeHandle* c : {&cardLight_, &probe_, &apply_}) {
+ if (*c != ComputeHandle::Invalid) device_.deleteCompute(*c);
+ *c = ComputeHandle::Invalid;
+ }
+ probeTilesX_ = probeTilesY_ = 0;
+ sdfBytes_ = instanceBytes_ = pixelBytes_ = radianceBytes_ = 0;
+ uploadedVersion_ = 0;
+ failed_ = false;
+}
+
+bool DynamicGI::ensure() {
+ if (failed_) return false;
+ if (!device_.supportsCompute()) return false;
+ if (params_ == BufferHandle::Invalid) {
+ params_ = device_.createBuffer({GfxBufferUsage::Uniform, sizeof(ParamsBlock), true}, GfxContent::transient(), nullptr);
+ if (params_ == BufferHandle::Invalid) { failed_ = true; return false; }
+ }
+ const auto make = [&](ComputeHandle& handle, const std::string& source, const char* name) {
+ if (handle != ComputeHandle::Invalid) return true;
+ std::string log;
+ handle = device_.createCompute(GfxComputeSource{GfxShaderLanguage::WGSL, source.c_str(), "main"}, &log);
+ if (handle == ComputeHandle::Invalid) {
+ ES_LOG_ERROR("DynamicGI: the {} kernel did not compile: {}", name, log);
+ failed_ = true;
+ return false;
+ }
+ return true;
+ };
+ return make(cardLight_, join(kCommon, kCardLight), "card light") && make(probe_, join(kCommon, kSurface, kProbe), "probe")
+ && make(apply_, join(kCommon, kSurface, kApply), "apply");
+}
+
+bool DynamicGI::upload() {
+ const DynamicGIScene& s = dynamicGIScene();
+ if (s.header.size() < kHeaderSize || s.sdf.empty() || s.instances.empty() || s.pixels.empty()) return false;
+ if (s.version == uploadedVersion_) return true;
+ const auto put = [&](BufferHandle& buffer, u32& have, const void* data, u32 bytes) {
+ bytes = std::max(bytes, 16u);
+ if (buffer == BufferHandle::Invalid || have != bytes) {
+ if (buffer != BufferHandle::Invalid) device_.deleteBuffer(buffer);
+ buffer = device_.createBuffer({GfxBufferUsage::Storage, bytes, false}, GfxContent::transient(), nullptr);
+ have = bytes;
+ }
+ if (buffer == BufferHandle::Invalid) return false;
+ device_.updateBuffer(buffer, 0, data, bytes);
+ return true;
+ };
+ if (!put(sdf_, sdfBytes_, s.sdf.data(), static_cast<u32>(s.sdf.size() * 4)) ||
+ !put(instances_, instanceBytes_, s.instances.data(), static_cast<u32>(s.instances.size() * 4)) ||
+ !put(pixels_, pixelBytes_, s.pixels.data(), static_cast<u32>(s.pixels.size() * 4))) {
+ ES_LOG_ERROR("DynamicGI: could not upload the scene");
+ failed_ = true;
+ return false;
+ }
+ pixelCount_ = static_cast<u32>(s.header[kPixels]);
+ // The radiance the cards hold: 16 bytes a pixel, two of them (this frame is written from the last), zeroed again on a new scene.
+ const u32 radianceBytes = std::max(pixelCount_ * 16u, 16u);
+ if (radianceBytes != radianceBytes_ || radiance_[0] == BufferHandle::Invalid) {
+ for (BufferHandle& r : radiance_) {
+ if (r != BufferHandle::Invalid) device_.deleteBuffer(r);
+ r = device_.createBuffer({GfxBufferUsage::Storage, radianceBytes, false}, GfxContent::transient(), nullptr);
+ }
+ radianceBytes_ = radianceBytes;
+ if (radiance_[0] == BufferHandle::Invalid || radiance_[1] == BufferHandle::Invalid) { failed_ = true; return false; }
+ }
+ std::vector<f32> zero(radianceBytes / 4, 0.0f);
+ for (BufferHandle r : radiance_) device_.updateBuffer(r, 0, zero.data(), radianceBytes);
+ frame_ = 0;
+ uploadedVersion_ = s.version;
+ return true;
+}
+
+bool DynamicGI::ensureProbes(u32 tilesX, u32 tilesY) {
+ if (probes_[0] != TextureHandle::Invalid && probeTilesX_ == tilesX && probeTilesY_ == tilesY) return true;
+ for (TextureHandle& t : probes_) {
+ if (t != TextureHandle::Invalid) device_.deleteTexture(t);
+ t = TextureHandle::Invalid;
+ }
+ TextureDesc desc;
+ desc.width = tilesX * kProbeTexels;
+ desc.height = tilesY;
+ desc.format = GfxPixelFormat::RGBA16F;
+ desc.minFilter = desc.magFilter = TextureFilter::Nearest;
+ desc.storage = true;
+ for (TextureHandle& t : probes_) t = device_.createTexture(desc, GfxContent::transient(), nullptr);
+ if (probes_[0] == TextureHandle::Invalid || probes_[1] == TextureHandle::Invalid) {
+ ES_LOG_ERROR("DynamicGI: could not allocate the probes");
+ return false;
+ }
+ probeTilesX_ = tilesX;
+ probeTilesY_ = tilesY;
+ return true;
+}
+
+rg::ResourceId DynamicGI::declare(rg::RenderGraph& graph, rg::ResourceId input, rg::ResourceId scene, const DynamicGIParams& params,
+ u32 width, u32 height) {
+ if (!ensure() || input == rg::kNoResource || scene == rg::kNoResource) return input;
+ if (!upload()) return input;
+ const u32 tilesX = (width + kProbeSize - 1) / kProbeSize, tilesY = (height + kProbeSize - 1) / kProbeSize;
+ if (!ensureProbes(tilesX, tilesY)) return input;
+
+ rg::TargetDesc token;
+ token.width = 1;
+ token.height = 1;
+ token.format = GfxPixelFormat::RGBA8;
+ token.storage = true;
+ token.linearFilter = false;
+ const DynamicGIParams p = params;
+
+ // The frame's constants for every pass: the scene's header and the effect's parameters.
+ const auto writeParams = [this, p]() {
+ const DynamicGIScene& s = dynamicGIScene();
+ const std::vector<f32>& h = s.header;
+ ParamsBlock b{};
+ b.sdf[0] = h[kDim]; b.sdf[1] = h[kCell]; b.sdf[2] = h[kReach]; b.sdf[3] = p.intensity;
+ b.origin[0] = static_cast<i32>(h[kOriginX]); b.origin[1] = static_cast<i32>(h[kOriginY]); b.origin[2] = static_cast<i32>(h[kOriginZ]);
+ b.origin[3] = static_cast<i32>(frame_);
+ b.counts[0] = static_cast<u32>(h[kInstances]); b.counts[1] = static_cast<u32>(h[kPixels]);
+ b.counts[2] = probeTilesX_; b.counts[3] = probeTilesY_;
+ b.sunDir[0] = h[kSunX]; b.sunDir[1] = h[kSunY]; b.sunDir[2] = h[kSunZ]; b.sunDir[3] = h[kSunOn];
+ b.sunRad[0] = h[kSunR]; b.sunRad[1] = h[kSunG]; b.sunRad[2] = h[kSunB]; b.sunRad[3] = h[kBias];
+ b.trace[0] = h[kRange]; b.trace[1] = h[kTolerance]; b.trace[2] = std::clamp(p.blend, 0.01f, 1.0f); b.trace[3] = h[kHit];
+ b.sky[0] = h[kSkyR]; b.sky[1] = h[kSkyG]; b.sky[2] = h[kSkyB];
+ device_.updateBuffer(params_, 0, &b, sizeof(b));
+ };
+
+ const rg::ResourceId lit = graph.createTarget(token);
+ {
+ rg::PassDesc pass;
+ pass.name = "dgi_cards";
+ pass.compute = true;
+ pass.dependencies = {scene};
+ pass.write = lit;
+ pass.execute = [this, writeParams](const rg::PassContext&) {
+ writeParams();
+ // This frame's lighting is written to one of the two buffers and read from the other.
+ const BufferHandle in = radiance_[frame_ & 1u], out = radiance_[(frame_ & 1u) ^ 1u];
+ const GfxComputeBinding bindings[7] = {
+ GfxComputeBinding::uniform(0, context_.frameUbo()),
+ GfxComputeBinding::uniform(1, params_),
+ GfxComputeBinding::storageRead(2, sdf_),
+ GfxComputeBinding::storageRead(3, instances_),
+ GfxComputeBinding::storageRead(4, pixels_),
+ GfxComputeBinding::storageRead(5, in),
+ GfxComputeBinding::storage(6, out),
+ };
+ device_.dispatchCompute(cardLight_, bindings, 7, (pixelCount_ + 63) / 64);
+ };
+ graph.addPass(std::move(pass));
+ }
+
+ const rg::ResourceId probed = graph.createTarget(token);
+ {
+ rg::PassDesc pass;
+ pass.name = "dgi_probes";
+ pass.compute = true;
+ pass.dependencies = {scene, lit};
+ pass.write = probed;
+ pass.execute = [this, &graph, scene](const rg::PassContext&) {
+ const TextureHandle depth = graph.depthTextureOf(scene);
+ const TextureHandle gbuffer = graph.gbufferTextureOf(scene);
+ if (depth == TextureHandle::Invalid || gbuffer == TextureHandle::Invalid) return;
+ // The cards were just written into the buffer the next frame reads: the probes see this frame's lighting.
+ const BufferHandle cards = radiance_[(frame_ & 1u) ^ 1u];
+ const u32 cur = frame_ & 1u;
+ const GfxComputeBinding bindings[10] = {
+ GfxComputeBinding::uniform(0, context_.frameUbo()),
+ GfxComputeBinding::uniform(1, params_),
+ GfxComputeBinding::storageRead(2, sdf_),
+ GfxComputeBinding::storageRead(3, instances_),
+ GfxComputeBinding::storageRead(4, pixels_),
+ GfxComputeBinding::storageRead(5, cards),
+ GfxComputeBinding::depth(6, depth),
+ GfxComputeBinding::sampled(7, gbuffer),
+ GfxComputeBinding::storageTexture(8, probes_[cur]),
+ GfxComputeBinding::sampled(9, probes_[cur ^ 1u]),
+ };
+ device_.dispatchCompute(probe_, bindings, 10, probeTilesX_, probeTilesY_);
+ };
+ graph.addPass(std::move(pass));
+ }
+
+ rg::TargetDesc full;
+ full.format = GfxPixelFormat::RGBA16F;
+ full.storage = true;
+ full.linearFilter = true;
+ const rg::ResourceId result = graph.createTarget(full);
+ {
+ rg::PassDesc pass;
+ pass.name = "dgi_apply";
+ pass.compute = true;
+ pass.reads = {input};
+ pass.dependencies = {scene, probed};
+ pass.write = result;
+ pass.execute = [this, &graph, scene](const rg::PassContext& ctx) {
+ const TextureHandle depth = graph.depthTextureOf(scene);
+ const TextureHandle gbuffer = graph.gbufferTextureOf(scene);
+ const TextureHandle albedo = graph.albedoTextureOf(scene);
+ if (depth == TextureHandle::Invalid || gbuffer == TextureHandle::Invalid || albedo == TextureHandle::Invalid
+ || ctx.output == TextureHandle::Invalid) return;
+ const u32 cur = frame_ & 1u;
+ const GfxComputeBinding bindings[12] = {
+ GfxComputeBinding::uniform(0, context_.frameUbo()),
+ GfxComputeBinding::uniform(1, params_),
+ GfxComputeBinding::storageRead(2, sdf_),
+ GfxComputeBinding::storageRead(3, instances_),
+ GfxComputeBinding::storageRead(4, pixels_),
+ GfxComputeBinding::storageRead(5, radiance_[0]),
+ GfxComputeBinding::depth(6, depth),
+ GfxComputeBinding::sampled(7, gbuffer),
+ GfxComputeBinding::sampled(8, albedo),
+ GfxComputeBinding::sampled(9, probes_[cur]),
+ GfxComputeBinding::sampled(10, ctx.input(0)),
+ GfxComputeBinding::storageTexture(11, ctx.output),
+ };
+ device_.dispatchCompute(apply_, bindings, 12, (ctx.width + 7) / 8, (ctx.height + 7) / 8);
+ ++frame_;
+ };
+ graph.addPass(std::move(pass));
+ }
+ return result;
+}
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/DynamicGI.hpp b/src/esengine/renderer/frame/DynamicGI.hpp
new file mode 100644
index 000000000..325c3c778
--- /dev/null
+++ b/src/esengine/renderer/frame/DynamicGI.hpp
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file DynamicGI.hpp
+ * @brief Diffuse global illumination from the scene's distance field and surface cache, run as compute passes (WebGPU).
+ *
+ * @details The design is docs/GI_LUMEN_DESIGN.md and the CPU reference is sdk/src/gi (globalSdf, surfaceCache, screenProbes), checked against
+ * Cycles in pipeline/tests/gi-lab.test.ts. This is the GPU form of that reference.
+ *
+ * What the scene is comes from script: the SDK composes the scene's distance field and lays out its surface cards, and hands
+ * them over through `setScene` (the bindings' gi_setScene) whenever they change. The engine keeps them in storage buffers and
+ * runs three passes a frame:
+ * card light every card pixel: the sun (shadowed by a ray through the field) plus the light 64 rays bring from the other
+ * cards, times its albedo, plus what it emits. Run every frame, it converges on many bounces.
+ * probe one probe per 8 x 8 pixels of the picture: 64 rays from the surface there through the field into the cards,
+ * reduced to the vector that integrates them against any normal (see kProbe).
+ * apply every pixel takes the light of the four probes around it, weighted by depth and normal, times its albedo.
+ * Needs a device with a compute stage; elsewhere the pass is left out of the chain, as the voxel GI is.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../graph/RenderGraph.hpp"
+#include "../rhi/GfxEnums.hpp"
+
+#include <glm/glm.hpp>
+#include <vector>
+
+namespace esengine {
+
+class GfxDevice;
+class RenderContext;
+
+/** What the effect is asked for, from the pass's uniforms. */
+struct DynamicGIParams {
+ /// How much of the gathered light is added over the picture.
+ f32 intensity = 1.0f;
+ /// How much of each frame's card lighting replaces what the card held (the rest is history, which is what smooths the noise).
+ f32 blend = 0.3f;
+};
+
+/**
+ * The scene as the SDK lays it out. All of it is plain numbers; the layouts are in DynamicGI.cpp (kLayout) and sdk/src/gi/gpuScene.ts.
+ */
+struct DynamicGIScene {
+ /// Header: sdf dim, cell size, origin x y z (cells), reach, instance count, card pixel count, sun (toLight xyz, on), sun radiance rgb, bias, range, tolerance, sky rgb.
+ std::vector<f32> header;
+ /// The distance field, dim^3 cells, toroidal.
+ std::vector<f32> sdf;
+ /// 64 floats an instance.
+ std::vector<f32> instances;
+ /// 4 words a card pixel.
+ std::vector<u32> pixels;
+ u32 version = 0;
+};
+
+/** The scene the next frame draws from; written by script through the bindings. */
+DynamicGIScene& dynamicGIScene();
+
+class DynamicGI {
+public:
+ DynamicGI(GfxDevice& device, RenderContext& context);
+ ~DynamicGI();
+
+ DynamicGI(const DynamicGI&) = delete;
+ DynamicGI& operator=(const DynamicGI&) = delete;
+
+ /** Declares the passes onto @p graph; returns the picture with the light added, or @p input when there is nothing to do. */
+ rg::ResourceId declare(rg::RenderGraph& graph, rg::ResourceId input, rg::ResourceId scene, const DynamicGIParams& params, u32 width, u32 height);
+
+ void release();
+
+private:
+ bool ensure();
+ bool upload();
+ bool ensureProbes(u32 tilesX, u32 tilesY);
+
+ GfxDevice& device_;
+ RenderContext& context_;
+ BufferHandle params_ = BufferHandle::Invalid;
+ BufferHandle sdf_ = BufferHandle::Invalid;
+ BufferHandle instances_ = BufferHandle::Invalid;
+ BufferHandle pixels_ = BufferHandle::Invalid;
+ BufferHandle radiance_[2] = {BufferHandle::Invalid, BufferHandle::Invalid};
+ u32 sdfBytes_ = 0, instanceBytes_ = 0, pixelBytes_ = 0, radianceBytes_ = 0;
+ TextureHandle probes_[2] = {TextureHandle::Invalid, TextureHandle::Invalid};
+ u32 probeTilesX_ = 0, probeTilesY_ = 0;
+ ComputeHandle cardLight_ = ComputeHandle::Invalid;
+ ComputeHandle probe_ = ComputeHandle::Invalid;
+ ComputeHandle apply_ = ComputeHandle::Invalid;
+ u32 uploadedVersion_ = 0;
+ bool failed_ = false;
+ u32 frame_ = 0;
+ u32 pixelCount_ = 0;
+};
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 58af295d4..eefb21d04 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -15,6 +15,7 @@
#include "../RenderOrigin.hpp"
#include "./RenderContext.hpp"
#include "./VoxelGI.hpp"
+#include "./DynamicGI.hpp"
#include "../rhi/GfxDevice.hpp"
#include "../store/MaterialConstants.hpp"
#include "../store/MaterialStore.hpp"
@@ -213,6 +214,7 @@ void PostProcessPipeline::shutdown() {
for (auto& [source, program] : compute_cache_) device_.deleteCompute(program);
compute_cache_.clear();
voxel_gis_.clear();
+ dynamic_gis_.clear();
if (compute_view_ubo_ != BufferHandle::Invalid) {
device_.deleteBuffer(compute_view_ubo_);
compute_view_ubo_ = BufferHandle::Invalid;
@@ -1324,6 +1326,25 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Res
if (passIsHighPrecision(pass)) writeDesc.format = GfxPixelFormat::RGBA16F;
if (!pass.nativeKind.empty()) {
// A pass the engine implements itself, in compute passes of its own that it declares onto the graph.
+ if (pass.nativeKind == "dynamicGI" && &passes == &passes_ && (scene_needs_depth_ || scene_gbuffer_) && scene_gbuffer_) {
+ const auto get = [&pass](const char* name, f32 fallback) {
+ const auto it = pass.floatUniforms.find(name);
+ return it != pass.floatUniforms.end() ? it->second : fallback;
+ };
+ DynamicGIParams gi;
+ gi.intensity = get("u_intensity", gi.intensity);
+ gi.blend = get("u_blend", gi.blend);
+ auto& cache = dynamic_gis_[temporalKey_];
+ if (!cache) {
+ if (dynamic_gis_.size() > 4) {
+ for (auto it = dynamic_gis_.begin(); it != dynamic_gis_.end(); ++it) {
+ if (it->first != temporalKey_) { dynamic_gis_.erase(it); break; }
+ }
+ }
+ dynamic_gis_[temporalKey_] = makeUnique<DynamicGI>(device_, context_);
+ }
+ input = dynamic_gis_[temporalKey_]->declare(*graph_, input, scene, gi, width_, height_);
+ }
if (pass.nativeKind == "voxelGI" && &passes == &passes_ && (scene_needs_depth_ || scene_gbuffer_) && scene_gbuffer_) {
const auto get = [&pass](const char* name, f32 fallback) {
const auto it = pass.floatUniforms.find(name);
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index fa4993c54..a705bcf15 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -33,6 +33,7 @@ class GfxDevice;
class RenderContext;
class Shader;
class VoxelGI;
+class DynamicGI;
namespace resource {
class ResourceManager;
@@ -641,6 +642,7 @@ private:
/// The voxel GI's cache lives here, across frames: what it has seen is the point of it. One per camera, since a cache is a
/// window around the eye and two eyes would take turns tearing each other's down.
std::unordered_map<u64, Unique<VoxelGI>> voxel_gis_;
+ std::unordered_map<u64, Unique<DynamicGI>> dynamic_gis_;
/// The size block a compute pass reads, one for all of them (each dispatch writes it just before it runs).
BufferHandle compute_view_ubo_ = BufferHandle::Invalid;
/// Declares one chain onto an already-begun graph and runs it, ending in the
diff --git a/tools/render-lab/gi_oracle.py b/tools/render-lab/gi_oracle.py
index 141b6490a..712f22463 100644
--- a/tools/render-lab/gi_oracle.py
+++ b/tools/render-lab/gi_oracle.py
@@ -30,6 +30,7 @@ RADIUS = 10
METHODS = {
'baked': {'BAKE': '1', 'BOUNCES': '8'},
'vgi': {'EFFECTS': json.dumps([{'type': 'voxelGI', 'enabled': True, 'uniforms': {}}])},
+ 'dgi': {'BACKEND': 'webgpu', 'HEADLESS_GPU': '1', 'EFFECTS': json.dumps([{'type': 'dynamicGI', 'enabled': True, 'uniforms': {}}])},
}
# The share of Cycles' light, per region, each method is allowed (measured 2026-11-11). A region the sun lights directly reads about 1 for all.
@@ -41,14 +42,19 @@ BANDS = {
('gi_room', 'vgi'): (0.10, 1.70),
('gi_away', 'vgi'): (0.25, 0.75),
('gi_emissive', 'vgi'): (0.05, 0.70),
+ ('gi_room', 'dgi'): (0.45, 1.25),
+ ('gi_away', 'dgi'): (0.45, 1.00),
+ ('gi_leak', 'dgi'): ('zero', 0.0005),
}
# Wrong today, on purpose written down: the lightmap baker has no notion of an emissive surface (tools/lightmap-wasm/kernel.cpp carries albedo
# and the sun, nothing that emits), so a room lit only by a glowing panel bakes black. The region shares are asserted to stay under this.
+# The dynamic GI (distance field + surface cache + probes; WebGPU, headless on swiftshader) is the one with no leak and no screen-only memory.
# Likewise the voxel method lets the sun through a sealed room's walls: its voxels are larger than a 10 cm wall, so one that holds the lit outside
# of a wall holds its dark inside too (with the sun taken out the room is exactly black). 0.005 linear, about 16 codes, in a room Cycles leaves black.
KNOWN_GAP = {
('gi_emissive', 'baked'): ('the lightmap baker does not light from emissive surfaces', 0.05),
('gi_leak', 'vgi'): ('the voxel method lets the sun through thin walls', 0.008),
+ ('gi_emissive', 'dgi'): ('the dynamic GI does not read the emissive colour of a material into its cards yet', 0.05),
}
diff --git a/tools/render-lab/shot.mjs b/tools/render-lab/shot.mjs
index 702080227..db53935c8 100644
--- a/tools/render-lab/shot.mjs
+++ b/tools/render-lab/shot.mjs
@@ -7,7 +7,7 @@ const web = process.argv[3];
const view = process.argv[4] ?? 'front';
const server = await serveHost(path.resolve(web));
const gpu = process.env.BACKEND === 'webgpu';
-const browser = await chromium.launch({ headless: !gpu && process.env.HEADED !== '1', args: gpu ? ['--enable-unsafe-webgpu', '--disable-gpu-sandbox', '--ignore-gpu-blocklist'] : ['--use-angle=d3d11', '--enable-webgl', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader'] });
+const browser = await chromium.launch({ ...(process.env.HEADLESS_GPU === '1' ? { channel: 'chromium' } : {}), headless: (gpu && process.env.HEADLESS_GPU === '1') || (!gpu && process.env.HEADED !== '1'), args: gpu ? (process.env.HEADLESS_GPU === '1' ? ['--enable-unsafe-webgpu', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--mute-audio'] : ['--enable-unsafe-webgpu', '--disable-gpu-sandbox', '--ignore-gpu-blocklist']) : ['--use-angle=d3d11', '--enable-webgl', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader'] });
const logs = [];
try {
const page = await browser.newPage({ viewport: { width: Number(process.env.W || 1280), height: Number(process.env.H || 720) }, deviceScaleFactor: 1 });