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

CameraRenderer::Render

bool Render(const CameraRenderRequest& request);

行为说明

执行一次完整的单相机提交。当前实现会把主场景、object-id、调用方注入的 post passes 和 overlay passes 串成一条固定顺序的执行链。

当前流程

1. 校验 request.IsValid()，并确认 m_pipeline 非空。
2. 拒绝 render-area 宽或高为 0 的 surface。
3. 如果请求了 object-id，要求 request.objectId.IsValid() 为真。
4. 用 request.surface.GetRenderAreaWidth() / GetRenderAreaHeight() 调用 m_sceneExtractor.ExtractForCamera(...)。
5. 若 sceneData.HasCamera() 为假，则返回 false。
6. 用 request 覆盖 sceneData.cameraData.clearFlags；如果 request 提供了 clear-color override，则继续覆盖 sceneData.cameraData.clearColor。
7. 依次初始化并执行：
   • preScenePasses
   • m_pipeline->Render(...)
   • m_objectIdPass->Render(...)
   • postScenePasses
   • overlayPasses
8. 按已经成功初始化的 sequence 做逆向 Shutdown()。

postScenePasses / overlayPasses 接入点

CameraRenderer 只消费调用方传入的 pass 序列，不再额外构建内部后处理层。

• postScenePasses 直接来自调用方提供的 RenderPassSequence
• overlayPasses 也是同样的注入点
• 编辑器 Scene View 当前会先通过 SceneViewportRenderPlan 组装这些序列，再调用 ApplySceneViewportRenderPlan(...) 挂到 request

这意味着 Scene View 的无限网格、选中轮廓和编辑器 overlay，已经被上移到 request 组装层，不再由 CameraRenderer 内部再做一次翻译。

失败与清理语义

• 任一验证失败会直接返回 false。
• 任一 sequence 初始化失败会立刻执行对应 Shutdown() 回滚。
• 主主管线、object-id pass、post 或 overlay 任一阶段失败，都会按已经初始化过的 sequence 做清理再返回 false。

参数

• request - 本次单相机渲染的完整输入。

返回值

• 整条提交链成功执行时返回 true。
• request 校验失败、场景提取失败、主管线失败，或任一附加阶段失败时返回 false。

测试覆盖

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

• render-area 会影响提取到的相机 viewport 尺寸。
• clear-flags 和 clear-color override 会写回 sceneData.cameraData。
• pre / pipeline / object-id / post / overlay 的执行顺序。
• object-id 失败和 post-pass 初始化失败时的回滚路径。

相关文档

• CameraRenderer
• CameraRenderRequest
• RenderSceneExtractor
• RenderPipeline::Render
• Passes