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` 真正收口成唯一上层组织者。

目标架构应收敛为:

```text
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` 的更稳定起点。