139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
# CameraRenderRequest
|
||
|
||
**命名空间**: `XCEngine::Rendering`
|
||
|
||
**类型**: `struct + related enums + related structs`
|
||
|
||
**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h`
|
||
|
||
**描述**: 单相机渲染提交的显式数据契约，统一描述主场景、阴影、depth-only、fullscreen、object-id 和 editor 注入阶段。
|
||
|
||
## 概览
|
||
|
||
`CameraRenderRequest` 处在 [Planning](../Planning.md) 和 [Execution](../../Execution/Execution.md) 之间。
|
||
它不直接渲染任何内容，而是把“这一台相机这一帧该怎样执行”压平成一份可验证、可排序、可扩展的 request。
|
||
|
||
当前头文件里与它一同公开的核心类型包括：
|
||
|
||
- `CameraFrameStage`
|
||
- `CameraFrameStageInfo`
|
||
- `ScenePassRenderRequest`
|
||
- `DirectionalShadowRenderPlan`
|
||
- `ObjectIdRenderRequest`
|
||
- `FullscreenPassRenderRequest`
|
||
- `CameraRenderRequest`
|
||
|
||
这套设计的价值在于：规划层只需要把 request 组装完整，执行层就能按统一阶段顺序跑完一台相机，而不必让 editor、runtime、离屏渲染各自维护一套隐式约定。
|
||
|
||
## 关键字段
|
||
|
||
| 字段 | 角色 |
|
||
|------|------|
|
||
| `scene` / `camera` / `context` | 主场景提取与执行的最小上下文。 |
|
||
| `surface` | 当前相机最终主输出目标。 |
|
||
| `depthOnly` | depth-only scene pass 子请求。 |
|
||
| `shadowCaster` | 显式 shadow-caster scene pass 子请求。 |
|
||
| `directionalShadow` | 仅声明方向光阴影计划；必要时由 `CameraRenderer` 自动生成内部 shadow surface。 |
|
||
| `postProcess` | fullscreen 后处理阶段请求。 |
|
||
| `finalOutput` | fullscreen 最终输出阶段请求。 |
|
||
| `finalColorPolicy` | fullscreen 最终颜色策略的解析结果。 |
|
||
| `objectId` | object-id 辅助输出请求。 |
|
||
| `cameraDepth` / `cameraStackOrder` | 多相机稳定排序键。 |
|
||
| `clearFlags` / `clearColorOverride` | 本次提交覆盖写回 `RenderSceneData::cameraData` 的清屏语义。 |
|
||
| `preScenePasses` / `postScenePasses` / `overlayPasses` | 调用方注入的附加阶段序列。 |
|
||
|
||
## 当前阶段顺序
|
||
|
||
`CameraRenderer` 会按 `kOrderedCameraFrameStages` 解释这份 request：
|
||
|
||
1. `PreScenePasses`
|
||
2. `ShadowCaster`
|
||
3. `DepthOnly`
|
||
4. `MainScene`
|
||
5. `PostProcess`
|
||
6. `FinalOutput`
|
||
7. `ObjectId`
|
||
8. `PostScenePasses`
|
||
9. `OverlayPasses`
|
||
|
||
这意味着 fullscreen 阶段和 object-id 不再是调用方各自拼出来的旁路，而是 request 模型里的正式阶段。
|
||
|
||
## 子请求模型
|
||
|
||
### `ScenePassRenderRequest`
|
||
|
||
`depthOnly` 和 `shadowCaster` 当前都只是 `ScenePassRenderRequest` 的别名。
|
||
它描述“在主 `RenderPipeline` 前，是否要额外执行一次 scene pass”。
|
||
|
||
- [IsRequested](ScenePassRenderRequest/IsRequested.md) 只判断是否真的挂了目标附件。
|
||
- [IsValid](ScenePassRenderRequest/IsValid.md) 进一步要求深度附件、颜色附件和 render area 全部可用。
|
||
- `hasCameraDataOverride` / `cameraDataOverride` 允许这条 scene pass 使用不同于主相机的数据；当前方向光阴影路径会利用这一点。
|
||
|
||
### `DirectionalShadowRenderPlan`
|
||
|
||
当 `shadowCaster.surface` 没有显式提供，但 `directionalShadow.IsValid()` 为真时，`CameraRenderer` 会借助 `DirectionalShadowSurfaceCache` 自动构建内部阴影 surface，并把 plan 里的 `cameraData` 写回 shadow-caster 子请求。
|
||
|
||
### `FullscreenPassRenderRequest`
|
||
|
||
`postProcess` 和 `finalOutput` 都是 `FullscreenPassRenderRequest` 的别名。
|
||
它们描述：
|
||
|
||
- 从哪张 source surface 读取
|
||
- 用哪张 `sourceColorView` 作为输入
|
||
- 把结果写到哪张 destination surface
|
||
- 由哪条 `RenderPassSequence` 执行
|
||
|
||
`SceneRenderer::BuildRenderRequests(...)` 会根据相机后处理描述和 final-color policy 自动补齐这两段 request。
|
||
|
||
### `ObjectIdRenderRequest`
|
||
|
||
`objectId` 描述独立的 object-id 辅助输出目标。
|
||
当前执行层要求它至少具备：
|
||
|
||
- 第一张颜色附件
|
||
- 深度附件
|
||
- 有效 render area
|
||
|
||
object-id 阶段发生在 `FinalOutput` 之后、`PostScenePasses` 之前。
|
||
|
||
## 辅助查询函数
|
||
|
||
头文件还提供了一组阶段化查询 helper：
|
||
|
||
- `HasFrameStage(...)`
|
||
- `GetPassSequence(...)`
|
||
- `GetScenePassRequest(...)`
|
||
- `GetObjectIdRequest(...)`
|
||
- `GetMainSceneSurface()`
|
||
- `GetFinalCompositedSurface()`
|
||
- `GetOutputSurface(...)`
|
||
- `GetSourceSurface(...)`
|
||
- `GetSourceColorView(...)`
|
||
- `GetSourceColorState(...)`
|
||
- `RequiresIntermediateSceneColor()`
|
||
|
||
这些 helper 的意义是把“不同阶段该读哪张 surface、写哪张 surface、是否需要中间颜色缓存”统一收口到 request 模型本身，而不是散落在调用方里。
|
||
|
||
## 当前数据契约
|
||
|
||
- [IsValid](IsValid.md) 只检查 `scene`、`camera` 和 `context`，不会替执行层验证所有子请求。
|
||
- `CameraRenderer::Render()` 还会继续拒绝无效的 `depthOnly`、`postProcess`、`finalOutput`、`objectId`，以及无法解析的 shadow-caster 请求。
|
||
- `SceneRenderer::Render(const std::vector<CameraRenderRequest>&)` 会先按 `cameraStackOrder -> cameraDepth` 稳定排序，再逐条提交。
|
||
|
||
## 真实使用位置
|
||
|
||
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) 负责先构建基础 request。
|
||
- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md) 负责补 `finalColorPolicy`、`postProcess` 和 `finalOutput`。
|
||
- editor Scene View 通过 `SceneViewportRenderPlan` 和 `ViewportHostRenderFlowUtils` 再补 `objectId`、`postScenePasses`、`overlayPasses` 与 clear override。
|
||
- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 最终按阶段执行整份 request。
|
||
|
||
## 相关文档
|
||
|
||
- [IsValid](IsValid.md)
|
||
- [ScenePassRenderRequest](ScenePassRenderRequest/ScenePassRenderRequest.md)
|
||
- [ObjectIdRenderRequest](ObjectIdRenderRequest/ObjectIdRenderRequest.md)
|
||
- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md)
|
||
- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md)
|
||
- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md)
|
||
- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md)
|