110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# CameraRenderer
|
||
|
||
**命名空间**: `XCEngine::Rendering`
|
||
|
||
**类型**: `class`
|
||
|
||
**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h`
|
||
|
||
**描述**: 单个 `CameraRenderRequest` 的执行器，负责在一次提交里串起 scene extraction、shadow/depth 预 pass、主主管线、object-id，以及注入式 pre/post/overlay pass。
|
||
|
||
## 概述
|
||
|
||
`CameraRenderer` 是当前 Rendering 模块里的“单 request 执行层”。它不负责决定应该渲染哪些相机，也不负责 request 排序；这些职责在 [SceneRenderer](../SceneRenderer/SceneRenderer.md) 与 [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)。
|
||
|
||
它关心的是另一件事：一份已经组装好的 `CameraRenderRequest`，到底按什么顺序跑完。
|
||
|
||
## 当前持有的运行时对象
|
||
|
||
- `m_sceneExtractor`
|
||
使用 request surface 的 render-area 尺寸提取当前相机对应的 `RenderSceneData`。
|
||
- `m_pipelineAsset`
|
||
当前主管线的创建来源工厂；可能为空。
|
||
- `m_pipeline`
|
||
当前实际执行主场景绘制的 runtime [RenderPipeline](../RenderPipeline/RenderPipeline.md)。
|
||
- `m_objectIdPass`
|
||
按需消费 `request.objectId` 的 object-id pass；默认是 [Passes::BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。
|
||
- `m_depthOnlyPass`
|
||
按需消费 `request.depthOnly` 的独立 scene pass；默认是 [Passes::BuiltinDepthOnlyPass](../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)。
|
||
- `m_shadowCasterPass`
|
||
按需消费 `request.shadowCaster` 的独立 scene pass；默认是 [Passes::BuiltinShadowCasterPass](../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)。
|
||
|
||
这意味着 `CameraRenderer` 不替调用方生成 Scene View 的特殊效果，但会直接消费 request 上已经明确给出的 depth-only / shadow-caster / object-id / post / overlay 槽位。
|
||
|
||
## 当前执行顺序
|
||
|
||
对一份有效 request，当前 `Render()` 的主顺序是：
|
||
|
||
1. 校验 request、自身主管线、render-area，以及 `shadowCaster / depthOnly / objectId` 请求前置条件。
|
||
2. 用 `m_sceneExtractor.ExtractForCamera(...)` 生成 `RenderSceneData`。
|
||
3. 用 request 覆盖 `sceneData.cameraData.clearFlags`，必要时再覆盖 `clearColor`。
|
||
4. 执行 `preScenePasses`。
|
||
5. 如请求了 shadow-caster，执行 `m_shadowCasterPass`。
|
||
6. 如请求了 depth-only，执行 `m_depthOnlyPass`。
|
||
7. 执行 `m_pipeline->Render(...)`。
|
||
8. 如请求了 object-id，执行 `m_objectIdPass->Render(...)`。
|
||
9. 执行 `postScenePasses`。
|
||
10. 执行 `overlayPasses`。
|
||
11. 按已初始化的 sequence 逆向 `Shutdown()`。
|
||
|
||
`tests/Rendering/unit/test_camera_scene_renderer.cpp` 已覆盖这条顺序，包括 shadow-caster / depth-only 位于主主管线之前这一点。
|
||
|
||
## 生命周期与回退策略
|
||
|
||
- 默认构造会使用静态共享的 [BuiltinForwardPipelineAsset](../Pipelines/BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md)，并同时创建 builtin object-id / depth-only / shadow-caster pass。
|
||
- `SetPipeline()` 走“手动注入 runtime pipeline”路径，并清空当前 `m_pipelineAsset`。
|
||
- `SetPipelineAsset()` 走“由 asset 创建 runtime pipeline”路径；传空时会回退到默认 asset。
|
||
- `ResetPipeline()` 会先 `Shutdown()` 旧主管线，再接管新实例；若新实例为空，则再次回退到默认 asset 并创建 builtin forward。
|
||
- [SetObjectIdPass](SetObjectIdPass.md) 会先关闭旧 pass；传空时回退到 builtin object-id pass。
|
||
- [SetDepthOnlyPass](SetDepthOnlyPass.md) 会先关闭旧 pass；传空时回退到 builtin depth-only pass。
|
||
- [SetShadowCasterPass](SetShadowCasterPass.md) 会先关闭旧 pass；传空时回退到 builtin shadow-caster pass。
|
||
|
||
## 当前验证规则
|
||
|
||
`Render()` 当前会显式拒绝：
|
||
|
||
- `request.IsValid()` 为假
|
||
- 当前 `m_pipeline == nullptr`
|
||
- `request.surface` 的 render-area 宽或高为 `0`
|
||
- 请求了 shadow-caster，但 `request.shadowCaster.IsValid()` 为假
|
||
- 请求了 depth-only，但 `request.depthOnly.IsValid()` 为假
|
||
- 请求了 object-id，但 `request.objectId.IsValid()` 为假
|
||
|
||
## 当前实现边界
|
||
|
||
- 这里只执行单个 request；多相机排序、stack 顺序和 clear 规则在 `SceneRenderer` / `SceneRenderRequestPlanner` 层完成。
|
||
- 这里只消费 request 上已经存在的 scene-pass 与 pass-sequence 槽位，不主动构建 editor 专用 overlay。
|
||
- post / overlay 阶段仍然只是顺序执行的 `RenderPassSequence`，不是 render graph。
|
||
|
||
## 公开方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| [Constructor](Constructor.md) | 构造 `CameraRenderer`，并决定主主管线与 builtin 独立 pass 的初始来源。 |
|
||
| [Destructor](Destructor.md) | 关闭当前主管线、object-id pass、depth-only pass 与 shadow-caster pass。 |
|
||
| [SetPipeline](SetPipeline.md) | 手动替换当前 runtime pipeline。 |
|
||
| [SetPipelineAsset](SetPipelineAsset.md) | 通过 `RenderPipelineAsset` 重建当前 runtime pipeline。 |
|
||
| [SetObjectIdPass](SetObjectIdPass.md) | 替换当前 object-id pass。 |
|
||
| [SetDepthOnlyPass](SetDepthOnlyPass.md) | 替换当前 depth-only scene pass。 |
|
||
| [SetShadowCasterPass](SetShadowCasterPass.md) | 替换当前 shadow-caster scene pass。 |
|
||
| [GetPipeline](GetPipeline.md) | 读取当前主管线的非拥有指针。 |
|
||
| [GetPipelineAsset](GetPipelineAsset.md) | 读取当前 pipeline asset 的非拥有指针。 |
|
||
| [GetObjectIdPass](GetObjectIdPass.md) | 读取当前 object-id pass 的非拥有指针。 |
|
||
| [GetDepthOnlyPass](GetDepthOnlyPass.md) | 读取当前 depth-only pass 的非拥有指针。 |
|
||
| [GetShadowCasterPass](GetShadowCasterPass.md) | 读取当前 shadow-caster 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)
|
||
- [BuiltinDepthOnlyPass](../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)
|
||
- [BuiltinShadowCasterPass](../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)
|
||
- [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md)
|
||
- [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md)
|
||
|