Formalize volume shader include context

docs/plan/Renderer剩余收口与体积渲染多后端正式化计划_2026-04-10.md

@@ -0,0 +1,200 @@
+# Renderer 剩余收口与体积渲染多后端正式化计划
+
+日期：2026-04-10
+
+## 1. 文档定位
+
+旧的 `Renderer当前阶段正式收口计划_2026-04-09` 与 `NanoVDB稀疏体积渲染后续正式化计划_2026-04-09`
+已归档。
+
+当前这份计划只覆盖 Rendering 主线里仍然没有真正收口的剩余问题，不再重复记录已经完成的阶段成果。
+
+本轮目标有且只有四类：
+
+1. 把 NanoVDB 体积渲染从 D3D12 单后端正式能力推进到 Vulkan / OpenGL 正式能力。
+2. 把 `FinalColor` 与 volume/final-output 的契约收死，消除“接口已存在但运行时半接线”的状态。
+3. 把 `ObjectId` 从“低 32 位截断可用方案”推进到清晰稳定的正式渲染 ID 契约。
+4. 把阴影规划与前向管线剩余的硬编码策略、monolith 结构继续拆干净。
+
+---
+
+## 2. 当前状态判断
+
+当前 Rendering 已经具备稳定运行基础，但还不能称为“完全收口”，核心原因是：
+
+1. `volume_scene / volume_occlusion_scene / volume_transform_scene` 目前仍只在 D3D12 上做了正式实例化与 GT 验证。
+2. `FinalColorSettings` 已经具备 pipeline/camera/volume 三层策略接口，但运行时只真正接入了 pipeline + camera。
+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、volume overrides 的设计边界。
+2. 二选一处理 volume override：
+   - 真正接入运行时解析链路；
+   - 或明确从现阶段 API 中收掉，不再保留半接线接口。
+3. 补齐对应单测与场景回归测试。
+4. 明确 post-process / final-output / volume 的职责关系文档。
+
+验收标准：
+
+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 不是“功能没做完”，而是“剩余收口项已经缩小到多后端体积渲染、运行时契约、自身结构整理三类问题”；本轮做完之后，才可以严肃地说它进入了真正可长期维护的正式状态。