XCEngine/docs/api/XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md

SceneRenderRequestUtils

命名空间: XCEngine::Rendering::SceneRenderRequestUtils

类型: utility header

头文件: XCEngine/Rendering/SceneRenderRequestUtils.h

描述: 提供相机可用性判断、稳定排序、clear flag 推导、render area 计算和 request 组装等内联 helper。

概览

SceneRenderRequestUtils.h 是当前相机请求规划链路的规则库。

和 SceneRenderRequestPlanner 的职责分工是：

• planner 决定“要处理哪些相机”
• utils 决定“这些相机和请求该怎样排序、怎样计算 clear、怎样落成具体 request”

公开规则

相机可用性

IsUsableCamera() 只接受：

• 非空相机
• 组件启用
• 挂载 GameObject 非空
• 对象处于 IsActiveInHierarchy()

排序

SortSceneCamerasForRendering() 与 SortCameraRenderRequests() 都使用 std::stable_sort()，因此在排序键完全相同的情况下，会保留原始相对顺序。

当前排序键分别是：

• 场景相机: stackType -> depth
• 渲染请求: cameraStackOrder -> cameraDepth

clear flag 推导

ResolveClearFlags() 的规则是：

• ColorAndDepth -> RenderClearFlags::All
• DepthOnly -> RenderClearFlags::Depth
• None -> RenderClearFlags::None
• Auto
  • overlay camera: 本次若还是首个已渲染 request，则清 All，否则只清 Depth
  • base camera: 若还没有任何成功渲染的 base camera，则清 All，否则只清 Depth

render area 计算

ResolveCameraRenderArea() 会把相机 viewportRect 解释为父 RenderSurface 当前 render area 的归一化子矩形：

• 左上边界使用 floor
• 右下边界使用 ceil

request 组装

BuildCameraRenderRequest() 当前会：

• 清空输出 request
• 绑定 scene、camera、context
• 复制输入 surface，再把 render area 改成相机子区域
• 写入 cameraDepth、cameraStackOrder、clearFlags
• 只有 render area 宽高都大于 0 时才返回 true

测试验证的真实行为

tests/Rendering/unit/test_scene_render_request_utils.cpp 已覆盖：

• 空指针 / 禁用 / 非激活相机都会被拒绝
• 场景相机与 request 排序都保持稳定 tie 顺序
• Auto clear mode 在 base / overlay 下的回退行为
• 嵌套 render area 的矩形组合规则
• 零尺寸 viewport 会导致 request 构建失败

当前实现边界

• 这些 helper 是纯局部规则，不处理多表面、多窗口或跨帧状态。
• clear 推导只依赖当前计数，不关心更复杂的 camera stack 依赖关系。
• request 组装阶段只填基础字段；objectId、preScenePasses、postScenePasses 与 overlayPasses 仍可由上层继续补全。

相关文档

• 当前模块
• SceneRenderRequestPlanner
• CameraRenderRequest
• SceneRenderer