XCEngine/docs/used/Renderer剩余收口与体积渲染多后端正式化计划_完成归档_2026-04-10.md

Renderer 剩余收口与体积渲染多后端正式化计划

日期：2026-04-10

1. 文档定位

旧的 Renderer当前阶段正式收口计划_2026-04-09 与 NanoVDB稀疏体积渲染后续正式化计划_2026-04-09 已归档。

当前这份计划只覆盖 Rendering 主线里仍然没有真正收口的剩余问题，不再重复记录已经完成的阶段成果。

本轮目标有且只有四类：

1. 把 NanoVDB 体积渲染从 D3D12 单后端正式能力推进到 Vulkan / OpenGL 正式能力。
2. 把 FinalColor 与 final-output 的契约收死，消除“接口已存在但运行时半接线”的状态。
3. 把 ObjectId 从“低 32 位截断可用方案”推进到清晰稳定的正式渲染 ID 契约。
4. 把阴影规划与前向管线剩余的硬编码策略、monolith 结构继续拆干净。

---

2. 当前状态判断

当前 Rendering 已经具备稳定运行基础，但还不能称为“完全收口”，核心原因是：

1. volume_scene / volume_occlusion_scene / volume_transform_scene 目前仍只在 D3D12 上做了正式实例化与 GT 验证。
2. FinalColorSettings 当前真正落地的是 pipeline defaults + camera overrides；此前残留的 volume override 分支只是头文件级 API，并未进入运行时。
3. ObjectId 仍基于 runtime object id 低 32 位编码，不是长期正式方案。
4. SceneRenderRequestPlanner 里仍保留方向光阴影尺寸与 focus 策略的硬编码。
5. BuiltinForwardPipeline 功能上可用，但资源布局、PSO、descriptor、skybox、draw path 仍聚集在同一条大实现链里。

这五点不继续收掉，后面不管做 editor 深化还是做更高层 renderer / SRP，都会反复返工。

---

3. 本轮明确不做什么

1. 不引入 RenderGraph。
2. 不提前启动 SRP 正式实现。
3. 不改写现有 Shader/Material 语法主线。
4. 不扩展新的大特性，例如 deferred、reflection probe、完整 post-processing stack。
5. 不为了追求“结构完美”重写整个 builtin renderer。

本轮只做剩余收口，不做新能力扩张。

---

4. 执行阶段

Phase 1：NanoVDB Vulkan 正式点亮

目标：

把当前 D3D12 已验证的体积渲染链路推进到 Vulkan 正式支持。

任务：

1. 审查 BuiltinVolumetricPass 在 Vulkan 下的 StructuredBuffer / storage buffer 绑定路径。
2. 核对体积 shader 在 Vulkan 下的资源布局、反射、descriptor set 绑定。
3. 让 volume_scene、volume_occlusion_scene、volume_transform_scene 在 Vulkan 下正式实例化并通过。
4. 固化 Vulkan 失败日志与 capability 行为，禁止 silent fallback。

验收标准：

1. Vulkan 路线能稳定出图。
2. 三个体积集成测试全部通过。
3. 失败时日志能直接定位到 capability / shader / 绑定问题。

Phase 2：NanoVDB OpenGL 正式点亮

目标：

把体积渲染推进到 OpenGL 正式支持，并确认 SSBO/GLSL 转译边界。

任务：

1. 审查 StructuredBuffer -> OpenGL SSBO 的运行时绑定链。
2. 解决体积 shader 在 OpenGL 下的 layout / binding / 对齐问题。
3. 让三组体积集成测试在 OpenGL 下正式实例化并通过。
4. 明确 OpenGL 不支持场景下的禁用与报错策略。

验收标准：

1. OpenGL 路线能稳定出图。
2. D3D12 / Vulkan / OpenGL 三后端都具备正式验证。
3. 不再存在“体积渲染只是 D3D12 正式能力”的状态。

Phase 3：FinalColor 契约彻底收死

目标：

让 FinalColor 的 API 契约、运行时行为、测试覆盖完全一致。

任务：

1. 审查 FinalColorSettings、camera overrides、final-output 的设计边界。
2. 将未落地的 volume override 分支从现阶段 API 中正式收掉，不再保留半接线接口。
3. 补齐对应单测与场景回归测试。
4. 明确 post-process / final-output 的职责关系文档。

验收标准：

1. 不再存在“接口支持但执行层没接”的不自洽状态。
2. FinalColor 行为能用测试稳定验证。

Phase 4：ObjectId 正式渲染 ID 契约

目标：

把 picking / outline / selection 依赖的 ID 方案从阶段实现推进到正式契约。

任务：

1. 明确长期方案是稳定 32-bit render id，还是 runtime mapping table。
2. 将 ObjectIdCodec 与 GameObject::ID 的关系从“低 32 位截断”调整为正式约束。
3. 让 picking / outline / editor selection 共用同一份正式契约。
4. 补齐边界测试与错误防护。

验收标准：

1. ObjectId 不再依赖模糊约定。
2. 相关 editor 能力建立在稳定渲染 ID 契约上。

Phase 5：阴影规划与前向管线剩余结构收口

目标：

继续把 planner / pipeline 里剩余的硬编码和 monolith 结构压缩到合理边界。

任务：

1. 把方向光阴影尺寸、focus/depth/padding 策略抽成正式配置点。
2. 收紧 SceneRenderRequestPlanner 的职责，避免继续膨胀。
3. 拆分 BuiltinForwardPipeline 剩余的大块职责：
   • pipeline state resolve
   • descriptor/layout cache
   • skybox path
   • draw submission
4. 保持功能不回退的前提下优化代码结构与目录边界。

验收标准：

1. 阴影规划不再写死关键策略参数。
2. BuiltinForwardPipeline 不再继续向单体类膨胀。

Phase 6：测试、文档、归档

目标：

让本轮真正可交接、可回归、可归档。

任务：

1. 复跑关键 Rendering unit / integration。
2. 输出阶段总结。
3. 将本轮完成计划归档到 docs/used。

验收标准：

1. 关键测试全绿。
2. 活跃 plan 只保留真正未完成事项。

---

5. 执行顺序

严格按下面顺序推进：

1. Phase 1
2. Phase 2
3. Phase 3
4. Phase 4
5. Phase 5
6. Phase 6

原因：

1. 体积渲染多后端 rollout 还没完成，当前还不能宣称 renderer 全面正式支持。
2. FinalColor 与 ObjectId 都是契约问题，必须在继续推进更高层系统前收死。
3. planner / pipeline 结构整理必须建立在前面能力边界稳定之后。

---

6. 本轮完成标志

当下面条件同时成立时，本轮才算真正完成：

1. 三个体积场景已在 D3D12 / Vulkan / OpenGL 三后端正式验证。
2. FinalColor 契约与执行层完全一致。
3. ObjectId 已切换到正式渲染 ID 契约。
4. 阴影规划关键策略点已正式化。
5. BuiltinForwardPipeline 剩余的结构性膨胀得到明显收口。
6. 文档与测试全部同步完成。

---

7. 一句话结论

当前 Rendering 不是“功能没做完”，而是“剩余收口项已经缩小到多后端体积渲染、运行时契约、自身结构整理三类问题”；本轮做完之后，才可以严肃地说它进入了真正可长期维护的正式状态。