docs: sync scene renderer docs
This commit is contained in:
@@ -6,41 +6,91 @@
|
||||
|
||||
**头文件**: `XCEngine/Rendering/SceneRenderer.h`
|
||||
|
||||
**描述**: 组织一帧场景渲染流程，负责 scene extraction，并把结果交给当前 `RenderPipeline`。
|
||||
**描述**: 场景级渲染编排入口。它负责构建和排序 `CameraRenderRequest`，再把每个请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`SceneRenderer` 是当前渲染模块的主入口。它把“提取场景数据”和“执行具体渲染”两步串起来：
|
||||
`SceneRenderer` 当前不再自己持有 `RenderSceneExtractor` 或直接驱动主管线。它只维护两块运行时对象：
|
||||
|
||||
- 内部持有一个 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
|
||||
- 内部持有一个当前使用的 [RenderPipeline](../RenderPipeline/RenderPipeline.md)
|
||||
- `m_requestPlanner`：负责从 `Scene` 和可选 override camera 生成 `CameraRenderRequest` 列表。
|
||||
- `m_cameraRenderer`：负责真正执行单个相机请求，包括场景提取、主管线提交、object-id pass 和 builtin post-process。
|
||||
|
||||
默认情况下，它会创建 [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)。
|
||||
这意味着当前的主链路已经拆成两层：
|
||||
|
||||
1. `SceneRenderer` 负责“这次要渲染哪些相机、按什么顺序、每个请求的 surface/render-area/clear-flags 是什么”。
|
||||
2. `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`。
|
||||
|
||||
### `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) 负责。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 默认构造会直接创建 `BuiltinForwardPipeline`。
|
||||
- 传入空 pipeline 时，构造函数和 [SetPipeline](SetPipeline.md) 都会退回到 `BuiltinForwardPipeline`。
|
||||
- 析构时如果持有 pipeline，会调用其 `Shutdown()`。
|
||||
- [Render](Render.md) 当前只在运行时触发 pipeline 的 `Render()`，并不会显式先调用 `Initialize()`；默认前向管线靠内部 `EnsureInitialized()` 自己兜底。
|
||||
- 不直接做 scene extraction；真正的 `RenderSceneExtractor` 调用发生在 `CameraRenderer` 里。
|
||||
- 不直接操作 `RenderPipeline` 的初始化或渲染细节；它只负责请求规划和排序。
|
||||
- 对手工提交的请求数组，会再次按相机优先级稳定排序，而不是按调用方原始顺序盲目执行。
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/Rendering/unit/test_camera_scene_renderer.cpp` 当前验证了：
|
||||
|
||||
- `BuildRenderRequests()` 的多相机排序、override camera、clear-flags 和 viewport/render-area 解析。
|
||||
- 手工提交请求数组时的排序和稳定性。
|
||||
- `SetPipeline()` / `SetPipelineAsset()` 的转发、替换与 shutdown 行为。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [Constructor](Constructor.md) | 构造场景渲染器。 |
|
||||
| [Destructor](Destructor.md) | 析构时关闭当前管线。 |
|
||||
| [SetPipeline](SetPipeline.md) | 替换当前渲染管线。 |
|
||||
| [GetPipeline](GetPipeline.md) | 获取当前管线指针。 |
|
||||
| [Render](Render.md) | 渲染一个场景。 |
|
||||
|
||||
## 设计说明
|
||||
|
||||
把 `SceneRenderer` 保持得足够薄，是一个正确方向。真正复杂的渲染逻辑应该沉到 pipeline，而不是让 renderer 主入口变成一坨硬编码流程。
|
||||
| [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.md)
|
||||
- [Rendering](../Rendering.md)
|
||||
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
|
||||
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
|
||||
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
|
||||
- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)
|
||||
- [RenderPipeline](../RenderPipeline/RenderPipeline.md)
|
||||
- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md)
|
||||
|
||||
Reference in New Issue
Block a user