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

# SceneRenderer

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

**类型**: `class`

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

**描述**: 场景级执行入口，负责构建或接收 `CameraRenderRequest`，补齐 fullscreen 阶段请求，再交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。

## 概览

`SceneRenderer` 是 Rendering 执行层的外层编排器。

它一方面承接 [SceneRenderRequestPlanner](../../Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 的结果，另一方面又比纯 planner 多做了一层“执行前补全”：

- 解析每个相机的 `FinalColorPolicy`
- 为 post-process / final-output 生成 pass sequence
- 为 fullscreen 阶段分配中间 surface cache

所以它不只是“把 planner 的结果原样转发给 `CameraRenderer`”，而是执行层和规划层之间的桥。

## 当前持有对象

- `m_requestPlanner`
  负责基础 request 生成。
- `m_cameraRenderer`
  负责单 request 真正执行。
- `m_ownedPostProcessSequences`
- `m_ownedFinalOutputSequences`
- `m_ownedFullscreenStageSurfaces`
  这些对象保存当前帧由 `SceneRenderer` 自己构建出来的 fullscreen 阶段资源。

## 当前职责

- 从 `Scene + overrideCamera + surface` 生成 request 数组
- 为 request 解析最终输出策略
- 为 request 挂接 post-process / final-output 子请求
- 对 request 数组做稳定排序并逐条执行
- 维护自己创建的 fullscreen surface 的资源状态

## 设计理念

### 为什么 fullscreen 链放在 `SceneRenderer`

planner 只该关心“这一帧有哪些相机 request”；  
而 fullscreen pass sequence 和中间 render target 明显属于执行阶段的临时对象。

把这层逻辑放在 `SceneRenderer`，有两个直接好处：

- planner 仍然可以保持轻量、纯规则化
- `CameraRenderer` 仍然只处理“单条 request 如何执行”，不会反向承担 per-frame 资源编排

## 当前实现边界

- 不直接做 scene extraction；那属于 `CameraRenderer`
- 不直接参与主管线内部 draw-call 组织；那属于 `RenderPipeline`
- 对手工传入的 request 数组，仍然会再次稳定排序，以保持统一的 camera stack 语义

## 公开方法

| 方法 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 构造场景级执行入口。 |
| [Destructor](Destructor.md) | 默认析构。 |
| [SetPipeline](SetPipeline.md) | 替换当前主管线实例。 |
| [SetPipelineAsset](SetPipelineAsset.md) | 通过 asset 重建主管线。 |
| [GetPipeline](GetPipeline.md) | 返回当前主管线的非拥有指针。 |
| [GetPipelineAsset](GetPipelineAsset.md) | 返回当前 pipeline asset 的非拥有指针。 |
| [BuildRenderRequests](BuildRenderRequests.md) | 生成并补齐当前帧 request 数组。 |
| [Render](Render.md) | 执行单个 request、request 数组，或从场景直接生成并执行。 |

## 相关文档

- [Execution](../Execution.md)
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [SceneRenderRequestPlanner](../../Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
- [SceneRenderRequestUtils](../../Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md)
- [CameraRenderRequest](../../Planning/CameraRenderRequest/CameraRenderRequest.md)