XCEngine/docs/used/NanoVDB稀疏体积渲染后续正式化计划_阶段归档_2026-04-10.md

NanoVDB 稀疏体积渲染后续正式化计划

日期：2026-04-09

1. 文档定位

旧的 NanoVDB 大计划已经归档为第一阶段完成文档。

当前这份计划只保留 NanoVDB 体积渲染在第一阶段落地之后，真正还没有完全收口的少数事项。

这意味着：

1. .nvdb -> artifact -> VolumeField -> VolumeRendererComponent -> BuiltinVolumetricPass -> Editor 基本接入 已经视为第一阶段完成。
2. 当前不再讨论那一整套已经落地的基础链路。
3. 当前只推进仍然明确未完成、且会影响后续长期演进的后续正式化工作。

---

2. 第一阶段已完成范围

以下内容已经不再作为活跃计划项：

1. .nvdb 资源导入与 artifact 化。
2. VolumeField 运行时资源模型。
3. VolumeRendererComponent 组件接入。
4. RenderSceneExtractor 对体积对象的提取。
5. BuiltinVolumetricPass 在内建前向链路中的正式接入。
6. D3D12 正式链路点亮。
7. D3D12 体积渲染集成测试与 GT 对比。
8. Editor 中最小可用的组件面板接入。

这些内容已经不该继续挂在 docs/plan 里作为未完成主线。

---

3. 当前仍然活跃的真实问题

现在剩下的 NanoVDB 后续工作，核心只有两类。

3.1 多后端尚未完成正式 rollout

当前体积渲染集成测试仍然只在 D3D12 路径上正式实例化与验证。

这意味着下面这些工作还没完成：

1. Vulkan 的正式点亮与稳定验证。
2. OpenGL 的正式点亮与稳定验证。
3. 三后端统一 GT 基线与回归验证。
4. capability 检测、禁用行为、错误信息是否完整。

3.2 与未来高层系统的契约还没有最终落地

当前底层 buffer 资源能力已经具备，但和未来高层系统的最终契约还没有必要现在就完全做死。

真正还需要收口的是：

1. 明确 NanoVDB 路线如何映射到未来 Unity 风格 SetBuffer 使用面。
2. 明确当 C# / SRP 正式接入时，体积渲染不会反向逼迫底层重写。
3. 把当前已经存在的运行时绑定约束整理成正式文档边界，而不是继续散落在实现里。

注意：

这不意味着现在要实现完整 C# 绑定层。 本阶段只需要把边界冻结清楚。

---

4. 本轮明确不做什么

1. 不重做第一阶段已经落地的 D3D12 体积渲染主链路。
2. 不扩展新的体积特性，例如全局体积雾、体积阴影系统、froxel fog。
3. 不引入 Texture3D 替代 NanoVDB 正式路线。
4. 不提前实现完整 C# Volume API。
5. 不把体积渲染主线改造成依赖 SRP 才能继续推进。

---

5. 执行阶段

Phase 1：Vulkan 路线正式点亮

目标：

把当前已经在 D3D12 上验证过的 NanoVDB 正式链路，推进到 Vulkan。

任务：

1. 审查 StructuredBuffer / storage buffer 绑定路径在 Vulkan 下的编译与运行时绑定。
2. 补齐体积渲染 shader 在 Vulkan 路线上的资源布局与反射验证。
3. 让 volume_scene、volume_occlusion_scene、volume_transform_scene 至少能在 Vulkan 路线上正式跑通。
4. 固化 Vulkan 路径的 GT 对比与失败日志。

验收标准：

1. Vulkan 路线上能稳定出图。
2. 集成测试能稳定通过。
3. 不是“偶然能跑”，而是正式进入体积渲染支持集合。

Phase 2：OpenGL 路线正式点亮

目标：

把 NanoVDB 路线推进到 OpenGL，并明确 SSBO/GLSL 转译的正式边界。

任务：

1. 审查当前 StructuredBuffer 到 OpenGL/SSBO 的转译链路。
2. 解决体积 shader 在 OpenGL 路线上可能出现的 layout、binding、对齐问题。
3. 让三组体积集成测试至少具备 OpenGL 正式验证能力。
4. 明确 OpenGL 不支持场景下的禁用与报错策略，禁止 silent fallback。

验收标准：

1. OpenGL 路线能稳定出图。
2. 三后端测试输出都可统一对同一 GT 做比较。
3. 不再存在“D3D12 独有体积功能”的阶段性状态。

Phase 3：多后端能力收口与文档冻结

目标：

在 D3D12 / Vulkan / OpenGL 三后端都跑通之后，把 NanoVDB 这条能力从“已点亮”收口成“正式能力”。

任务：

1. 明确三后端 capability 表达方式。
2. 明确资源绑定失败、shader 编译失败、后端不支持时的统一错误行为。
3. 冻结未来高层 SetBuffer 风格接口与当前底层资源绑定的对应关系。
4. 更新文档并把这份后续计划归档。

验收标准：

1. 三后端行为边界清晰。
2. 错误路径明确，不靠试错排查。
3. 文档和代码边界一致。

---

6. 当前阶段完成标志

当下面条件同时成立时，这份后续计划才算真正完成：

1. volume_scene
2. volume_occlusion_scene
3. volume_transform_scene

上述三组集成测试已经在：

1. D3D12
2. Vulkan
3. OpenGL

三后端上完成正式验证，且对应错误处理、能力边界、文档说明都已经收口。

---

7. 一句话结论

NanoVDB 不是“还没做完”，而是“第一阶段已经完成，剩下的是多后端 rollout 与最终正式化边界”；从现在开始，这条主线不再需要一份大而全计划，只需要一份小而硬的后续收口计划。