docs(rendering): realign api docs to module structure
This commit is contained in:
@@ -0,0 +1,38 @@
|
||||
# SceneRenderRequestPlanner::BuildRequests
|
||||
|
||||
```cpp
|
||||
std::vector<CameraRenderRequest> BuildRequests(
|
||||
const Components::Scene& scene,
|
||||
Components::CameraComponent* overrideCamera,
|
||||
const RenderContext& context,
|
||||
const RenderSurface& surface) const;
|
||||
```
|
||||
|
||||
## 行为说明
|
||||
|
||||
当前实现先调用 [CollectCameras](CollectCameras.md) 取得这次需要处理的相机列表，然后逐个调用 `SceneRenderRequestUtils::BuildCameraRenderRequest(...)` 生成请求。
|
||||
|
||||
构建过程中会维护两类计数：
|
||||
|
||||
- `renderedBaseCameraCount`
|
||||
- 已成功加入结果数组的 request 数量
|
||||
|
||||
这两个计数会传给 `ResolveClearFlags()`，用于推导 `Auto` clear mode 的最终清屏行为。
|
||||
|
||||
## 当前过滤规则
|
||||
|
||||
- 如果某台相机最终生成的 request render area 宽高为 `0`，该请求会被跳过。
|
||||
- 只有真正成功加入结果数组的 base camera，才会推进 `renderedBaseCameraCount`。
|
||||
- 方法不会抛出失败原因；调用方只会拿到最终保留下来的请求数组。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 一组已经完成基础字段填充的 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)。
|
||||
- 结果可能为空，例如没有可用相机，或所有相机的 render area 都被裁成了零尺寸。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneRenderRequestPlanner](SceneRenderRequestPlanner.md)
|
||||
- [CollectCameras](CollectCameras.md)
|
||||
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
|
||||
- [SceneRenderer::BuildRenderRequests](../../Execution/SceneRenderer/BuildRenderRequests.md)
|
||||
@@ -0,0 +1,33 @@
|
||||
# SceneRenderRequestPlanner::CollectCameras
|
||||
|
||||
```cpp
|
||||
std::vector<Components::CameraComponent*> CollectCameras(
|
||||
const Components::Scene& scene,
|
||||
Components::CameraComponent* overrideCamera) const;
|
||||
```
|
||||
|
||||
## 行为说明
|
||||
|
||||
当前实现按下面的顺序决定这次真正参与渲染规划的相机列表：
|
||||
|
||||
1. 如果 `overrideCamera` 通过 [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) 的 `IsUsableCamera()` 检查，则只返回这一台相机。
|
||||
2. 否则从 `scene` 里收集全部 `CameraComponent`。
|
||||
3. 过滤掉不可用相机。
|
||||
4. 调用 `SceneRenderRequestUtils::SortSceneCamerasForRendering(...)` 做稳定排序。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 一个已经过滤并排序好的相机数组。
|
||||
- 如果没有任何可用相机，返回空数组。
|
||||
|
||||
## 当前排序语义
|
||||
|
||||
- `base` 相机会排在 `overlay` 前面。
|
||||
- 同一 stack 类型内部再按 `depth` 升序。
|
||||
- 排序使用 `std::stable_sort()`，所以完全同键时仍保留场景原始枚举顺序。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SceneRenderRequestPlanner](SceneRenderRequestPlanner.md)
|
||||
- [BuildRequests](BuildRequests.md)
|
||||
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
|
||||
@@ -6,32 +6,80 @@
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h`
|
||||
|
||||
**描述**: 从场景和可选 override camera 生成最终要提交给执行层的 `CameraRenderRequest` 数组。
|
||||
**描述**: 负责从场景和可选 override camera 生成实际要提交给 `CameraRenderer` 的相机请求列表。
|
||||
|
||||
## 概览
|
||||
|
||||
`SceneRenderRequestPlanner` 处在 request planning 主链的中心位置。
|
||||
`SceneRenderRequestPlanner` 处在 [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md) 和 [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) 之间。
|
||||
它不亲自渲染任何东西，而是把“应该渲染哪些相机、按什么顺序、哪些请求应该被丢弃”整理成一组 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)。
|
||||
|
||||
它负责：
|
||||
这种“先规划 request，再执行 request”的拆法很接近商业引擎里常见的 camera scheduling 思路。它的价值不是抽象更漂亮，而是把两类会频繁变化的逻辑拆开：
|
||||
|
||||
- 收集本次要参与渲染的相机
|
||||
- 复用 [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) 的规则组装 request
|
||||
- 丢弃 render area 无效的 request
|
||||
- 场景侧规则：相机收集、stack/depth 排序、clear 推导、viewport 解析
|
||||
- 执行侧规则：scene extraction、主管线、object-id、post/overlay pass
|
||||
|
||||
这样 Editor、离屏渲染和手工 request 注入都能复用同一套规划规则，而不用直接碰 `CameraRenderer` 内部执行链。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [CollectCameras](CollectCameras.md) | 收集本次应参与渲染的相机列表。 |
|
||||
| [BuildRequests](BuildRequests.md) | 把相机列表展开成可执行的 `CameraRenderRequest` 数组。 |
|
||||
|
||||
## 当前规划规则
|
||||
|
||||
- `CollectCameras(...)` 优先接受可用的 `overrideCamera`，否则收集场景相机并做稳定排序。
|
||||
- `BuildRequests(...)` 逐个调用 `BuildCameraRenderRequest(...)`，并维护 base/request 计数以推导 `Auto` clear 行为。
|
||||
### `CollectCameras()`
|
||||
|
||||
当前规则是：
|
||||
|
||||
1. 如果 `overrideCamera` 可用，则只渲染它自己。
|
||||
2. 否则从场景里查找全部 `CameraComponent`。
|
||||
3. 过滤掉不可用相机。
|
||||
4. 按 [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) 里的稳定排序规则整理顺序。
|
||||
|
||||
### `BuildRequests()`
|
||||
|
||||
它会按相机顺序逐个调用 `BuildCameraRenderRequest()`，并维护：
|
||||
|
||||
- `renderedBaseCameraCount`
|
||||
- 已成功生成的 request 数量
|
||||
|
||||
这两个计数会影响自动 clear flag 的推导。
|
||||
如果某个相机最终解析出的 render area 宽高为 `0`，该请求会被直接丢弃，而且不会错误地推进 base camera 计数。
|
||||
|
||||
## 设计取舍
|
||||
|
||||
当前 planner 故意保持“只做一件事”：
|
||||
|
||||
- 负责决定 request 集合
|
||||
- 不负责 request 执行
|
||||
- 不负责附加 pass 组装
|
||||
|
||||
这是一种比很多早期引擎实现更稳的做法。否则 Scene View 一旦要加 object-id、grid、selection outline、editor overlay，规划逻辑和执行逻辑很容易在一个类里互相缠死。
|
||||
|
||||
另一个重要取舍是：当前只支持 base / overlay + depth 的线性排序，而不是更复杂的 stacking 依赖图。
|
||||
这不是文档漏写，而是当前实现的真实边界。它优先保证顺序简单、稳定、可测试。
|
||||
|
||||
## 真实使用位置
|
||||
|
||||
- `engine/include/XCEngine/Rendering/Execution/SceneRenderer.h` 持有一个 `SceneRenderRequestPlanner` 实例。
|
||||
- `engine/src/Rendering/Planning/SceneRenderRequestPlanner.cpp` 实现具体收集与构建逻辑。
|
||||
- `tests/Rendering/unit/test_scene_render_request_planner.cpp` 覆盖了 override camera、稳定排序和零尺寸 viewport 的行为。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 它只生成 request，不执行 request。
|
||||
- 它不填充 `objectId`、fullscreen 阶段或 editor 注入的 pass sequence。
|
||||
- 它只规划相机请求，不处理 `objectId` 或各类 `RenderPassSequence` 的具体填充；那部分通常由更上层调用方补充。
|
||||
- 当前没有 camera stacking 的更复杂依赖分析，只有 base / overlay 与 depth 的线性排序。
|
||||
- `BuildRequests()` 只返回成功构建的请求，不单独报告被过滤掉的相机原因。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Planning](../Planning.md)
|
||||
- [当前模块](../../Rendering.md)
|
||||
- [CollectCameras](CollectCameras.md)
|
||||
- [BuildRequests](BuildRequests.md)
|
||||
- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md)
|
||||
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user