XCEngine/docs/plan/rendering_srp_urp_closeout_plan.md

Rendering SRP / URP Closeout Plan

更新日期: 2026-04-26

状态: Draft, Phase 1 queued

1. Plan 管理规则

• docs/plan 只保留总 plan。
• 已完成 subplan 的结论直接并回总 plan，不再长期保留独立阶段文档。
• 如果实现与本计划冲突，以代码现状为准，再回写本计划。
• 本计划关注“收口顺序”和“职责边界”，不把所有未来渲染特性都混进当前路线。

2. 当前状态判断

• native 主链已经比较清楚: SceneRenderer -> SceneRenderRequestPlanner -> RenderPipelineHost -> CameraRenderer -> RenderSceneExtractor -> CameraFrameGraph -> RenderGraph。
• managed 侧已经存在 ScriptableRenderPipelineAsset -> ScriptableRendererData -> ScriptableRenderer -> ScriptableRendererFeature/Pass 这条产品层骨架。
• ScriptableRenderPipelineHost 已经能优先把 stage graph、scene setup、directional shadow execution state 交给 managed runtime。
• 因此当前问题不是“SRP 没打通”，而是“URP 风格上层还没有彻底收口成唯一主线”。
• 目前 managed runtime 仍复用默认 native forward backend 作为共享绘制后端，这让 BuiltinForwardPipeline 同时带着“产品层语义”和“native 执行后端”两种身份。

3. 顶层架构问题

• BuiltinForwardPipeline 身份过重，既像默认产品管线，又像通用 scene draw backend。
• managed URP 还不是默认主线的唯一组织者，部分策略仍可能滑回 native backend。
• backend 解析目前偏隐式，default fallback 的存在让“谁在拥有组织权”不够明确。
• PostProcess / FinalOutput / Shadow / DepthOnly / MainScene 虽然都有 managed 接缝，但还没有被定义成统一、稳定、单一路径的产品闭环。
• 现有测试覆盖了很多局部契约，但“默认 URP 主路径”的端到端产品闭环还不够突出。

4. 长期目标

长期目标不是继续堆更多 URP 外形，而是把 URP 真正收口成唯一上层组织者。

目标架构应收敛为:

GraphicsSettings.renderPipelineAsset
  -> UniversalRenderPipelineAsset
      -> selected ScriptableRendererData
          -> UniversalRenderer
              -> ScriptableRendererFeature / ScriptableRenderPass
                  -> ScriptableRenderPipelineHost
                      -> native scene draw backend contract
                          -> RenderSceneExtractor / CameraFrameGraph / RenderGraph / RHI

5. 长期职责边界

• managed URP 负责:
  • camera request policy
  • renderer 选择
  • per-camera stage planning
  • render scene setup
  • shadow execution policy
  • pass / feature 排序与产品层组织
• native Rendering 负责:
  • Scene 到 RenderSceneData 的提取
  • renderer list 绘制
  • native scene feature 执行
  • fullscreen primitive 与 graph 执行支持
  • RenderGraph / RHI 执行内核
• BuiltinForwardPipeline 或其后继最终只应保留 backend 语义，不再承载默认产品层策略。
• 新增“绘制能力”优先放 native；新增“渲染组织策略”优先放 managed。

6. 长期阶段路线

Phase 1: Renderer-backed URP v1 收口

• 目标: 让 UniversalRenderPipelineAsset -> UniversalRendererData -> UniversalRenderer 成为默认主线的明确组织者。
• 重点: 不大改底层执行内核，先收口产品层 ownership。
• 交付:
  • 把共享 native backend 的解析变成显式 contract，而不是隐藏 fallback。
  • 明确 ShadowCaster / DepthOnly / MainScene / PostProcess / FinalOutput 的 managed ownership。
  • 固化默认 renderer data、default feature lineup、camera override 和 final color 策略。
  • 补一组面向默认 URP 主线的端到端验证。
• 验收:
  • 默认 UniversalRenderPipelineAsset 的主路径不再依赖“读代码才知道”的隐式 backend fallback 语义。
  • managed 层成为五类默认 stage 的唯一组织入口。
  • 本阶段不再把新的产品策略塞进 BuiltinForwardPipeline。

Phase 2: Native backend contract 抽取

• 目标: 把 BuiltinForwardPipeline 退回为 backend-only 角色，抽出更稳定的 native scene draw contract。
• 重点: 从“具体默认管线类”过渡到“可被 managed 调用的 native backend 能力集合”。
• 交付:
  • 抽取明确的 backend asset / backend key / backend contract。
  • 明确 scene draw、native feature pass、fullscreen support 的 contract surface。
  • 收窄 ScriptableRenderPipelineHost 和 managed bridge 对 BuiltinForwardPipeline 具体类型的隐式依赖。
• 验收:
  • managed bridge 暴露的是 backend contract，而不是继续暴露一个带产品语义的默认 forward pipeline 资产。
  • host fallback 只保留兼容路径，不再是默认产品路径的一部分。

Phase 3: Feature ownership 迁移

• 目标: 把上层 feature 组织从“native 顺带拥有”进一步迁到 managed URP。
• 重点: native 只保留叶子能力，feature 编排放回 ScriptableRendererFeature 和 renderer block。
• 交付:
  • 明确哪些能力保留为 native leaf feature，例如 volumetric、gaussian splat、tooling feature pass。
  • 把这些能力的启用、排序、插入点和开关逻辑统一交给 managed feature/controller。
  • 清理仍然散落在 C++ 中的 URP-like 组织策略。
• 验收:
  • feature 是否执行、何时执行、插入在哪个 stage/block，应由 managed 层决定。
  • native 只回答“怎么执行”，不再回答“应不应该插入”。

Phase 4: Asset / Editor / Runtime 产品化

• 目标: 让 renderer data、renderer feature、camera override、graphics settings 形成稳定产品闭环。
• 重点: 让默认主线不只是能跑，而是能配置、能失效重建、能被 editor 正常消费。
• 交付:
  • 稳定 UniversalRendererData、default renderer composition、renderer override、camera additional data。
  • 梳理 runtime invalidation、renderer rebuild、feature cache release 路径。
  • 把默认 asset、renderer data、feature 的 authoring 体验稳定下来。
• 验收:
  • graphics settings、camera override、renderer invalidation 都能沿主路径稳定工作。
  • editor / runtime 不再依赖 probe 级行为去维持默认主线。

Phase 5: 收尾与清理

• 目标: 删除临时兼容层，统一命名和文档，把“在建中的双重语义”收尾。
• 重点: 只在前面阶段稳定后做命名与删除，不和 ownership 迁移并行进行。
• 交付:
  • 删除过时 fallback。
  • 统一 host / backend / renderer / feature 的命名。
  • 更新模块文档、测试说明和 blueprint。
• 验收:
  • 默认主线对新人是可解释的。
  • “哪个层负责什么”可以不靠历史背景直接从命名和代码结构看出来。

7. 跨阶段约束

• 不把 deferred、clustered lighting、完整 volume framework、更多 Unity compatibility shim 混入当前收口路线。
• 不在收口阶段同时做大规模 rename 和 ownership 迁移。
• 不新增新的“临时 fallback 语义”来掩盖边界问题。
• 每推进一个阶段，都必须补足默认主线路径的 focused test，而不是只补 probe。
• 任何新增策略逻辑，都要先回答“它属于 managed 组织层还是 native 执行层”。

8. 非目标

• 这份计划当前不直接追求完整 HDRP / 延迟渲染路线。
• 不直接重写 RenderGraph。
• 不直接重做 RenderSceneExtractor 和相机规划主链。
• 不要求短期内删掉所有 builtin pass。
• 不把 editor tooling pass、object id、selection outline 等工具路径强行并入默认 URP 主线。

9. 下一个阶段 subplan

下一个阶段对应 Phase 1: Renderer-backed URP v1 收口。

9.1 阶段目标

• 让默认 UniversalRenderPipelineAsset 成为“可解释、可验证、可扩展”的唯一上层主线。
• 保持底层执行内核稳定，不在本阶段直接做 backend 大拆分。
• 先把 ownership 和 contract 说清楚，再进入更大的 backend 抽取。

9.2 本阶段明确要解决的问题

1. managed bridge 目前对共享 native backend 的解析太隐式。
2. UniversalRenderer 对默认 stage 的 ownership 还不够集中，PostProcess 路径尤其需要拍板。
3. BuiltinForwardPipeline 仍容易继续吸收本该属于产品层的策略。
4. 默认 URP 主线缺一组更醒目的 end-to-end 验证。

9.3 建议改动范围

• engine/include/XCEngine/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h
• engine/src/Scripting/Mono/MonoScriptRuntime.cpp
• engine/src/Rendering/Pipelines/ScriptableRenderPipelineHost.cpp
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/RendererBackedRenderPipelineAsset.cs
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderPipelineAsset.cs
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderer.cs
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalPostProcessBlock.cs
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalFinalOutputBlock.cs
• tests/scripting/test_mono_script_runtime.cpp
• tests/Rendering/unit/test_camera_scene_renderer.cpp
• 如有必要，再补 project/Assets/Scripts/ProjectRenderPipelineProbe.cs

9.4 执行顺序

1. 先把 shared native backend contract 显式化。
   • 明确 managed asset runtime 返回的到底是“默认 fallback backend”还是“显式指定 backend”。
   • 推荐把默认 URP 使用的 native backend 变成显式选择，而不是 CreateDefaultPipelineBackendAsset() 兜底。
   • 兼容 fallback 可以保留，但必须退到 guarded compatibility path。
2. 再收口默认 stage ownership。
   • ShadowCaster / DepthOnly / MainScene / PostProcess / FinalOutput 的默认规划和调度都要从 UniversalRenderer 主线解释得通。
   • PostProcess 建议正式成为 UniversalRenderer 的显式 stage 分支，而不是只靠 feature 侧“顺带成立”。
   • UniversalPostProcessBlock 与 UniversalFinalOutputBlock 的关系要稳定成单一路径。
3. 冻结 BuiltinForwardPipeline 的产品层职责继续外溢。
   • 本阶段起不再向它添加新的 camera policy、renderer 选择、stage 编排逻辑。
   • 若新增能力确实必须放 native，也要以 backend contract 的形式暴露，而不是直接塞产品策略。
4. 补默认主线 focused validation。
   • 覆盖默认 UniversalRenderPipelineAsset。
   • 覆盖 custom renderer data / renderer override。
   • 覆盖 feature 注入对 post-process / main-scene 路径的影响。
   • 覆盖 renderer invalidation 和 runtime rebuild。

9.5 本阶段验收标准

• 默认 UniversalRenderPipelineAsset 的 backend 来源是显式可追踪的。
• 默认五类 stage 都能从 managed URP 主线解释清楚 ownership。
• BuiltinForwardPipeline 在本阶段没有继续吸收新的产品层策略。
• 默认 URP 主路径至少具备一组比 probe 更贴近产品语义的 focused 测试。
• 文档和代码中的默认主线表述一致。

9.6 本阶段非目标

• 不在本阶段直接重命名 BuiltinForwardPipeline。
• 不在本阶段抽出最终形态的 backend-only 类层次。
• 不引入 deferred、renderer graph 大改或新的大体量渲染特性。
• 不把 editor tooling 路径强行并进默认 URP 产品线。

9.7 阶段完成后的输出

• 一条更清晰的默认 URP 主线。
• 一组更明确的 backend contract 下一步抽取前提。
• 一个可以继续进入 Phase 2 的更稳定起点。