# CameraRenderer

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

**类型**: `class`

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

**描述**: 单个 `CameraRenderRequest` 的执行器。它负责在一次相机提交里完成场景提取、主管线渲染、object-id 输出，以及调用方注入的 post / overlay pass 串接。

## 概览

`CameraRenderer` 是当前渲染模块里的“单请求执行层”。和 [SceneRenderer](../SceneRenderer/SceneRenderer.md) 的分工是：

- `SceneRenderer` 负责规划和排序 `CameraRenderRequest`
- `CameraRenderer` 负责把一份 request 真正跑完

因此这里关心的不是“该渲染哪些相机”，而是“这一份相机请求如何被执行”。

## 当前持有的运行时对象

- `m_sceneExtractor`
  使用 `request.surface` 的 render area 尺寸调用 `ExtractForCamera(...)`，生成这次提交要用的 `RenderSceneData`。
- `m_pipelineAsset`
  当前主管线的来源工厂；可能为空。
- `m_pipeline`
  当前实际执行主场景绘制的 runtime [RenderPipeline](../RenderPipeline/RenderPipeline.md)。
- `m_objectIdPass`
  主场景之后的 object-id pass；默认是 [Passes::BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。

这意味着 `CameraRenderer` 本身不负责替调用方生成 Scene View 专用效果；它只按 request 已给出的 `postScenePasses` / `overlayPasses` 顺序执行。

## 当前执行顺序

对一份有效 request，当前 `Render()` 的主顺序是：

1. 校验 request、自身主管线、render-area 和 object-id 请求前置条件。
2. 用 `m_sceneExtractor.ExtractForCamera(...)` 生成 `RenderSceneData`。
3. 用 request 覆盖 `sceneData.cameraData.clearFlags`，必要时再覆盖 `clearColor`。
4. 执行 `preScenePasses`。
5. 执行 `m_pipeline->Render(...)`。
6. 如请求了 object-id，执行 `m_objectIdPass->Render(...)`。
7. 执行 `postScenePasses`。
8. 执行 `overlayPasses`。
9. 按已初始化的 sequence 逆向 `Shutdown()`。

这条顺序被 `tests/Rendering/unit/test_camera_scene_renderer.cpp` 明确覆盖。

## 生命周期与回退策略

- 默认构造会使用静态共享的 [BuiltinForwardPipelineAsset](../Pipelines/BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md)。
- `SetPipeline()` 走“手动注入 runtime pipeline”路径，并清空当前 `m_pipelineAsset`。
- `SetPipelineAsset()` 走“由 asset 创建 runtime pipeline”路径；传空时会回退到默认 asset。
- `ResetPipeline()` 会先 `Shutdown()` 旧主管线，再接管新实例；若新实例为空，则再次回退到默认 asset 并创建 builtin forward。
- `SetObjectIdPass()` 同样会先关闭旧 pass；传空时回退到 builtin object-id pass。

## 当前验证规则

`Render()` 目前会显式拒绝：

- `request.IsValid()` 为假
- 当前 `m_pipeline == nullptr`
- `request.surface` 的 render-area 宽或高为 `0`
- 请求了 object-id，但 `request.objectId.IsValid()` 为假

## 当前实现边界

- 只执行单个 request；多相机排序、stack 顺序和 clear 规则在 `SceneRenderer` / `SceneRenderRequestPlanner` 层完成。
- 不直接决定“默认主管线是什么”，而是通过 pipeline asset seam 解决。
- post / overlay 阶段只是顺序执行的 `RenderPassSequence`，不是 render graph。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 构造 `CameraRenderer`，并建立默认或注入的主管线 / object-id pass。 |
| [Destructor](Destructor.md) | 关闭当前主管线与 object-id pass。 |
| [SetPipeline](SetPipeline.md) | 手动替换当前 runtime pipeline。 |
| [SetPipelineAsset](SetPipelineAsset.md) | 通过 `RenderPipelineAsset` 重建当前 runtime pipeline。 |
| [SetObjectIdPass](SetObjectIdPass.md) | 替换当前 object-id pass。 |
| [GetPipeline](GetPipeline.md) | 读取当前主管线的非拥有指针。 |
| [GetPipelineAsset](GetPipelineAsset.md) | 读取当前 pipeline asset 的非拥有指针。 |
| [GetObjectIdPass](GetObjectIdPass.md) | 读取当前 object-id pass 的非拥有指针。 |
| [Render](Render.md) | 执行一次完整的单相机提交。 |

## 相关文档

- [Rendering](../Rendering.md)
- [SceneRenderer](../SceneRenderer/SceneRenderer.md)
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
- [RenderPipeline](../RenderPipeline/RenderPipeline.md)
- [ObjectIdPass](../ObjectIdPass/ObjectIdPass.md)
- [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md)