# Passes

**命名空间**: `XCEngine::Rendering::Passes`

**类型**: `submodule`

**描述**: 承载 builtin object-id、selection outline、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套参数类型。

## 概览

`Rendering::Passes` 不是用来替代 [RenderPipeline](../RenderPipeline/RenderPipeline.md) 的第二套主渲染框架，而是承载几类被 `CameraRenderer`、editor 视口流程和 builtin pipeline 复用的 builtin pass：

- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) 把可见物体编码成 object-id 颜色，写到辅助渲染目标。
- [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 读取 object-id 纹理和选中对象列表，把轮廓或调试 mask 叠加回场景颜色。
- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 给 Scene View 一类编辑器视口叠加无限网格。
- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 执行基于 `sourceColorView` 的全屏颜色缩放后处理。
- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 执行 exposure、tone mapping、output transfer 和 final color scale 的最终输出阶段。
- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) 为深度风格场景重绘 pass 提供共享执行骨架。
- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 是 `CameraRenderer` 默认 `depthOnly` request 的 builtin 实现。
- [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 是 `CameraRenderer` 默认 `shadowCaster` request 的 builtin 实现。

## 典型链路

### Scene View / editor 补充 pass

当前 Scene View 相关链路大致是：

1. [CameraRenderer](../CameraRenderer/CameraRenderer.md) 先执行主 `RenderPipeline`。
2. 如果 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) 里请求了 `objectId.surface`，则额外执行 [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md)。
3. editor 侧的 `SceneViewportRenderPlan` 再构建 `postScenePasses` 和 `overlayPasses`。
4. 其中 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 最终分别调用 [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 和 [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。

### Fullscreen post-process / final-color

`SceneRenderer` 当前会先在 planning 阶段把：

- 相机 `postProcess` 描述栈
- pipeline 默认 final-color 设置
- 相机 final-color override

解析成 `CameraRenderRequest::postProcess` 与 `CameraRenderRequest::finalOutput`。

随后 `CameraRenderer` 在主场景之后依次执行：

1. `postProcess`
2. `finalOutput`
3. `objectId`
4. `postScenePasses`
5. `overlayPasses`

## 当前公开概念

| 类型 / 页面 | 角色 |
|------|------|
| [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) | 生成 object-id 颜色缓冲。 |
| [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) | 在主颜色目标上合成选中轮廓。 |
| [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) | Scene View 网格覆盖层的底层执行 pass。 |
| [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) | 相机 post-process 栈当前的颜色缩放全屏 pass。 |
| [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) | final-color 阶段的最终合成 / 输出变换 pass。 |
| [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) | depth-only / shadow-caster 场景重绘共享的执行骨架。 |
| [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) | `CameraRenderer` 默认的 depth-only scene pass。 |
| [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) | `CameraRenderer` 默认的 shadow-caster scene pass。 |

## 测试与真实调用点

- `tests/Rendering/unit/test_camera_scene_renderer.cpp` 验证了 `CameraRenderer` 里 object-id、post-process、final-output 与可选 pass sequence 的接入时机。
- `engine/src/Rendering/Execution/CameraRenderer.cpp` 当前把 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 作为默认 scene pass 挂进 `shadowCaster` / `depthOnly` request。
- `engine/src/Rendering/Execution/SceneRenderer.cpp` 当前负责把 fullscreen 阶段写进 `CameraRenderRequest`。
- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass。

## 当前实现边界

- 这一层目前是 builtin、轻量、偏 editor/工具链导向的 pass 集合，还不是通用 render graph。
- object-id 相关流程依赖单独的辅助 render target / shader resource view，而不是直接从主颜色结果反推。
- fullscreen pass 依赖调用方准备 `sourceColorView` 和中间表面；单个 pass 本身不管理整条阶段链。

## 相关文档

- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md)
- [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)
- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)
- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md)
- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)
- [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md)
- [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md)
- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
- [Rendering](../Rendering.md)