XCEngine/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md

# SceneRenderer

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

**类型**: `class`

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

**描述**: 场景级渲染编排入口。它负责构建和排序 `CameraRenderRequest`，再把每个请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。

## 概览

`SceneRenderer` 当前不再自己持有 `RenderSceneExtractor` 或直接驱动主管线。它只维护两块运行时对象：

- `m_requestPlanner`：负责从 `Scene` 和可选 override camera 生成 `CameraRenderRequest` 列表。
- `m_cameraRenderer`：负责真正执行单个相机请求，包括场景提取、主管线提交、object-id pass，以及 request 上挂接的 pre/post/overlay pass sequence。

这意味着当前的主链路已经拆成两层：

1. `SceneRenderer` 负责“这次要渲染哪些相机、按什么顺序、每个请求的 surface/render-area/clear-flags 是什么”。
2. `CameraRenderer` 负责“单个请求如何真正跑完”。

这条边界是当前 Rendering 模块里最值得保留的设计决定之一。
如果把相机规划和 request 执行重新揉回一个类里，Editor 的 Scene View、object-id picking、overlay 注入和离屏渲染很快就会和主管线细节耦合到一起。

现在的拆法则让 `SceneRenderer` 更像一个稳定的编排入口：

- 从 `Scene` 直接提交时，它负责生成 request
- 从外部手工提交 request 时，它负责复用同一排序规则
- 不管 request 来源是什么，真正执行都统一落到 `CameraRenderer`

## 当前执行路径

### `BuildRenderRequests(...)`

直接委托给 [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)：

```cpp
return m_requestPlanner.BuildRequests(scene, overrideCamera, context, surface);
```

### `Render(const Components::Scene&, ...)`

这是“从场景直接提交”的便捷入口，本质上等价于：

```cpp
return Render(BuildRenderRequests(scene, overrideCamera, context, surface));
```

### `Render(const std::vector<CameraRenderRequest>&)`

当前会：

1. 拒绝空请求数组。
2. 拒绝任何 `IsValid()` 为假的请求。
3. 复制一份请求数组，并通过 `SceneRenderRequestUtils::SortCameraRenderRequests(...)` 做稳定排序。
4. 依次调用 `m_cameraRenderer.Render(request)`。
5. 任一请求失败就立即返回 `false`。

这里不会额外改写 request 里的 `objectId` 或各类 pass sequence；如果上层已经补好了这些字段，`SceneRenderer` 只负责排序后转交执行。

这也是为什么手工 request 提交路径仍然会再次排序。当前实现明确认为“stack/depth 规则”属于 `SceneRenderer` 的稳定契约，而不是调用方各自维护的一套隐式约定。

### `Render(const CameraRenderRequest&)`

这是最薄的一层，直接转发到 `m_cameraRenderer.Render(request)`。

## 构造与默认行为

- 默认构造通过默认构造的 `CameraRenderer` 获得默认主管线与默认 object-id pass。
- 传入 `std::unique_ptr<RenderPipeline>` 时，走“手动注入 runtime pipeline”路径。
- 传入 `std::shared_ptr<const RenderPipelineAsset>` 时，走“由 asset 创建 runtime pipeline”路径。

默认主管线的具体创建不在 `SceneRenderer` 内部硬编码，而是由 `CameraRenderer` 通过默认 [BuiltinForwardPipelineAsset](../Pipelines/BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md) 负责。

## 当前实现边界

- 不直接做 scene extraction；真正的 `RenderSceneExtractor` 调用发生在 `CameraRenderer` 里。
- 不直接操作 `RenderPipeline` 的初始化或渲染细节；它只负责请求规划和排序。
- 不负责替 request 自动补 `objectId` 或各类 `RenderPassSequence`；这类附加阶段通常由 Editor 或其他上层调用方在提交前写入。
- 对手工提交的请求数组，会再次按相机优先级稳定排序，而不是按调用方原始顺序盲目执行。

## 测试覆盖

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

- `BuildRenderRequests()` 的多相机排序、override camera、clear-flags 和 viewport/render-area 解析。
- 手工提交请求数组时的排序和稳定性。
- `SetPipeline()` / `SetPipelineAsset()` 的转发、替换与 shutdown 行为。

这些测试锚点说明，`SceneRenderer` 当前不是一个“薄到没有语义”的转发器。它真正承担了 request planning 契约本身，包括：

- override camera 的回退语义
- base / overlay 排序
- `Auto` clear 的默认策略
- 手工 request 重新排序的稳定性

## 公开方法

| 方法 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 构造 `SceneRenderer`，并决定 `CameraRenderer` 的主管线路径。 |
| [Destructor](Destructor.md) | 默认析构；真正的运行时清理由成员对象完成。 |
| [SetPipeline](SetPipeline.md) | 手动替换当前 runtime `RenderPipeline`。 |
| [SetPipelineAsset](SetPipelineAsset.md) | 通过 `RenderPipelineAsset` 重建当前 runtime `RenderPipeline`。 |
| [GetPipeline](GetPipeline.md) | 返回当前主管线的非拥有指针。 |
| [GetPipelineAsset](GetPipelineAsset.md) | 返回当前 pipeline asset 的非拥有指针。 |
| [BuildRenderRequests](BuildRenderRequests.md) | 生成当前场景对应的相机请求列表。 |
| [Render](Render.md) | 执行单个请求、请求数组，或从场景直接生成请求并执行。 |

## 相关文档

- [Rendering](../Rendering.md)
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
- [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md)