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

# SceneRenderRequestUtils

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

**类型**: `utility header`

**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestUtils.h`

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

## 概览

`SceneRenderRequestUtils.h` 是当前相机请求规划链路的规则库。
和 [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 的职责分工是：

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

从工程角度看，`SceneRenderRequestUtils` 其实承担的是“统一规则口径”的角色。它把多相机渲染里最容易在不同调用方之间写散掉的逻辑收口成一套 header-level helper：

- 相机是否可用
- base / overlay 与 depth 的稳定排序
- `CameraClearMode::Auto` 的默认推导
- viewport 到最终 render area 的换算

这样 `SceneRenderer`、`SceneRenderRequestPlanner` 以及手工 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`

这里最值得注意的是：overlay camera 不是永远只清 `Depth`。
如果场景里根本没有 base camera，第一个成功进入队列的 overlay request 仍然会回退到 `All`。这保证了“纯 overlay 场景”也能得到一个稳定起始帧，而不会直接叠到未定义颜色上。

### render area 计算

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

- 左上边界使用 `floor`
- 右下边界使用 `ceil`

这意味着当前系统支持“在已有 render area 上再切子视口”，而不只是对整张 surface 做 0..1 映射。这对 Scene View、离屏窗口和分块渲染都很关键。

### 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` 仍可由上层继续补全。

## 相关文档

- [当前模块](../../Rendering.md)
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md)
- [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md)