5.9 KiB
CameraRenderRequest
命名空间: XCEngine::Rendering
类型: struct + related enums + related structs
头文件: XCEngine/Rendering/Planning/CameraRenderRequest.h
描述: 单相机渲染提交的显式数据契约，统一描述主场景、阴影、depth-only、fullscreen、object-id 和 editor 注入阶段。
概览
CameraRenderRequest 处在 Planning 和 Execution 之间。
它不直接渲染任何内容，而是把“这一台相机这一帧该怎样执行”压平成一份可验证、可排序、可扩展的 request。
当前头文件里与它一同公开的核心类型包括：
CameraFrameStageCameraFrameStageInfoScenePassRenderRequestDirectionalShadowRenderPlanObjectIdRenderRequestFullscreenPassRenderRequestCameraRenderRequest
这套设计的价值在于：规划层只需要把 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：
PreScenePassesShadowCasterDepthOnlyMainScenePostProcessFinalOutputObjectIdPostScenePassesOverlayPasses
这意味着 fullscreen 阶段和 object-id 不再是调用方各自拼出来的旁路，而是 request 模型里的正式阶段。
子请求模型
ScenePassRenderRequest
depthOnly 和 shadowCaster 当前都只是 ScenePassRenderRequest 的别名。
它描述“在主 RenderPipeline 前，是否要额外执行一次 scene pass”。
- IsRequested 只判断是否真的挂了目标附件。
- IsValid 进一步要求深度附件、颜色附件和 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 只检查
scene、camera和context，不会替执行层验证所有子请求。 CameraRenderer::Render()还会继续拒绝无效的depthOnly、postProcess、finalOutput、objectId，以及无法解析的 shadow-caster 请求。SceneRenderer::Render(const std::vector<CameraRenderRequest>&)会先按cameraStackOrder -> cameraDepth稳定排序，再逐条提交。
真实使用位置
- SceneRenderRequestPlanner 负责先构建基础 request。
- SceneRenderer 负责补
finalColorPolicy、postProcess和finalOutput。 - editor Scene View 通过
SceneViewportRenderPlan和ViewportHostRenderFlowUtils再补objectId、postScenePasses、overlayPasses与 clear override。 - CameraRenderer 最终按阶段执行整份 request。