7.7 KiB
7.7 KiB
Passes
命名空间: XCEngine::Rendering::Passes
类型: submodule
描述: 承载 builtin object-id、selection outline、infinite grid，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套样式/参数类型。
概述
Rendering::Passes 不是用来替代 RenderPipeline 的第二套主渲染框架，而是承载几类被 CameraRenderer、editor 视口流程和 builtin pipeline 复用的 builtin pass：
- BuiltinObjectIdPass 把可见物体编码成 object-id 颜色，写到辅助渲染目标，供拾取和选中反馈使用。
- BuiltinObjectIdOutlinePass 读取 object-id 纹理和选中对象列表，把轮廓或调试 mask 叠加回场景颜色。
- BuiltinInfiniteGridPass 给 Scene View 一类编辑器视口叠加无限网格。
- BuiltinDepthStylePassBase 为深度风格场景重绘 pass 提供共享执行骨架。
- BuiltinDepthOnlyPass 是
CameraRenderer默认depthOnlyrequest 的 builtin 实现。 - BuiltinShadowCasterPass 是
CameraRenderer默认shadowCasterrequest 的 builtin 实现。
其中 object-id / outline / infinite-grid 更接近“主场景之外的附加结果”；depth-only / shadow-caster 则属于 ScenePassRenderRequest 路径，会在 CameraRenderer 中作为场景重绘 pass 直接执行，而不是 editor overlay 逻辑的一部分。
当前这些 builtin pass 更多是“底层执行单元”。真正决定 Scene View 要不要画网格、要不要叠选中轮廓、这些效果要挂到 postScenePasses 还是 overlayPasses 上的逻辑，已经迁移到 editor 侧的 SceneViewportRenderPlan；真正决定 depth-only / shadow-caster surface 与 clear 策略的，则是 CameraRenderRequest。
典型链路
Scene View / editor 补充 pass
当前 Scene View 相关链路大致是：
- CameraRenderer 先执行主
RenderPipeline。 - 如果 CameraRenderRequest 里请求了
objectId.surface，则额外执行 BuiltinObjectIdPass，把每个可见物体的GameObjectID 编码进辅助纹理。 - editor 侧的 SceneViewportRenderPlan 会根据 overlay、选中对象和 render targets 同时构建
postScenePasses与overlayPasses。 - 其中
postScenePasses里的SceneViewportGridPass/SceneViewportSelectionOutlinePass包装器，最终分别调用 BuiltinInfiniteGridPass 与 BuiltinObjectIdOutlinePass；overlayPasses则保留给 editor overlay 的最终叠加层。
Depth-only / shadow-caster request
对 CameraRenderer 自身持有的 scene pass，当前链路大致是：
- 调用方在 CameraRenderRequest 的
shadowCaster/depthOnly槽位里提供ScenePassRenderRequest。 CameraRenderer在执行主RenderPipeline前，先按顺序驱动 BuiltinShadowCasterPass 与 BuiltinDepthOnlyPass 的默认实例。- 这两类 pass 共用 BuiltinDepthStylePassBase::Execute 的执行框架，因此当前都要求
surface同时提供colorAttachments[0]与depthAttachment，并复用renderArea、clear flags 与状态迁移逻辑。
当前公开概念
| 类型 / 头文件 | 角色 |
|---|---|
| BuiltinObjectIdPass | 生成 object-id 颜色缓冲，给拾取与 outline 作为输入。 |
| BuiltinObjectIdOutlinePass | 读取 object-id 纹理，在主颜色目标上合成选中轮廓或调试 mask。 |
| ObjectIdOutlineStyle | 轮廓颜色、像素宽度、调试模式的配置载体。 |
| BuiltinInfiniteGridPass | Scene View 网格覆盖层的底层执行 pass。 |
| InfiniteGridPassData | 网格 pass 使用的相机姿态与裁剪参数。 |
| InfiniteGridParameters | 由相机状态推导出的网格尺度、过渡和淡出参数。 |
| BuildInfiniteGridParameters | 把 Scene View 相机数据折算成稳定的十进制网格参数。 |
| BuiltinDepthStylePassBase | depth-only / shadow-caster 场景重绘共享的执行骨架。 |
| BuiltinDepthOnlyPass | CameraRenderer 默认的 depth-only scene pass。 |
| BuiltinShadowCasterPass | CameraRenderer 默认的 shadow-caster scene pass。 |
测试与真实调用点
tests/Rendering/unit/test_camera_scene_renderer.cpp验证了CameraRenderer中 object-id pass 与可选 pass sequence 的接入时机。engine/src/Rendering/CameraRenderer.cpp当前把 BuiltinShadowCasterPass 与 BuiltinDepthOnlyPass 作为默认 scene pass 挂进shadowCaster/depthOnlyrequest。tests/Rendering/unit/test_builtin_forward_pipeline.cpp固定了 depth-only / shadow-caster 输入布局和 legacy builtin binding plan 的兼容语义。tests/Editor/test_scene_viewport_overlay_renderer.cpp固定了BuildInfiniteGridParameters(...)的十进制尺度、过渡和淡出语义。tests/Editor/test_viewport_render_flow_utils.cpp验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass，以及 object-id SRV 缺失时的警告路径。
当前实现边界
- 这一层目前是 builtin、轻量、偏 editor/工具链导向的 pass 集合，还不是通用 render graph。
- object-id 相关流程依赖单独的辅助 render target / shader resource view，而不是直接从主颜色结果反推。
- depth-style 家族当前仍要求
RenderSurface提供首个颜色附件和深度附件；它不是“只给一个 depth target 就能跑”的极简路径。 - 具体 pass 的资源状态切换大多由调用方保证，单个 pass 本身往往只做最小提交逻辑。