SPEEDBALL GI WebGPU Showcase（speedball-gi）项目源码解读

解读对象：https://github.com/norio/speedball-gi
解读结构：① 名称/作者/作用/背景 ② 安装与使用 ③ 工作流程与执行步骤 ④ 文件逐个解读 ⑤ 优势/不足/创新点
系列序号：本文为仓库源码解读系列第 16 篇。

1. 项目名称、作者及其介绍、作用与背景

1.1 名称与定位

1.2 作用

这是一个实时动态漫反射全局光照（DDGI，Dynamic Diffuse Global Illumination） 的 Three.js WebGPU 展示项目。它基于上游 speedball-gi（作者 cl0nazepamm，仓库 cl0nazepamm/speedball）这一 WebGPU DDGI + 局部反射库，搭建了三个互补的演示场景，用来直观呈现"世界空间探针体积（probe volume）如何对世界空间内的几何与光源做实时、可交互的间接光照"：

• Sponza：经典建筑场景（上游 Sponza 演示的 Vite 化改造），含程序化天空、方向太阳光、自动拟合的 DDGI、局部反射、探针调试、动画金属接收体。
• Afterimage Court（余像庭院）：轻量程序化柱廊，红墙绿墙 + 中央天窗步道，专为"方便对比间接颜色传递"而设计。
• Ball Pool（球池）：物理模拟 + 实例化球体，指针控制光源并推开附近小球，几何持续变化，用来观察动态几何下的 GI 实时更新；池宽与球数随视口自适应。

1.3 背景

• 技术背景：传统实时 GI 要么依赖昂贵的路径追踪，要么依赖屏幕空间（SSGI/SSAO）而缺乏世界空间一致性。DDGI（由 NVIDIA 在 2019 年提出）用稀疏规则探针网格存储辐照度/方向性，可在动态场景下实时重算。speedball-gi 进一步用 BVH 追踪（three-mesh-bvh） 做世界空间探针光线追踪，使其无需预烘焙。
• 项目背景：上游 cl0nazepamm/speedball 提供了 DDGI 实现与 Sponza 演示；norio 在此基础上用 Vite 重写入口，并新增两个聚焦测试场景 + 一套共享的 GI/后处理辅助模块 + 资源优化管线，作为"官方 Sponza 演示（WebGPU DDGI + Sky）适配 Vite"的样板。
• 致谢/来源（README Credits）：
  • speedball-gi 提供 WebGPU DDGI 与局部反射实现；
  • Sponza 场景改编自上游 SPEEDBALL GI 演示；
  • Ball Pool 概念基于 three.js 官方 WebGPU SSGI Ball Pool 示例，物理用 @perplexdotgg/bounce，世界空间间接光照用 SPEEDBALL GI。

2. 安装与使用教程、依赖的软件/硬件条件

2.1 软件依赖

2.2 运行时依赖（package.json）

"dependencies": {
  "@perplexdotgg/bounce": "^1.9.0",   // 刚体物理（球池）
  "lil-gui": "^0.21.0",               // 调试 GUI
  "speedball-gi": "^0.6.7",           // WebGPU DDGI + 局部反射核心库
  "stats-gl": "^4.2.3",               // 性能统计面板
  "three": "0.185.1",                 // Three.js（固定版本）
  "three-mesh-bvh": "0.9.14"          // GI 用到的 BVH 追踪
},
"devDependencies": { "vite": "^8.2.1" }

2.3 安装与启动

git clone https://github.com/norio/speedball-gi.git
cd speedball-gi
npm ci                      # 锁定版本安装
npm run dev                 # 启动 Vite 开发服务器（默认端口 5173）

打开 Vite 打印的 URL（通常 http://localhost:5173/speedball-gi/）即进入 Sponza。其余两个场景在同一源下：

• /speedball-gi/simple.html（Afterimage Court）
• /speedball-gi/ballpool.html（Ball Pool）

应用内左上角 HUD 也提供了三个场景的互相跳转链接。

2.4 其它可用脚本

2.5 部署

每次推送到 main，GitHub Actions（deploy-pages.yml）会 npm ci → npm test → npm run build，把 dist/ 部署到 GitHub Pages（项目路径 /speedball-gi/），在线演示地址：https://norio.github.io/speedball-gi/。

2.6 交互说明（来自 README Controls）

• Sponza：拖拽环绕、滚轮缩放；Sky/Sun 调太阳方向与大气；GI 调探针场/显示探针；Post 配 GTAO/TRAA/Bloom；Display 调色调映射、曝光、纹理可见性、DPR、帧率上限。相机或 GUI 静止后，空闲门控的探针求解才会收敛。
• Afterimage Court：拖拽/缩放；按 G 对比"仅直接光照 vs GI"；Court 文件夹调太阳强度与曝光；共享 GI/Post 文件夹。
• Ball Pool：指针移动控制灯光并推开附近小球；按住鼠标把球送回池顶（触屏用双指）；按 G 对比；"drop 20 balls" 立即重置一批。

3. 工作流程与具体执行步骤

3.1 核心集成约定（各场景一致）

README 与三套入口代码都强调：installSpeedballGI() 必须在首次渲染或 renderer.setAnimationLoop() 之前调用。原因是 SPEEDBALL GI 会在 lit 材质编译前注入一个"GI 感知的 Three.js lights 节点"，若渲染循环启动后才安装，缓存的非 GI lights 节点无法被替换，GI 永远接不进来。

每个场景的运行时流程：

1. 创建/加载几何与光照（Sponza 用 GLTFLoader 加载 public/Sponza/glTF/Sponza.gltf；Court 用 simple_scene.js 程序化生成；Ball Pool 用 ballpool_scene.js 物理世界）。
2. 场景就绪后调用 gi.requestRebuild() 请求探针场重建（自动拟合包围盒）。
3. 每帧调用 gi.update({ playing: false })。
4. 通过共享后处理管线 renderPipeline.render() 渲染。

playing: false 并非关闭 GI 或暂停球池物理，而是标记"场景不在播放时间线"，让 SPEEDBALL GI 的空闲门控（idle gate）把繁重的 BVH 构建与 GPU 求解推迟到相机/GUI 交互静止后再进行——从而绝不会在交互中途出现帧卡顿。

天空网格、探针辅助体、诊断反射体等都通过 excludeFromGI() 排除在 GI 追踪之外，避免它们撑大自动包围盒或污染自身光照。

3.2 统一预色调映射渲染管线（五个阶段）

1. WebGPU 场景 Pass：用 MRT（Multiple Render Targets）写入 color、depth、velocity、view-space normals。
2. GTAO：调制场景颜色（环境光遮蔽）。
3. TRAA：解析相机抖动（jitter）与时间历史（temporal history）。
4. Bloom：叠加在解析后的图像上。
5. 色调映射 + 曝光：由 renderer 应用所选 tone mapping（ACES Filmic 等）与曝光。

因 TRAA 已提供抗锯齿阶段，画布 MSAA 被显式关闭（new THREE.WebGPURenderer({ canvas, antialias: false })）。

3.3 Sponza 场景具体执行步骤（以 src/main.js 为例）

1. 取 #c 画布与 #status 状态元素，注册 error/unhandledrejection 全局监听以显示错误浮层。
2. 创建 WebGPURenderer（antialias:false），设 DPR、size、ACES Filmic 色调映射，await renderer.init()；随后检查 renderer.backend.isWebGPUBackend !== true → 非 WebGPU 直接报错退出。
3. 创建 Scene、PerspectiveCamera(62°, …)、OrbitControls（带阻尼）。
4. 天空与太阳：SkyMesh（excludeFromGI）+ DirectionalLight（带阴影）+ 微弱 HemisphereLight 兜底。关键：updateGiSky() 把无太阳的 SkyMesh 穹顶近似为 CPU 端 9 系数球谐（SH-9），只给探针核 9 个 vec3 uniform，避免纹理采样/导数/探针内存；方向太阳光保持 direct-only。
5. 安装 GI：gi = installSpeedballGI({ renderer, scene, camera, enabled, intensity, divisions, hysteresis, roughReflections:true, reflectionIntensity, reflectionSkyFallback:true })，随后 gi.setSmoothness(1)、gi.setFilterStrength(1)、applyGiSettings(gi, params)、updateGiSky()、refreshSunConsumers()。
6. createProbeHelpers(scene, gi, params) 拿到 updateProbeHelpers 回调；addGiPanel(...) 注入共享 GI 面板（不持久化到 Sponza）；addPostPipeline(...) 注入 GTAO/TRAA/Bloom 并返回 { renderPipeline, aoPass, traaPass }。
7. Display 面板：色调映射、曝光、纹理可见性、DPR、帧率上限。
8. 加载 Sponza：GLTFLoader.load(sponzaUrl, …)，遍历 mesh 设阴影并调用 prepareSponzaMaterialForGi()（把金属度 >0.5 归一到介电 metalness=0、粗糙度 <0.85 提到 0.85，让漫反射反弹可读）；加入场景后按包围盒调整阴影相机与天空缩放；添加一个纯金属诊断球（excludeFromGI，便于观察局部反射）；最后 gi.requestRebuild()。
9. 渲染循环（setAnimationLoop）：可选帧率上限 → controls.update() → 金属球上下浮动 → 若 sunGiDirty 则 flushSunGiRefresh() → gi.update({ playing:false }) → updateProbeHelpers() → renderPipeline.render() → stats.update()。

3.4 Ball Pool 场景关键流程（动态 GI）

• ballpool_scene.js 用 @perplexdotgg/bounce 建立 World（重力 -9.81、速度/位置求解迭代、linearDamping/angularDamping），创建六面墙（白墙 + 左红墙 + 右绿墙）与按视口宽算出的实例化球体（InstancedMesh，按颜色分组，DynamicDrawUsage）。
• 每帧：step(deltaSeconds)（推进物理）→ syncMeshes()（把刚体位置/朝向写回实例矩阵，睡眠或微小位移则跳过以省开销）→ gi.update({ playing:false }) → 渲染。
• 指针交互：pointermove 用 Raycaster 与 frontPlane 求交得到灯光目标位置；移动时 pushAlongRay() 沿射线把半径内小球施加线性冲量；按住指针（触屏双指）则持续 respawnBalls() 把球送回顶部。灯光位置做指数缓动跟随指针。
• 视口 resize 时（去抖 120ms）ballPool.rebuild(camera.aspect) + gi.requestRebuild() 重建。

3.5 资源优化与校验流程

• scripts/optimize-sponza-textures.mjs：把已还原的 JPEG/PNG 源集用 cwebp 转 WebP（基础色 quality 82、法线/金属粗糙度 quality 95、alpha 掩码无损），用 SHA-256 对逐字节相同的法线贴图去重，更新 glTF 的 EXT_texture_webp 扩展与 textures[].extensions.source，删旧 JPEG/PNG，并统计引用负载。
• tests/sponza-assets.test.mjs：node --test 跑两组断言——（1）Sponza 仅引用 WebP（校验 EXT_texture_webp、纹理映射 SHA-256、alpha MASK 图像数=3、各 WebP 尺寸 1024²/white.webp 4²、WebP 资产总 SHA-256、无遗留 legacy 纹理）；（2）引用负载 ≤ 30 MiB（校验单一 buffer 的 SHA-256 与大小、累加 gltf + buffer + 全部图片字节数）。预期哈希硬编码进测试，作为"已验证内容"的契约。

4. 文件逐个解读（按模块）

4.1 根级配置与文档

4.2 三场景入口（HTML + 主 JS）

4.3 共享辅助模块（三个场景共用）

4.4 资源与构建/质量保障

5. 优势、不足、创新点与亮点

5.1 优势

1. 三场景互补：建筑（Sponza）、程序化（Court）、动态（Ball Pool）分别覆盖"静态复杂几何 / 间接颜色对比 / 移动实例化几何下的实时 GI"，展示维度完整。
2. 世界空间 DDGI + 自动拟合：探针体积自动包围场景，无需预烘焙；可选探针可视化（含 lit 模式显示真实辐照度），便于教学与调试。
3. 粗糙/光滑局部探针反射：Sponza 与 Court 提供 local probe reflections，比纯环境光更有质感。
4. 实时可调 + 空闲门控：GI 探针布局、射线数、时间响应、漏光抑制、天空贡献、显示设置全部可直播控；空闲门控确保"交互时不卡、静止才收敛"，体验顺滑。
5. 统一后处理栈：GTAO + TRAA + Bloom 在色调映射前组合，且 TRAA 自带抖动与历史管理。
6. 共享控制面 + 持久化：gi_settings.js 让三页共享完全一致的 GI 控件，且 GI 键 localStorage 持久化（类型安全合并，避免陈旧/手改数据注入 NaN）。
7. 资源严格管控：WebP（EXT_texture_webp）分级质量 + 逐字节去重 + node:test 用硬编码 SHA-256 与 30 MiB 预算做"内容契约"校验，保证线上资产可信且体积小。
8. 响应式 HUD/GUI：移动端 GUI 变底部抽屉，触屏双指交互球池，开箱可用。

5.2 不足 / 限制（README 明确列出 + 代码观察）

1. 收敛需要时间：探针光照随帧累积收敛，初始加载及灯/几何/网格结构变更后需若干帧才稳定。
2. 局部反射是近似：属"离屏稳定光照层"，非逐像素镜面反射或路径追踪。
3. Sponza 材质被归一化：加载器把强金属度归一到介电、提升低粗糙度，使漫反射反弹可读——因此不是源 glTF 的原始材质参考查看器。
4. WebP 强依赖：打包 Sponza 要求 WebP（WebGPU 浏览器已支持，故无回退纹理集）。
5. GUI 不持久化：重载/重访恢复该场景默认值（Sponza 故意不持久化以保证"每次回到发布调参"）。
6. 无 WebGL 回退：硬性要求 WebGPU storage 特性，旧浏览器不可用。
7. 依赖上游库演进：GI 行为基本由 speedball-gi（npm ^0.6.7）与 three@0.185.1 决定，本仓库主要是"展示/适配/测试场景"，核心算法不在本仓。

5.3 创新点 / 亮点

1. 本地 TRAA 实现（TRAANode.js）：把 three.js WebGPU 的 TAA 思路落地为本仓可控节点——方差裁剪（NVIDIA GDC2016）、子像素校正、Lottes 闪烁抑制、AABB 裁剪（Playdead temporal），并用 Halton 抖动 + renderPipeline 前后钩子做相机偏移同步；尺寸变化用 beauty 纹理重置历史防黑屏。这是本仓最"自研"的亮点代码。
2. 空闲门控的 GI 求解（playing:false）：把繁重 BVH 构建/GPU 求解推迟到交互静止，从架构上消除"交互中途帧卡顿"，是实时 GI 演示中很关键的体验设计。
3. 共享 Demo 辅助模块驱动多页一致体验：gi_settings.js/post_settings.js 抽离出"单一控制面"，一处增减滑块即在三页同时生效；addGiPanel 的 onInteract/onStructure 回调把各页的交互/结构事件统一回灌 GI。
4. 探针可视化即"GI 读数"：probe_helpers.js 的 lit 模式直接采样 sampleIrradiance 把探针染成实际辐照度颜色，把抽象的探针场变成肉眼可读的调试信息。
5. 资产内容契约（content-contract）测试：tests/sponza-assets.test.mjs 用硬编码 SHA-256 + 30 MiB 上限，把"资产正确性"变成可回归的 CI 门禁，配合 optimize-sponza-textures.mjs 形成可重建、可验证的资源闭环。
6. 多页 Vite 工程化：vite.config.js 用 rollupOptions.input 把三个 HTML 同时打包、base:'/speedball-gi/' 适配 GitHub Pages 项目路径、dedupe:['three'] 避免多副本，体现成熟的前端工程实践。

附：关键技术栈速查