Refactor editor windowing and update renderer regression
This commit is contained in:
@@ -1,93 +0,0 @@
|
||||
# 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 产品主线
|
||||
@@ -1,141 +1 @@
|
||||
# 渲染模块长期目标与下一阶段执行计划
|
||||
|
||||
更新时间: `2026-04-26`
|
||||
|
||||
状态: `Active`
|
||||
|
||||
执行闸门:
|
||||
|
||||
- 每完成一个阶段，先编译并启动 `editor`。
|
||||
- 对 `editor` 执行不少于 `12s` 的冒烟测试，确认进程可启动、主循环可持续运行且无立即崩溃。
|
||||
- 只有在该阶段编译和 `12s` 冒烟测试都通过后，才允许执行该阶段的 `commit` 和 `push`。
|
||||
|
||||
说明: 本文基于当前仓库中的实际代码重新审核后编写，用于替代已经失效的 `rendering_srp_urp_closeout_plan.md`。本计划只按现有实现说话，不沿用旧文档中的“已收口完成”结论。
|
||||
|
||||
## 1. 基于代码的审核结论
|
||||
|
||||
- 当前默认渲染主线是
|
||||
`SceneRenderer -> SceneRenderRequestPlanner -> RenderPipelineHost -> CameraFramePlanBuilder -> CameraRenderer -> ExecuteCameraFrameRenderGraphPlan`，不是“managed URP 直接驱动 native backend”的单线结构。
|
||||
- 当前默认顶层 pipeline 已经是 `ScriptableRenderPipelineHost`。在没有显式 preferred asset 时，`RenderPipelineFactory` 会优先尝试 configured managed pipeline asset，失败后回落到 host asset；host 的默认 backend 是 `BuiltinForwardPipelineAsset`。
|
||||
- managed SRP 不是空壳。当前已经具备 `ScriptableRenderPipelinePlanningContext`、`RenderSceneSetupContext`、`DirectionalShadowExecutionContext`、`ScriptableRenderContext`，能够参与 request/frame plan、scene setup、shadow policy、scene draw 和 fullscreen stage 录制。
|
||||
- 但 managed/backend contract 还没有真正完成。`MonoManagedRenderPipelineAssetRuntime::GetPipelineRendererAsset()` 当前不会返回 shared backend asset，`GetPipelineRendererAssetPolicy()` 在 managed asset 可用时固定返回 `DefaultNativeBackend`。也就是说，现阶段 managed renderer 仍统一依赖默认 native scene backend。
|
||||
- `RenderGraph` 的 managed 接口目前是 v1。它能创建 transient texture、记录 scene phase / injection point / native feature pass、按 desc 调 `DrawRenderers`，也能提交 raster pass；但 raster pass execution 仍只覆盖 `ColorScale` / `ShaderVector` / `FinalColor` 三类 fullscreen execution，且 flush 逻辑只对 fullscreen sequence stage 生效。
|
||||
- `UniversalRenderPipelineAsset` / `RendererBackedRenderPipelineAsset` 已支持 `rendererDataList`、`defaultRendererIndex`、`UniversalAdditionalCameraData.rendererIndex`，但 `UniversalPostProcessBlock` 仍为空实现，默认后处理主要依赖 feature 注入和 `FinalOutput` 内置 pass。
|
||||
- `BuiltinForwardPipeline` 仍同时承担 fallback pipeline、默认 `SceneDrawBackend`、默认 native feature host 三个角色，是当前渲染模块最大的耦合点。
|
||||
- editor tooling 仍是独立层。`CameraRenderer` 顶层安装 `BuiltinObjectIdPass`，而 scene viewport 的 grid / selection / helper pass 仍在 editor 专用路径，不应并入本阶段 SRP / URP 主线计划。
|
||||
|
||||
## 2. 长期目标
|
||||
|
||||
- 稳定总主线：
|
||||
`SceneRenderer -> SceneRenderRequestPlanner -> CameraFramePlanBuilder -> CameraRenderer -> ScriptableRenderPipelineHost -> managed stage recorder / native scene draw backend -> RenderGraph / RHI`
|
||||
- 稳定职责边界：
|
||||
managed 负责 camera / request / frame plan、renderer 选择、feature / pass 排序、fullscreen stage 组合、scene setup、shadow policy；native 负责 scene extraction、culling、scene draw backend、资源生命周期、RenderGraph 编译执行、RHI。
|
||||
- 让 `ScriptableRenderPipelineHost` 成为唯一可信的 SRP 边界，而不是继续把产品层策略散落在 `BuiltinForwardPipeline` 和 editor / runtime 兼容层里。
|
||||
- 把 `BuiltinForwardPipeline` 收敛为清晰的 fallback / backend 角色，避免它继续同时承担“默认产品主线”和“可复用 native backend”两套语义。
|
||||
- 让 `rendererDataList`、`rendererIndex`、feature invalidation、bridge generation refresh、asset runtime versioning 变成稳定 contract，而不是靠隐式 fallback 维持行为。
|
||||
- 如果未来真的需要多个 native backend asset，必须通过明确定义的 backend asset contract 接入，而不是继续复用当前未完成的 placeholder API。
|
||||
- 明确 runtime 主渲染与 editor viewport / tooling 的共用层和专用层，避免后续计划再次混写。
|
||||
|
||||
## 3. 当前约束
|
||||
|
||||
- 下一阶段不做纯 managed scene draw backend，不承诺把 Gaussian Splat / Volumetric 改写为纯 C# feature。
|
||||
- 下一阶段不新增 deferred、clustered lighting、完整 volume framework 等新能力。
|
||||
- 下一阶段不改 editor viewport render loop，也不把 grid / selection / helper pass 并入 runtime 主线。
|
||||
- 下一阶段不把 managed `RenderGraph` 包装误写成“通用图形 / 计算图 API”；当前它只是 SRP v1 录制接口。
|
||||
|
||||
## 4. 下一阶段执行计划
|
||||
|
||||
### 4.1 先把 backend contract 讲真
|
||||
|
||||
状态: `Completed` (`2026-04-26`)
|
||||
|
||||
目标: 把“当前唯一真实可用的是 `DefaultNativeBackend`”写进代码和测试，不再保留会误导人的伪完成语义。
|
||||
|
||||
执行:
|
||||
|
||||
- 重新审核 `ManagedRenderPipelineAssetRuntime`、`MonoManagedRenderPipelineAssetRuntime`、`RenderPipelineFactory`、`ScriptableRenderPipelineHost` 的 backend 选择路径。
|
||||
- 对未实现的 explicit backend asset 分支做二选一收口：要么真正实现 shared backend asset 解析，要么明确删除 / 禁用该分支并补充注释与测试。
|
||||
- 把 `DefaultNativeBackend` 作为当前正式 contract 固化下来，避免再出现“文档已完成、代码仍默认回落”的错位。
|
||||
|
||||
完成标志:
|
||||
|
||||
- 代码、测试、文档对 backend 选择语义一致。
|
||||
- 不再有“managed renderer 已支持 explicit backend asset”这一错误暗示。
|
||||
|
||||
### 4.2 从 `BuiltinForwardPipeline` 中抽出可复用的 native scene backend
|
||||
|
||||
状态: `Completed` (`2026-04-26`)
|
||||
|
||||
目标: 减轻 `BuiltinForwardPipeline` 的三重职责，让 host fallback 和 scene draw backend 可以独立演进。
|
||||
|
||||
执行:
|
||||
|
||||
- 从 `BuiltinForwardSceneSetup`、`BuiltinForwardPipeline`、`NativeSceneRecorder` 梳理出稳定的 `SceneDrawBackend` 组装层。
|
||||
- 把 `ShadowCaster`、`DepthOnly`、main scene feature host 的 ownership 拆清楚，避免 host / backend / fallback wrapper 重复配置。
|
||||
- 统一 fallback path 和 managed recorder path 对默认 native feature 的消费方式，减少双份默认注册逻辑的漂移风险。
|
||||
|
||||
完成标志:
|
||||
|
||||
- fallback pipeline 仍可独立工作。
|
||||
- managed stage recorder 与 fallback path 共用同一套默认 native backend 组装逻辑。
|
||||
|
||||
### 4.3 固化 managed SRP v1 能力边界
|
||||
|
||||
状态: `Completed` (`2026-04-26`)
|
||||
|
||||
目标: 把现有 managed API 从“隐式能力集合”收敛成明确的 v1 contract，便于后续扩展而不是继续误判能力上限。
|
||||
|
||||
执行:
|
||||
|
||||
- 整理 `ScriptableRenderContext`、`ScriptableRenderPipelinePlanningContext`、`RenderSceneSetupContext`、`DirectionalShadowExecutionContext` 的能力矩阵。
|
||||
- 对“fullscreen raster-only”“仅 fullscreen sequence stage flush managed raster pass”“scene draw 仍依赖 native backend”等限制补齐断言、测试和文档。
|
||||
- 补齐 `UniversalPostProcessBlock` 当前的真实语义说明：默认后处理并未在 block 内完成，仍主要依赖 feature / pass 注入与 `FinalOutput` 内置 pass。
|
||||
|
||||
完成标志:
|
||||
|
||||
- managed 侧能做什么、不能做什么有明确边界。
|
||||
- 后续计划不再把现有 API 误写成完整 URP runtime 或通用 RenderGraph API。
|
||||
|
||||
### 4.4 稳住 renderer authoring / invalidation / bridge refresh
|
||||
|
||||
状态: `Completed` (`2026-04-26`)
|
||||
|
||||
目标: 把当前已经存在但还容易漂移的 authoring 路径变成可回归验证的稳定面。
|
||||
|
||||
执行:
|
||||
|
||||
- 围绕 `rendererDataList`、`defaultRendererIndex`、`UniversalAdditionalCameraData.rendererIndex`、feature `SetDirty` / invalidation、bridge generation refresh 增加 focused tests。
|
||||
- 验证 default asset selection、explicit managed asset selection、bridge rebinding 这三条路径在 frame plan 和实际渲染行为上保持一致。
|
||||
- 明确 renderer 选择、feature 变更和 runtime resource version 之间的刷新链路，避免再次回退到隐式缓存。
|
||||
|
||||
完成标志:
|
||||
|
||||
- renderer 切换、feature 改动、bridge 切换都有回归保护。
|
||||
- `CameraFramePlanBuilder` 和 `CameraRenderer` 对 managed path 的依赖关系稳定可追踪。
|
||||
|
||||
## 5. 下一阶段完成后的验收口径
|
||||
|
||||
- `ScriptableRenderPipelineHost` 的角色描述不再含混。
|
||||
- `DefaultNativeBackend` 与 explicit backend asset 的语义只保留一种真实状态。
|
||||
- `BuiltinForwardPipeline` 不再是继续扩张的“总包类”。
|
||||
- managed SRP v1 的能力边界和限制有文档、有测试、有 fail-fast。
|
||||
- renderer authoring / invalidation / bridge refresh 不再依赖人工记忆。
|
||||
|
||||
## 6. 审核依据
|
||||
|
||||
- `engine/src/Rendering/Execution/SceneRenderer.cpp`
|
||||
- `engine/src/Rendering/Planning/SceneRenderRequestPlanner.cpp`
|
||||
- `engine/src/Rendering/Planning/CameraFramePlanBuilder.cpp`
|
||||
- `engine/src/Rendering/Execution/CameraRenderer.cpp`
|
||||
- `engine/src/Rendering/Internal/RenderPipelineFactory.cpp`
|
||||
- `engine/src/Rendering/Pipelines/ScriptableRenderPipelineHost.cpp`
|
||||
- `engine/src/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.cpp`
|
||||
- `engine/src/Rendering/Pipelines/Internal/BuiltinForwardSceneSetup.cpp`
|
||||
- `engine/src/Scripting/Mono/MonoScriptRuntime.cpp`
|
||||
- `managed/XCEngine.ScriptCore/Rendering/Core/ScriptableRenderContext.cs`
|
||||
- `managed/XCEngine.ScriptCore/Rendering/Core/ScriptableRenderPipelinePlanningContext.cs`
|
||||
- `managed/XCEngine.ScriptCore/Rendering/Core/RenderSceneSetupContext.cs`
|
||||
- `managed/XCEngine.ScriptCore/Rendering/Graph/RenderGraphRasterPassBuilder.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`
|
||||
|
||||
Reference in New Issue
Block a user