refactor(srp): formalize renderer block recording

docs/used/SRP_URP_RendererBlockFormalizationPlan_2026-04-22_完成归档.md

@@ -0,0 +1,90 @@
+# SRP / URP Renderer Block Formalization Plan
+
+时间：2026-04-22
+
+## 背景
+
+当前渲染主线已经完成了两件更底层的事情：
+
+1. C++ 侧的 RenderGraph / runtime resource / stage contract 已经能稳定承接 managed SRP。
+2. managed 侧也已经有 `ScriptableRenderer / RendererFeature / RenderPass` 这套骨架，并且 post-process / final output 的 graph 绑定已经打通。
+
+但 renderer 这一层还有一个明显的问题没有收口：
+
+- `ScriptableRenderer` 现在还是把所有 pass 丢进一个总队列，然后在录制时按 `CameraFrameStage` 逐个扫描、过滤。
+- 这意味着 renderer 的“组织单位”依然是 stage，而不是 renderer 自己拥有的 block。
+- 对后续把阴影、体积、Gaussian、更多 scene feature 逐步迁到 URP 层不够友好，因为缺少稳定的 block 落点。
+
+这一步的目标不是继续扩 RenderGraph 功能，也不是开始 deferred，而是先把 managed renderer 的组织方式收紧。
+
+## 本阶段目标
+
+把 managed `ScriptableRenderer` 从“单队列 + stage 过滤”重构成“显式 renderer block 录制”，并保持当前 C++ stage 边界不变。
+
+目标结果：
+
+1. `ScriptableRenderer` 内部显式识别 `ShadowCaster / DepthPrepass / MainOpaque / MainSkybox / MainTransparent / PostProcess / FinalOutput`。
+2. stage 仍然只是 native 执行边界，renderer 内部真正按 block 组织与录制。
+3. `UniversalRenderer` 后续迁移阴影、体积、Gaussian 等逻辑时，有稳定的 block 入口可以承接。
+4. 不引入新的兼容层，不保留“旧逻辑先留着”的临时路线。
+
+## 范围
+
+本阶段只做 managed SRP / URP 组织重构，不做：
+
+- deferred rendering
+- shadow 算法升级
+- editor 侧面板与资源工作流
+- ObjectId 这类 editor-only 特性迁移
+
+## 实施步骤
+
+### 1. 补齐 renderer block 基础类型
+
+新增 renderer block 枚举与辅助工具，统一维护：
+
+- pass event -> renderer block
+- renderer block -> camera frame stage
+- renderer block 的运行时范围描述
+
+### 2. 重构 ScriptableRenderer 的录制入口
+
+保留 active pass queue 作为排序输入，但录制逻辑改为：
+
+1. 先按 `RenderPassEvent` 排序构建 active pass queue
+2. 再根据 event range 构建 renderer block range
+3. 按当前 stage 对应的 block 顺序执行
+
+也就是说：
+
+- `MainScene` 不再是“扫完整队列找属于 MainScene 的 pass”
+- 而是显式录制 `MainOpaque -> MainSkybox -> MainTransparent`
+
+### 3. 清理 stage-driven 痕迹
+
+重点清理：
+
+- `ScriptableRenderer` 内部 `renderPass.SupportsStage(...)` 式的全队列过滤
+- 把 `SupportsRendererRecording / RecordRenderer` 改成基于 block 判断
+
+保留：
+
+- native C++ 仍然通过 `CameraFrameStage` 调用 managed
+- `ScriptableRenderPass.SupportsStage(...)` 作为公共 API 兼容入口，但内部改为基于 block 推导
+
+### 4. 验证主线不回退
+
+要求：
+
+1. `XCEditor` Debug 构建通过
+2. old editor 冒烟运行至少 10 秒
+3. `editor.log` 出现 `SceneReady`
+
+## 完成标准
+
+满足以下条件才算本阶段收口：
+
+1. `ScriptableRenderer` 不再通过“单队列 + stage 过滤”驱动录制。
+2. renderer block 成为 managed renderer 内部的正式组织单位。
+3. `UniversalRenderer` 当前默认路径行为不回退。
+4. `XCEditor` 构建与 old editor 冒烟通过。