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.

docs: design of the dynamic GI - global distance field, surface cache, screen probes, world radiance cache

yhh97620b310b12
diff --git a/docs/GI_LUMEN_DESIGN.md b/docs/GI_LUMEN_DESIGN.md
new file mode 100644
index 000000000..241e0d2e4
--- /dev/null
+++ b/docs/GI_LUMEN_DESIGN.md
@@ -0,0 +1,142 @@
+# 动态全局光照设计(Lumen 式,方案 B)
+
+状态:**设计稿,未开始实现**。写于 2026-11-11。第 1 节是已核对的现状和实测基线,第 2 节起是设计。
+
+## 1. 现状与基线(已核对)
+
+**已有**
+- 烘焙:光照贴图(`tools/lightmap-wasm/kernel.cpp`,`BakedLighting` 反弹和采样可调)和光探针体(`LightProbeVolume`,
+ `renderer/store/ProbeStore.hpp`,9 个球谐系数)。静态场景正确,不漏光。
+- 运行时:`voxelGI` 后效(`renderer/frame/VoxelGI.cpp`,约 800 行,四个 compute 通道:维护、注入、聚集、应用)。体素缓存
+ 128×64×128、随相机移动、环形寻址;光源只有**屏幕上的画面**和**太阳阴影图**,聚集用 DDA 在体素里走光线。需要 compute,
+ 即 WebGPU;WebGL2、小游戏没有。
+
+**没有**:距离场、网格 BVH、表面缓存(card)、屏幕探针、世界空间辐射缓存。引擎里搜不到任何一项。
+
+**实测基线**(`tools/render-lab/gi_oracle.py`,Cycles 12 次反弹为准,表中是引擎占 Cycles 光量的比例)
+
+| 场景 | 烘焙 | 体素 GI |
+|---|---|---|
+| `gi_room` 阴影区 | 0.75–1.00 | 0.10–1.70(遮挡面只有 0.1) |
+| `gi_away` 镜头外的墙 | 0.75–1.00 | 0.31–0.52 |
+| `gi_emissive` 自发光房间 | 0(烘焙器没有自发光) | 0.07–0.61 |
+| `gi_leak` 密闭房间(Cycles 为 0) | 0 | 约 0.005,体素 8 cm 时为 0 |
+
+漏光来源已定位:太阳注入(`u_sunAlbedo=0` 时恰好为 0),不是光线穿墙。试过的三个局部修补都没改变读数
+(见记忆 `oracle-render-scenes.md`)。**根因是缓存里没有几何**:缓存只知道“相机见过的表面在哪个体素”,
+不知道墙有多厚、墙后是什么。方案 B 就是补上几何。
+
+## 2. 目标与不做什么
+
+目标(以 `gi_oracle.py` 的带为验收,见第 7 节):
+1. 密闭房间不漏光(与 Cycles 一样为 0)。
+2. 镜头外的表面照样发出和接收间接光(`gi_away` 占比 ≥ 0.8)。
+3. 自发光表面照亮周围(`gi_emissive` ≥ 0.8)。
+4. 遮挡面的反弹占比 ≥ 0.7(现在 0.1)。
+5. 动态物体、动态太阳、动态灯即时生效,无需烘焙。
+
+不做:
+- 镜面全局反射与折射的追踪(第 2 期之后再评估,现有 SSR 和反射探针继续负责)。
+- WebGL2、小游戏上的动态 GI。这些设备继续用烘焙贴图和探针;新方案同样要求 compute。
+- 任意网格的实时硬件光追。
+
+## 3. 总体管线
+
+仿 Lumen 的四层,按 WebGPU compute 裁剪:
+
+```
+网格距离场(离线烘)──▶ 全局距离场(相机跟随的 3 级 clipmap)
+ │ 光线求交 / 遮挡
+表面缓存(card 图集)◀──────────┤ 命中点取光
+ 直接光 + 太阳阴影 + 自发光 + 上一帧间接光(多次反弹)
+ ▲
+屏幕探针(每 8×8 像素一个,八面体辐射)──▶ 滤波 ──▶ 应用到画面
+ 光线先走屏幕空间(HZB),再走全局距离场,最后落到世界辐射缓存
+世界辐射缓存(相机周围 clipmap 探针)──▶ 远处与未命中
+```
+
+### 3.1 网格距离场
+- 每个静态网格资源在导入时(pipeline,不在运行时)烘一张**带符号距离体**,分辨率按包围盒长边约 0.1 m 一格,上限 64³,单通道
+ fp16,和网格同生命周期(`.esmeshsdf` 旁路资源,进缓存预算,见 `docs/CACHE_BUDGET.md`)。
+- 地形用高度场单独表达(已有 `sampleHeight`),不烘体。
+- 动态网格(蒙皮)不入距离场,只作为 card 的光接收者与屏幕空间追踪的遮挡者(第 5 节取舍)。
+- 薄墙:导入时 SDF 取**无符号距离减半厚**,保证 10 cm 墙在 0.1 m 格下仍有负值内部;这正是体素缓存做不到的。
+
+### 3.2 全局距离场
+- 3 级 clipmap(例如 6 m / 24 m / 96 m,各 128³ 的 fp16 = 4 MB 一级),每级随相机按整格平移。
+- 每帧只更新**变脏的区域**:对象变换变化或进出窗口时,把覆盖该区域的网格 SDF 按 `min` 合成进去(compute,按 tile 分派)。
+- 查询接口两种:`sphereTrace(origin, dir, maxT)` 和 `occlusion(origin, target)`;统一放一个 WGSL 公共片段。
+
+### 3.3 表面缓存
+- 每个网格资源生成 6 个轴向 card(±x ±y ±z 正交投影),每张 card 在导入时烘:反照率、法线、自发光、深度(8 位到 16 位)。
+ 存成静态图集;运行时只增量刷新**光照**。
+- 运行时每张 card 一张 `radiance` 图集,分配器按屏幕占用和距离给 card 分配分辨率(类似 mip 流送)。每帧只刷新一小部分 card:
+ `直接光(平行光带现有阴影图、点光/聚光带现有阴影) + 自发光 + 上一帧间接光 × 反照率`。
+ 最后一项让缓存逐帧收敛到**多次反弹**,和现在体素缓存的做法一致,但存在 card 上而不是模糊的体素里。
+- 命中点取光:根据命中点法线选最多 3 个 card,按法线权重混合,深度测试去除背面。
+
+### 3.4 屏幕探针
+- 画面每 8×8 像素放一个探针(自适应:边缘和高频处补加密探针)。每个探针每帧发 64 条光线(八面体 8×8),重要性按上一帧亮度和
+ BRDF cos 加权。
+- 每条光线:先在屏幕空间用 HZB 走几步(命中就取画面色,和 SSR 共用 HZB);未命中则走全局距离场到命中点,取表面缓存;
+ 仍未命中(超出距离场范围或离开 clipmap)则读世界辐射缓存;最后读天空。
+- 结果写进探针的八面体图集,再做时间累积(速度重投影)与空间滤波,转成每像素的漫反射间接光(法线加权,深度加权)。
+
+### 3.5 世界辐射缓存
+- 相机周围 clipmap 的探针网格(例如 4 级,各 32³ 个探针,间距 0.5 m 起,每级翻倍),每个探针存低分辨率八面体辐射。
+- 作用:**屏幕外光源**(这就解决 `gi_away`)、远处光线的终点、屏幕探针的光线预算不足时的平滑后备。
+- 更新:每帧更新一部分探针,射线同样走全局距离场和表面缓存。
+
+## 4. 与现有系统的关系
+
+| 现有 | 处理 |
+|---|---|
+| `voxelGI` 后效 | 保留作 **WebGPU 低配后备**和过渡;新方案作为新后效 `dynamicGI`(分组 `esengine/fx-gi`,按用才打进包,见 AgX 的拆法)。两者互斥。 |
+| 烘焙光照贴图/探针 | 不变。静态烘焙优先:被烘焙的表面不再接收动态间接光,避免重复计算。 |
+| 阴影图(`kSun` 读回) | 表面缓存直接复用阴影图算直接光,**不再把阴影图读回写进体素**(漏光源头消失)。 |
+| SSR、SSAO、GTAO | 继续存在;HZB 共用。GTAO 仍负责接触阴影,GI 管大尺度。 |
+| `ReflectionProbe` | 不变,镜面部分仍由它负责。 |
+
+## 5. 取舍
+
+- **不做硬件光追**:WebGPU 没有。距离场追踪换来的是:薄结构精度差、小物体(< 1 格)丢失。接受,用屏幕空间追踪补细节。
+- **动态物体不进距离场**:蒙皮角色会没有间接遮挡,但仍接收间接光。后续可给角色加一个胶囊近似。
+- **card 内存**:6 个 card/网格,按需流送;小网格(包围盒 < 0.5 m)不生成 card,只贡献距离场。
+- **手机成本**:现有体素聚集在手机(Adreno/Vulkan)上曾因聚集里的 atomic 读耗时 1 秒以上,后改为只读数组(见 `VoxelGI.cpp` 注释)。新方案所有读都用只读数组;探针数量和光线数按 `QualityConfig.power` 缩放;
+ 目标:桌面 1080p ≤ 3 ms,手机 720p ≤ 6 ms(未验证,第 6 节每期实测后再改)。
+
+## 6. 分期
+
+每期独立可验收、可回退,期间旧 `voxelGI` 一直可用。
+
+| 期 | 内容 | 验收 |
+|---|---|---|
+| P0 | 网格 SDF 烘焙(pipeline)+ 全局距离场 clipmap + `sphereTrace`/`occlusion` 公共 WGSL | 新 oracle 场景:球、盒、薄墙的距离值和闭式解比对(`tools/oracle`);薄墙 10 cm 在 0.1 m 格下 `occlusion` 为真 |
+| P1 | 表面缓存:card 烘焙、图集分配、直接光 + 自发光刷新 | 卡面亮度与 `shade()` 参考一致;自发光面板出现在命中点取光里 |
+| P2 | 屏幕探针 + SDF 追踪 + 时间/空间滤波,单次反弹 | `gi_leak` 为 0;`gi_room` 阴影区 0.6–1.1 |
+| P3 | 表面缓存吃上一帧间接光(多次反弹)+ 世界辐射缓存 | `gi_room` 0.8–1.1;`gi_away` ≥ 0.8;`gi_emissive` ≥ 0.8 |
+| P4 | 成本:自适应探针、光线预算、QualityConfig 档位、手机与桌面实测 | 帧时间达标;gate 内加成本断言(同阴影通道做法) |
+| P5 | 编辑器:设置面板、调试视图(SDF、card、探针)、文档;`esengine/fx-gi` 分组与包体 | 编辑器检查;包体断言 |
+
+P0、P1 之间没有依赖,可并行;P2 依赖两者。
+
+## 7. 验证方式
+
+- 所有新带加进 `gi_oracle.py` 的 `BANDS`,并按它的约定:带是方法当前的精度,变差则失败,变好则提示收紧。
+- 几何层(P0)用 `tools/oracle` 的闭式场景:SDF 值是公式,不需要 Blender。
+- 每期完成后重跑基线表,把表更新进本文第 1 节。
+- 变异检验:关掉 SDF 遮挡,`gi_leak` 必须重新变红;关掉世界缓存,`gi_away` 必须掉出带。
+
+## 8. 风险
+
+1. **距离场精度**:薄墙、尖角、细柱在 0.1 m 格下会出错。缓解:导入时做保守化(薄结构向外膨胀半格),并提供按网格覆盖分辨率的选项。
+2. **更新成本**:大场景 clipmap 脏区过大。缓解:分帧、限预算,静态物体只在加载时合成。
+3. **探针噪点与闪烁**:Lumen 靠大量滤波才稳。缓解:先做固定 64 光线 + 时间累积,验证后再加自适应。
+4. **时间不确定**:这是多轮工程(P0–P5 每期至少一轮)。P0 做完前不要对外承诺“Lumen 级”。
+5. **WebGPU 兼容**:存储纹理格式、`rg16float` 等需确认;记忆 `webgpu-depth-sampling` 的几个坑(可采样深度附件)同样会碰到 HZB。
+
+## 9. 需要用户拍板的点
+
+1. P0 的 SDF 烘焙放在导入管线(推荐,运行时零成本),还是首次加载时运行时烘(省磁盘,首帧卡顿)?
+2. 动态物体第一版是否接受“只接收、不遮挡”?
+3. 新后效是否直接叫 `dynamicGI` 并在稳定后取代 `voxelGI`,还是两者长期并存?