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
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.mdnew file mode 100644index 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`,还是两者长期并存?