XCEngine/docs/plan/Renderer_C++层第一阶段收口计划_2026-04-13_晚间.md

# Renderer C++层第一阶段收口计划

日期: `2026-04-13`

## 1. 文档定位

这份文档是 `Render Graph` 之前的最后一轮 `native render kernel v1` 收口计划。

目标不是继续往当前 `Rendering` 层里塞新功能，而是先把下面几件事彻底做清楚：

- `request -> frame plan -> execution` 三层语义分开。
- `RenderSceneExtractor -> CullingResults -> RendererList -> DrawSettings` 这条数据组织链正式化。
- `BuiltinForwardPipeline` 从“大杂烩渲染器”收成“协调器 + 子能力”。
- `Editor` 注入点、阴影、主场景、后处理之间的边界说清楚。
- 给下一步 `C++ Render Graph` 留出稳定输入，而不是把当前混乱直接 graph 化。

结论先写在前面：

- `Render Graph` 应该做在 `C++ native` 层。
- 现在还不应该直接开做 `Render Graph` 或 `Deferred Renderer`。
- 当前更优先的是把现有渲染层整理干净，再往 SRP/URP 方向演进。

## 2. 当前阶段已经完成的收口

截至 `2026-04-13` 晚间，已经落地的内容：

- `CameraRenderRequest -> CameraFramePlan` 已经分层，`CameraRenderer` 开始正式消费 plan。
- `CullingResults / RendererList` contract 已经进入 `RenderSceneData`。
- `Forward / Depth / ObjectId` 已经优先走 `RendererList`，旧 `visibleItems` 只保留过渡 fallback。
- `RendererListUtils` 已经把可见项遍历规则收口成公共工具。
- `Gaussian / Volumetric` 已经从 `BuiltinForwardPipeline` 中抽成统一 `SceneRenderFeaturePass`。
- `FrameExecutionContext / ScenePhase / DrawSettings` 已经引入。
- `RenderPipeline` 已经支持新的 `FrameExecutionContext` 入口，旧三参数入口保留为兼容适配层。
- `BuiltinForwardPipeline` 已经开始按 scene phase 组织主场景执行。
- `CameraRenderer` 主场景阶段已经走新的 execution context，而不是继续只传三参数。

本轮验证结果：

- `XCEditor` 已重新编译通过。
- `rendering_unit_tests` 已重新编译通过。
- `editor_tests` 已重新编译通过。
- `editor_tests --gtest_filter=*ViewportRenderFlow*:*SceneViewportRenderPassBundle* --gtest_brief=1` 通过 `14/14`。
- `rendering_unit_tests --gtest_filter=*BuiltinForwardPipeline*:*RenderPass*:*CameraSceneRenderer*:*Shadow*:*ObjectId* --gtest_brief=1` 通过 `67/68`。
- 唯一失败仍然是既有老问题：
  `BuiltinForwardPipeline_Test.OpenGLRuntimeTranspilesForwardShadowVariantToLegacyClipConventions`

## 3. 为什么现在还不能直接上 Render Graph

现在直接上 `Render Graph`，本质上是在 graph 里继续承接当前的隐式耦合，问题只会换个位置存在。

当前还没完全收口的核心问题不是“没有 graph”，而是下面这些边界还不够正式：

- `CameraRenderer` 和各类 scene pass 之间，谁负责组织阶段，谁负责执行，还没有完全模块化。
- `Shadow` 相关逻辑仍然分散在 planner、camera execution、pipeline、surface cache 几处。
- `BuiltinForwardPipeline` 虽然已经开始瘦身，但还没有彻底收成一个明确的 coordinator。
- `Editor` 的扩展点虽然已可用，但 contract 还偏“约定式”，还不够像以后给 `C# SRP` 暴露的正式接口。
- 目录结构仍然在暴露旧历史：一些“子系统”目前还是文件堆，不是真正的模块。

如果这些问题不先解决，`Render Graph` 只会变成一个新的承压层，后面再拆更贵。

## 4. Render Graph 和未来 SRP/URP 的边界

未来的推荐结构仍然是这条线：

`RHI -> Native Render Kernel -> Render Graph -> SRP-like Contract -> Universal Renderer -> C# Custom Pipeline`

其中边界应当明确成这样：

- `C++ native` 保留：
  - `Render Graph`
  - `CullingResults / RendererList`
  - draw / dispatch context
  - GPU resource cache
  - shadow map / atlas 执行能力
  - Gaussian 排序与 working set
  - Volume 资源上传与底层执行
- `URP-like` 包层保留：
  - feature 编排
  - pass 注入顺序
  - renderer feature 配置
  - 用户级 pipeline 组合
  - 未来的 `C#` 自定义渲染管线 API

这意味着：

- 阴影、Gaussian、Volumetric 不是整块搬去包层。
- 包层更像 Unity 的 `URP renderer` 和 `renderer feature`。
- native 层更像 Unity 没公开给用户、但真正负责执行和图资源生命周期的内核。

## 5. 第一阶段还差哪些工作才能收口

### 5.1 Shadow 子系统正式化

这是当前最值得先做的一块。

现状问题：

- 阴影规划在 `Planning`。
- 阴影 surface/cache 在 `Execution/Caches`。
- 阴影执行又是 standalone pass。
- 主场景采样阴影的状态切换仍在 `BuiltinForwardPipeline`。

这说明阴影现在“能跑”，但还不是一个正式子系统。

收口目标：

- 明确 `shadow planning / shadow resources / shadow execution / shadow sampling contract` 四层边界。
- 把方向光阴影相关共享数据收成一组正式类型，而不是散落在多个调用点上。
- 为以后扩展 `cascades / shadow atlas / additional light shadows / baked shadowmask` 留出位置。

### 5.2 Editor 注入点正式化

现状问题：

- 当前有 `pre scene / post scene / overlay / object id / outline / grid` 多种 editor 路径。
- 这些能力已经能工作，但还没有统一成“正式 stage 注入 contract”。

收口目标：

- 明确哪些注入点属于 runtime 正式阶段，哪些属于 editor-only extension。
- 让 `CameraFramePlan` 对这些阶段的描述更加稳定。
- 给以后 `C# renderer feature` 的注入点设计提供 native 对照物。

### 5.3 BuiltinForwardPipeline 继续瘦身

本轮已经完成第一刀，但还没收完。

还需要继续做的事情：

- 把 forward scene phase 执行和底层 draw/resource 逻辑彻底分开。
- 把 forward renderer 自己的内部资源、skybox、feature 协调代码进一步收拢。
- 保证 `BuiltinForwardPipeline` 自己只表达“阶段顺序和协调”，不再继续膨胀。

### 5.4 旧 fallback 的裁边

当前有一些过渡兼容层是故意保留的：

- `RenderPipeline::Render(context, surface, sceneData)` 旧入口
- `visibleItems` fallback
- `BuildRenderRequests` 旧习惯入口

这些现在不该硬删，因为会影响现有 tests 和 editor 链路。

但第一阶段收口前，至少要做到：

- 新主链默认只走正式 contract。
- 旧入口只作为 adapter，不再新增依赖。
- 每个 fallback 都有明确退出条件。

### 5.5 测试和文档补齐

当前已有回归还不够系统。

还需要补的重点测试：

- `FrameExecutionContext` 是否完整透传 source surface / source color view / state。
- `BuiltinForwardPipeline` scene phase 顺序是否稳定。
- feature pass 的 `Prepare -> Execute` 顺序是否稳定。
- editor 注入点在有后处理和无后处理两种情况下是否仍能保持正确 source/destination surface。
- shadow planning 和 main scene shadow sampling 之间的契约测试。

## 6. 下一步最优先该做什么

下一步最优先建议做：

`Shadow 子系统收口`

原因很直接：

- 它横跨 `Planning / Execution / Pipeline / Resources / Sampling`。
- 它是以后 `Deferred / Light Baking / ShadowMask / Additional Light Shadows` 的共同基础。
- 它也是未来 `Render Graph` 最敏感的一类资源依赖链。
- 如果阴影先不收，后面 graph 化时 barrier、resource lifetime、pass dependency 都会更乱。

建议顺序：

1. 先把方向光阴影的 plan/data/resource/execute contract 固化。
2. 再把 editor 注入 contract 固化。
3. 然后做第一轮目录收拢。
4. 最后判断这一阶段是否可以正式收口，进入 `Render Graph` 设计。

## 7. 当前 Rendering 目录结构存在的问题

### 7.1 `FrameData` 目录太杂

现在 `FrameData` 里同时混着：

- camera/environment 数据
- scene snapshot
- visible item
- culling results
- renderer list utils

这说明它不是一个明确模块，而是“跟帧有关的先放这”。

建议方向：

- `FrameData` 保留纯只读帧快照类型。
- 把 `CullingResults / RendererList / Filtering / Sorting / DrawSettings` 逐步收进更明确的 `Execution` 或 `Culling` 子域。
- `RendererListUtils` 这种执行辅助逻辑，不适合长期留在 `FrameData`。

### 7.2 `Passes` 目录混合了三类东西

现在 `Passes` 里同时有：

- 主场景 pass
- fullscreen/post-process pass
- editor pass

这会让“runtime 正式渲染能力”和“editor 辅助渲染能力”继续混在一起。

建议方向：

- `Passes/Scene`
- `Passes/Fullscreen`
- `Passes/Editor`
- `Passes/Shadow`

不一定要一次性全搬，但后面新增文件不应继续平铺。

### 7.3 `BuiltinForwardPipeline` 还没形成真正子模块

当前 forward 相关代码已经分散在：

- `BuiltinForwardPipeline.h/.cpp`
- `BuiltinForwardPipelineSkybox.cpp`
- `Internal/BuiltinForwardPipelineResources.cpp`

这已经具备“应该单独成目录”的条件。

建议方向：

- `Rendering/Pipelines/BuiltinForward/`
  - `BuiltinForwardPipeline.h`
  - `BuiltinForwardPipeline.cpp`
  - `BuiltinForwardPipelineScene.cpp`
  - `BuiltinForwardPipelineResources.cpp`
  - `BuiltinForwardPipelineSkybox.cpp`

这样后面 forward / deferred / universal renderer 才能并列演进。

### 7.4 `Shadow` 目录还不算真正的 shadow 子系统

目前虽然已经有 `Rendering/Shadow`，但从全链路看，阴影的责任仍然散在其他目录。

建议方向：

- `Shadow` 目录最终至少容纳：
  - planning types
  - shared frame data
  - runtime resources / caches
  - shadow executor or shadow renderer

### 7.5 `Internal` 边界不稳定

现在 `src/Rendering/Internal` 更像历史遗留缓冲区。

长期风险：

- 真正属于 forward 的内部实现放在全局 `Internal`
- 真正属于 volume / splat / shadow 的内部实现也可能继续堆进去

建议方向：

- 全局 `Internal` 只保留跨模块公共 helper。
- 各子系统自己的内部文件放回各自目录。

## 8. 建议的第一轮目录收拢动作

这一轮只做低风险收拢，不做大搬家。

建议动作：

- 把 `BuiltinForwardPipeline*` 相关实现收成 `Pipelines/BuiltinForward/` 子目录。
- 给 `Passes` 至少先分出 `Editor` 和 `Fullscreen` 两个子目录。
- 给 `Shadow` 补一组正式 shared types，再决定是否移动更多实现文件。
- 暂时不大动 `include` 层 public 路径，先保证编译和引用稳定。

原则：

- 先按职责拆，再按目录搬。
- 不为了“好看”做纯目录手术。
- 每次收拢都必须带编译和回归。

## 9. 第一阶段收口完成的判定标准

满足下面这些条件，就可以认为 `Render Graph` 之前这一阶段基本收口：

- `CameraFramePlan` 成为主执行入口，旧 request 入口只保留兼容壳。
- `FrameExecutionContext / ScenePhase / DrawSettings` 成为主场景执行正式 contract。
- `CullingResults / RendererList` 成为主要 draw organization contract。
- `BuiltinForwardPipeline` 被收成 coordinator，而不是继续长成总垃圾堆。
- `Shadow` 成为清晰子系统，而不是散点逻辑。
- `Editor` 注入点形成稳定 contract。
- 目录结构不再继续鼓励“新逻辑直接往老文件里塞”。
- 相关 tests 和编译链稳定。

到这一步，再开始 `C++ Render Graph`，代价才是可控的。

## 10. 当前建议

当前最佳路线不变：

- 短期：继续按 Unity 的 `SRP + URP` 方向做 native 基座。
- 中期：先在 `C++` 做出稳定的 `Render Graph + RendererList + Feature Injection` 内核。
- 中长期：再暴露 `C#` 自定义渲染管线接口，做你自己的 `URP-like` 包层。

眼下最正确的动作不是“赶紧补 deferred”，也不是“先把所有特效搬去包层”，而是：

`先把当前 native rendering layer 整理成一个真正可扩展的内核。`