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 与最终正式化边界”；从现在开始，这条主线不再需要一份大而全计划，只需要一份小而硬的后续收口计划。