2026-04-03 15:10:37 +08:00
|
|
|
|
# ObjectIdPass
|
|
|
|
|
|
|
|
|
|
|
|
**命名空间**: `XCEngine::Rendering`
|
|
|
|
|
|
|
|
|
|
|
|
**类型**: `interface`
|
|
|
|
|
|
|
|
|
|
|
|
**头文件**: `XCEngine/Rendering/ObjectIdPass.h`
|
|
|
|
|
|
|
|
|
|
|
|
**描述**: 定义把 `RenderSceneData` 渲染到 object-id 目标表面的抽象接口，供 `CameraRenderer` 注入具体实现。
|
|
|
|
|
|
|
|
|
|
|
|
## 概览
|
|
|
|
|
|
|
|
|
|
|
|
`ObjectIdPass` 是 `CameraRenderer` 主链路里的一个可替换插槽。
|
|
|
|
|
|
|
|
|
|
|
|
它的职责很明确：
|
|
|
|
|
|
|
|
|
|
|
|
- 输入已经提取好的 `RenderSceneData`
|
|
|
|
|
|
- 输出一张 object-id 颜色目标
|
|
|
|
|
|
- 不参与主管线本身的颜色绘制
|
|
|
|
|
|
|
|
|
|
|
|
当前默认实现是 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)，但 `CameraRenderer` 允许调用方替换成别的实现，测试里也正是通过 mock pass 验证执行时序和失败回滚。
|
|
|
|
|
|
|
|
|
|
|
|
## 接口契约
|
|
|
|
|
|
|
|
|
|
|
|
### `Render()`
|
|
|
|
|
|
|
|
|
|
|
|
调用方会把：
|
|
|
|
|
|
|
|
|
|
|
|
- 当前帧的 `RenderContext`
|
|
|
|
|
|
- object-id 输出目标 `RenderSurface`
|
|
|
|
|
|
- 已经提取完成的 `RenderSceneData`
|
|
|
|
|
|
|
|
|
|
|
|
一起传进来。返回 `false` 表示本次 object-id 渲染失败，`CameraRenderer::Render()` 会直接终止本次相机提交。
|
|
|
|
|
|
|
|
|
|
|
|
### `Shutdown()`
|
|
|
|
|
|
|
|
|
|
|
|
默认实现为空，用于给具体 pass 释放缓存的 GPU 资源或内部状态。
|
|
|
|
|
|
|
|
|
|
|
|
`CameraRenderer` 会在以下时机调用它：
|
|
|
|
|
|
|
|
|
|
|
|
- 替换 object-id pass 时
|
|
|
|
|
|
- `CameraRenderer` 自身析构时
|
|
|
|
|
|
|
|
|
|
|
|
## 当前接入位置
|
|
|
|
|
|
|
|
|
|
|
|
在 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 里，object-id pass 的执行顺序是：
|
|
|
|
|
|
|
|
|
|
|
|
1. 执行 pre-scene pass
|
2026-04-04 17:35:23 +08:00
|
|
|
|
2. 如请求了 `shadowCaster` / `depthOnly`，先执行对应 scene pass
|
|
|
|
|
|
3. 绘制主 `RenderPipeline`
|
|
|
|
|
|
4. 如果 `request.objectId.IsRequested()`，执行 `ObjectIdPass`
|
|
|
|
|
|
5. 再执行 `postScenePasses`
|
|
|
|
|
|
6. 最后执行 `overlayPasses`
|
2026-04-03 15:10:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 当前实现边界
|
|
|
|
|
|
|
|
|
|
|
|
- `ObjectIdPass` 只定义单次 object-id 绘制接口，不负责请求是否合法；这部分先由 `CameraRenderRequest` 和 `CameraRenderer` 做基础校验。
|
|
|
|
|
|
- 接口没有显式的 `Initialize()` 阶段，具体实现通常在第一次 `Render()` 时懒初始化，或在构造期准备资源。
|
|
|
|
|
|
- 当前引擎默认只维护一个 object-id pass 实例，由 `CameraRenderer` 持有。
|
|
|
|
|
|
|
|
|
|
|
|
## 真实使用位置
|
|
|
|
|
|
|
|
|
|
|
|
- `engine/src/Rendering/CameraRenderer.cpp`
|
|
|
|
|
|
- `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp`
|
|
|
|
|
|
- `tests/Rendering/unit/test_camera_scene_renderer.cpp`
|
|
|
|
|
|
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
|
|
|
|
|
|
- [当前模块](../Rendering.md)
|
|
|
|
|
|
- [CameraRenderer](../CameraRenderer/CameraRenderer.md)
|
|
|
|
|
|
- [ObjectIdRenderRequest](../CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)
|
|
|
|
|
|
- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)
|
