XCEngine/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md

# CameraRenderRequest

**命名空间**: `XCEngine::Rendering`

**类型**: `struct + related enums + related structs`

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

**描述**: 单相机渲染提交的显式数据契约，统一描述主场景、阴影、depth-only、fullscreen、object-id 和 editor 注入阶段。

## 概览

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

当前头文件里与它一同公开的核心类型包括：

- `CameraFrameStage`
- `CameraFrameStageInfo`
- `ScenePassRenderRequest`
- `DirectionalShadowRenderPlan`
- `ObjectIdRenderRequest`
- `FullscreenPassRenderRequest`
- `CameraRenderRequest`

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

## 关键字段

| 字段 | 角色 |
|------|------|
| `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` | 调用方注入的附加阶段序列。 |

## 当前阶段顺序

`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。

## 相关文档

- [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)