XCEngine/docs/plan/rendering_srp_urp_closeout_plan.md

# Rendering SRP / URP Closeout Plan

更新日期: `2026-04-26`

状态: `Completed, Phase 1 closeout done`

## 1. 长期目标

目标不是继续堆更多 URP 外形，而是把默认渲染主线真正收口为:

`GraphicsSettings.renderPipelineAsset -> UniversalRenderPipelineAsset -> ScriptableRendererData -> UniversalRenderer -> ScriptableRendererFeature/Pass -> ScriptableRenderPipelineHost -> native backend contract -> RenderGraph / RHI`

收口后的职责边界:

- managed URP 负责 camera policy、renderer 选择、stage planning、feature/pass 编排、final color 策略
- native Rendering 负责 scene extraction、scene draw、fullscreen graph execution、RenderGraph/RHI
- `BuiltinForwardPipeline` 或其后继只保留 backend 语义，不继续承载产品层策略

## 2. 阶段路线

### Phase 1: Renderer-backed URP v1 收口

- 让默认 `UniversalRenderPipelineAsset -> UniversalRenderer` 成为唯一上层主线
- 先收口 ownership 和 contract，不在本阶段做 backend 大拆分

### Phase 2: Native backend contract 抽取

- 把默认 native backend 从产品层语义里剥离出来
- 让 host/bridge 面向稳定 backend contract，而不是面向 builtin forward 产品实现

### Phase 3: Feature ownership 迁移

- 把 feature 的启用、排序、插入点统一回收到 managed `ScriptableRendererFeature`

### Phase 4: Asset / Editor / Runtime 产品化

- 稳定 renderer data、camera override、runtime invalidation、editor 消费路径

### Phase 5: 收尾与清理

- 删除临时兼容层，统一命名和文档

## 3. Phase 1 已完成进展

- 已补齐长期目标文档和 Rendering 模块目标描述
- 已把 managed backend 解析从“隐式默认 fallback”改成“显式策略”
- 已新增 `ManagedPipelineRendererAssetPolicy`
- 已让 `ManagedScriptableRenderPipelineAsset` 先读显式 renderer asset，再按 policy 解析 default native backend
- 已让 `MonoManagedRenderPipelineAssetRuntime::GetPipelineRendererAsset()` 不再直接偷偷创建默认 native backend asset
- 已让 Mono runtime 显式返回 `DefaultNativeBackend` policy
- 已把 `UniversalRenderer` 的 `PostProcess` 变成显式 stage 分支
- 已补 `UniversalPostProcessBlock.EnqueueRenderPasses()` 作为显式入口
- 已把 `RuntimeStateHashUtility` 调整为跨程序集可见
- 已把 `ScriptableRendererFeature.CreateInstance()` 调整为可供外部受控复用
- 已更新一批 scripting 侧测试预期，使默认 URP/managed pipeline case 面向“显式 default backend policy”
- 已完成 editor 编译与 12 秒启动冒烟
  - `XCUIEditorApp` 编译通过
  - `build/editor/Debug/XCEngine.exe` 12 秒启动烟测通过

## 4. Phase 1 验收结果

- 已修掉 `managed/GameScripts/RenderPipelineApiProbe.cs` 中挡住本阶段验证的 managed API 问题
- `scripting_tests` 已恢复为可用基线，并通过 9 条聚焦的 SRP/URP 回归用例
- 默认 backend 来源、default renderer fallback、feature 注入、renderer invalidation 等关键主路径已被 focused regression tests 覆盖
- editor 侧验证已补齐，`XCUIEditorApp` 编译与 `build/editor/Debug/XCEngine.exe` 12 秒启动烟测均通过
- `rendering_unit_tests` 仍存在与本次收口无关的既有编译断点，但不再阻塞 Phase 1 收口验收

## 5. 当前 subplan

本轮 subplan 已完成，已从执行列表清空。

### 5.1 已完成验收项

- 默认 backend 来源已变成显式可追踪的 policy
- `PostProcess` ownership 已稳定挂到 `UniversalRenderer`
- `scripting_tests` 已能稳定覆盖本阶段相关用例
- 默认 URP 主路径已具备 focused regression tests
- Phase 1 未再引入新的隐式 fallback 语义

## 6. 下一阶段建议

下一阶段可以进入 Phase 2，但不要重新把产品层策略带回 native:

1. 抽取更稳定的 native backend contract，继续收窄 host/bridge 对具体 builtin forward 实现的依赖
2. 继续把 feature 的启用、排序、插入点留在 managed `ScriptableRendererFeature / UniversalRenderer` 主线
3. 在当前 focused regression baseline 之上继续稳住 renderer invalidation、asset authoring 和 editor/runtime 消费路径

## 7. 非目标

- 本阶段不直接重命名 `BuiltinForwardPipeline`
- 不在本阶段完成 backend-only 最终类层次
- 不引入 deferred、clustered lighting、完整 volume framework 等新能力
- 不把 editor tooling 路径强行并进默认 URP 产品主线