docs(rendering): realign api docs to module structure

2026-04-10 16:55:33 +08:00
parent 8cde4e0649
commit 4d8a51aee2
95 changed files with 1136 additions and 1585 deletions
--- a/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md
+++ b/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md
@@ -6,24 +6,14 @@

 **头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h`

-**描述**: 单相机渲染提交的显式请求对象，打包主场景 surface、shadow/depth/object-id/fullscreen 子请求、clear 覆盖、frame-stage 辅助查询，以及可选 pass 序列。
+**描述**: 单相机渲染提交的显式数据契约，统一描述主场景、阴影、depth-only、fullscreen、object-id 和 editor 注入阶段。

 ## 概览

-`CameraRenderRequest` 是 [Planning](../Planning.md) 与 [Execution](../../Execution/Execution.md) 之间最核心的数据契约。
+`CameraRenderRequest` 处在 [Planning](../Planning.md) 和 [Execution](../../Execution/Execution.md) 之间。
+它不直接渲染任何内容，而是把“这一台相机这一帧该怎样执行”压平成一份可验证、可排序、可扩展的 request。

-相较旧版 request 模型，当前头文件已经把更多阶段正式纳入同一份 request：
-
- `shadowCaster`
- `depthOnly`
- `postProcess`
- `finalOutput`
- `objectId`
- `preScenePasses`
- `postScenePasses`
- `overlayPasses`
-
-## 头文件中的主要类型
+当前头文件里与它一同公开的核心类型包括：

 - `CameraFrameStage`
 - `CameraFrameStageInfo`
@@ -33,23 +23,116 @@
 - `FullscreenPassRenderRequest`
 - `CameraRenderRequest`

-## 当前语义
+这套设计的价值在于：规划层只需要把 request 组装完整，执行层就能按统一阶段顺序跑完一台相机，而不必让 editor、runtime、离屏渲染各自维护一套隐式约定。

- `ScenePassRenderRequest` 同时服务 `DepthOnlyRenderRequest` 与 `ShadowCasterRenderRequest`。
- `DirectionalShadowRenderPlan` 保存 directional shadow 相机与 map 配置。
- `FullscreenPassRenderRequest` 同时服务 `PostProcessRenderRequest` 与 `FinalOutputRenderRequest`。
- `HasFrameStage(...)`、`GetPassSequence(...)`、`GetOutputSurface(...)` 让执行层可以按统一阶段名查询 request。
+## 关键字段

-## 当前实现边界
+| 字段 | 角色 |
+|------|------|
+| `scene` / `camera` / `context` | 主场景提取与执行的最小上下文。 |
+| `surface` | 当前相机最终主输出目标。 |
+| `depthOnly` | depth-only scene pass 子请求。 |
+| `shadowCaster` | 显式 shadow-caster scene pass 子请求。 |
+| `directionalShadow` | 仅声明方向光阴影计划；必要时由 `CameraRenderer` 自动生成内部 shadow surface。 |
+| `postProcess` | fullscreen 后处理阶段请求。 |
+| `finalOutput` | fullscreen 最终输出阶段请求。 |
+| `finalColorPolicy` | fullscreen 最终颜色策略的解析结果。 |
+| `objectId` | object-id 辅助输出请求。 |
+| `cameraDepth` / `cameraStackOrder` | 多相机稳定排序键。 |
+| `clearFlags` / `clearColorOverride` | 本次提交覆盖写回 `RenderSceneData::cameraData` 的清屏语义。 |
+| `preScenePasses` / `postScenePasses` / `overlayPasses` | 调用方注入的附加阶段序列。 |

- `IsValid()` 仍只检查 `scene`、`camera` 和 `context` 是否存在，具体子请求完整性由执行层进一步验证。
- request 本身不生成任何 pass；Editor 或更上层系统仍要先把 sequence 和 surface 写进来。
+## 当前阶段顺序
+
+`CameraRenderer` 会按 `kOrderedCameraFrameStages` 解释这份 request：
+
+1. `PreScenePasses`
+2. `ShadowCaster`
+3. `DepthOnly`
+4. `MainScene`
+5. `PostProcess`
+6. `FinalOutput`
+7. `ObjectId`
+8. `PostScenePasses`
+9. `OverlayPasses`
+
+这意味着 fullscreen 阶段和 object-id 不再是调用方各自拼出来的旁路，而是 request 模型里的正式阶段。
+
+## 子请求模型
+
+### `ScenePassRenderRequest`
+
+`depthOnly` 和 `shadowCaster` 当前都只是 `ScenePassRenderRequest` 的别名。
+它描述“在主 `RenderPipeline` 前，是否要额外执行一次 scene pass”。
+
+- [IsRequested](ScenePassRenderRequest/IsRequested.md) 只判断是否真的挂了目标附件。
+- [IsValid](ScenePassRenderRequest/IsValid.md) 进一步要求深度附件、颜色附件和 render area 全部可用。
+- `hasCameraDataOverride` / `cameraDataOverride` 允许这条 scene pass 使用不同于主相机的数据；当前方向光阴影路径会利用这一点。
+
+### `DirectionalShadowRenderPlan`
+
+当 `shadowCaster.surface` 没有显式提供，但 `directionalShadow.IsValid()` 为真时，`CameraRenderer` 会借助 `DirectionalShadowSurfaceCache` 自动构建内部阴影 surface，并把 plan 里的 `cameraData` 写回 shadow-caster 子请求。
+
+### `FullscreenPassRenderRequest`
+
+`postProcess` 和 `finalOutput` 都是 `FullscreenPassRenderRequest` 的别名。
+它们描述：
+
+- 从哪张 source surface 读取
+- 用哪张 `sourceColorView` 作为输入
+- 把结果写到哪张 destination surface
+- 由哪条 `RenderPassSequence` 执行
+
+`SceneRenderer::BuildRenderRequests(...)` 会根据相机后处理描述和 final-color policy 自动补齐这两段 request。
+
+### `ObjectIdRenderRequest`
+
+`objectId` 描述独立的 object-id 辅助输出目标。
+当前执行层要求它至少具备：
+
+- 第一张颜色附件
+- 深度附件
+- 有效 render area
+
+object-id 阶段发生在 `FinalOutput` 之后、`PostScenePasses` 之前。
+
+## 辅助查询函数
+
+头文件还提供了一组阶段化查询 helper：
+
+- `HasFrameStage(...)`
+- `GetPassSequence(...)`
+- `GetScenePassRequest(...)`
+- `GetObjectIdRequest(...)`
+- `GetMainSceneSurface()`
+- `GetFinalCompositedSurface()`
+- `GetOutputSurface(...)`
+- `GetSourceSurface(...)`
+- `GetSourceColorView(...)`
+- `GetSourceColorState(...)`
+- `RequiresIntermediateSceneColor()`
+
+这些 helper 的意义是把“不同阶段该读哪张 surface、写哪张 surface、是否需要中间颜色缓存”统一收口到 request 模型本身，而不是散落在调用方里。
+
+## 当前数据契约
+
+- [IsValid](IsValid.md) 只检查 `scene`、`camera` 和 `context`，不会替执行层验证所有子请求。
+- `CameraRenderer::Render()` 还会继续拒绝无效的 `depthOnly`、`postProcess`、`finalOutput`、`objectId`，以及无法解析的 shadow-caster 请求。
+- `SceneRenderer::Render(const std::vector<CameraRenderRequest>&)` 会先按 `cameraStackOrder -> cameraDepth` 稳定排序，再逐条提交。
+
+## 真实使用位置
+
+- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 负责先构建基础 request。
+- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md) 负责补 `finalColorPolicy`、`postProcess` 和 `finalOutput`。
+- editor Scene View 通过 `SceneViewportRenderPlan` 和 `ViewportHostRenderFlowUtils` 再补 `objectId`、`postScenePasses`、`overlayPasses` 与 clear override。
+- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 最终按阶段执行整份 request。

 ## 相关文档

- [Planning](../Planning.md)
+- [IsValid](IsValid.md)
+- [ScenePassRenderRequest](ScenePassRenderRequest/ScenePassRenderRequest.md)
+- [ObjectIdRenderRequest](ObjectIdRenderRequest/ObjectIdRenderRequest.md)
 - [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
 - [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
 - [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md)
 - [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md)
-