# CameraRenderer::Render

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

**类型**: `method`

**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h`

## 签名

```cpp
bool Render(const CameraRenderRequest& request);
```

## 行为说明

执行一次完整的单相机提交。当前实现会把 shadow-caster、depth-only、主场景、object-id，以及调用方注入的 pre / post / overlay pass 串成一条固定顺序的执行链。

## 当前流程

1. 校验 `request.IsValid()`，并确认 `m_pipeline` 非空。
2. 拒绝 render-area 宽或高为 `0` 的 `surface`。
3. 如果请求了 shadow-caster，要让 `request.shadowCaster.IsValid()` 为真。
4. 如果请求了 depth-only，要让 `request.depthOnly.IsValid()` 为真。
5. 如果请求了 object-id，要让 `request.objectId.IsValid()` 为真。
6. 用 `request.surface.GetRenderAreaWidth()` / `GetRenderAreaHeight()` 调用 `m_sceneExtractor.ExtractForCamera(...)`。
7. 若 `sceneData.HasCamera()` 为假，则返回 `false`。
8. 用 request 覆盖 `sceneData.cameraData.clearFlags`；如果 request 提供了 clear-color override，则继续覆盖 `sceneData.cameraData.clearColor`。
9. 依次初始化并执行：
   - `preScenePasses`
   - `m_shadowCasterPass->Execute(...)`
   - `m_depthOnlyPass->Execute(...)`
   - `m_pipeline->Render(...)`
   - `m_objectIdPass->Render(...)`
   - `postScenePasses`
   - `overlayPasses`
10. 按已经成功初始化的 sequence 做逆向 `Shutdown()`。

## `postScenePasses` / `overlayPasses` 接入点

`CameraRenderer` 只消费调用方传入的 pass 序列，不额外构建内部后处理层。

- `postScenePasses` 直接来自调用方提供的 `RenderPassSequence`
- `overlayPasses` 也是同样的注入点
- 编辑器 Scene View 当前会先通过 [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 组装这些序列，再调用 `ApplySceneViewportRenderPlan(...)` 挂到 request

这意味着 Scene View 的无限网格、选中轮廓和编辑器 overlay，已经被上移到 request 组装层，不再由 `CameraRenderer` 内部再做一次翻译。与之相对，`shadowCaster` 和 `depthOnly` 当前仍属于 `CameraRenderRequest` 上的专用 scene-pass 槽位，由 `CameraRenderer` 直接在主主管线之前消费。

## 失败与清理语义

- 任一验证失败会直接返回 `false`。
- `shadowCaster` 或 `depthOnly` 请求校验失败时，不会进入主主管线。
- 任一 sequence 初始化失败会立刻执行对应 `Shutdown()` 回滚。
- `shadowCaster`、`depthOnly`、主管线、object-id pass、post 或 overlay 任一阶段失败，都会按已经初始化过的 sequence 做清理再返回 `false`。

## 参数

- `request` - 本次单相机渲染的完整输入。

## 返回值

- 整条提交流成功执行时返回 `true`。
- request 校验失败、场景提取失败、主管线失败，或任一附加阶段失败时返回 `false`。

## 测试覆盖

`tests/Rendering/unit/test_camera_scene_renderer.cpp` 当前验证了：

- render-area 会影响提取到的相机 viewport 尺寸
- clear-flags 和 clear-color override 会写回 `sceneData.cameraData`
- `shadowCaster / depthOnly / pipeline / object-id / post / overlay` 的执行顺序
- shadow-caster 请求无效、object-id 失败和 post-pass 初始化失败时的回滚路径

## 相关文档

- [CameraRenderer](CameraRenderer.md)
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
- [RenderPipeline::Render](../RenderPipeline/Render.md)
- [SetDepthOnlyPass](SetDepthOnlyPass.md)
- [SetShadowCasterPass](SetShadowCasterPass.md)
- [Passes](../Passes/Passes.md)