XCEngine/docs/api/XCEngine/Rendering/CameraRenderer/CameraRenderer.md

CameraRenderer

命名空间: XCEngine::Rendering

类型: class

头文件: XCEngine/Rendering/CameraRenderer.h

描述: 单个 CameraRenderRequest 的执行器，负责在一次提交里串起 scene extraction、shadow/depth 预 pass、主主管线、object-id，以及注入式 pre/post/overlay pass。

概述

CameraRenderer 是当前 Rendering 模块里的“单 request 执行层”。它不负责决定应该渲染哪些相机，也不负责 request 排序；这些职责在 SceneRenderer 与 SceneRenderRequestPlanner。

它关心的是另一件事：一份已经组装好的 CameraRenderRequest，到底按什么顺序跑完。

当前持有的运行时对象

• m_sceneExtractor 使用 request surface 的 render-area 尺寸提取当前相机对应的 RenderSceneData。
• m_pipelineAsset 当前主管线的创建来源工厂；可能为空。
• m_pipeline 当前实际执行主场景绘制的 runtime RenderPipeline。
• m_objectIdPass 按需消费 request.objectId 的 object-id pass；默认是 Passes::BuiltinObjectIdPass。
• m_depthOnlyPass 按需消费 request.depthOnly 的独立 scene pass；默认是 Passes::BuiltinDepthOnlyPass。
• m_shadowCasterPass 按需消费 request.shadowCaster 的独立 scene pass；默认是 Passes::BuiltinShadowCasterPass。

这意味着 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，并同时创建 builtin object-id / depth-only / shadow-caster pass。
• SetPipeline() 走“手动注入 runtime pipeline”路径，并清空当前 m_pipelineAsset。
• SetPipelineAsset() 走“由 asset 创建 runtime pipeline”路径；传空时会回退到默认 asset。
• ResetPipeline() 会先 Shutdown() 旧主管线，再接管新实例；若新实例为空，则再次回退到默认 asset 并创建 builtin forward。
• SetObjectIdPass 会先关闭旧 pass；传空时回退到 builtin object-id pass。
• SetDepthOnlyPass 会先关闭旧 pass；传空时回退到 builtin depth-only pass。
• SetShadowCasterPass 会先关闭旧 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	构造 CameraRenderer，并决定主主管线与 builtin 独立 pass 的初始来源。
Destructor	关闭当前主管线、object-id pass、depth-only pass 与 shadow-caster pass。
SetPipeline	手动替换当前 runtime pipeline。
SetPipelineAsset	通过 RenderPipelineAsset 重建当前 runtime pipeline。
SetObjectIdPass	替换当前 object-id pass。
SetDepthOnlyPass	替换当前 depth-only scene pass。
SetShadowCasterPass	替换当前 shadow-caster scene pass。
GetPipeline	读取当前主管线的非拥有指针。
GetPipelineAsset	读取当前 pipeline asset 的非拥有指针。
GetObjectIdPass	读取当前 object-id pass 的非拥有指针。
GetDepthOnlyPass	读取当前 depth-only pass 的非拥有指针。
GetShadowCasterPass	读取当前 shadow-caster pass 的非拥有指针。
Render	执行一次完整的单相机提交。

相关文档

• Rendering
• SceneRenderer
• CameraRenderRequest
• RenderSceneExtractor
• RenderPipeline
• ObjectIdPass
• BuiltinDepthOnlyPass
• BuiltinShadowCasterPass
• Camera Request Planning And Clear Rules
• Scene Extraction And Builtin Forward Pipeline