90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# SceneRenderRequestUtils
|
||
|
||
**命名空间**: `XCEngine::Rendering::SceneRenderRequestUtils`
|
||
|
||
**类型**: `utility header`
|
||
|
||
**头文件**: `XCEngine/Rendering/SceneRenderRequestUtils.h`
|
||
|
||
**描述**: 提供相机可用性判断、稳定排序、clear flag 推导、render area 计算和 request 组装等内联 helper。
|
||
|
||
## 概览
|
||
|
||
`SceneRenderRequestUtils.h` 是当前相机请求规划链路的规则库。
|
||
|
||
和 [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 的职责分工是：
|
||
|
||
- 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` 仍可由上层继续补全。
|
||
|
||
## 相关文档
|
||
|
||
- [当前模块](../Rendering.md)
|
||
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
|
||
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
|
||
- [SceneRenderer](../SceneRenderer/SceneRenderer.md)
|