# 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
2. 如请求了 `shadowCaster` / `depthOnly`，先执行对应 scene pass
3. 绘制主 `RenderPipeline`
4. 如果 `request.objectId.IsRequested()`，执行 `ObjectIdPass`
5. 再执行 `postScenePasses`
6. 最后执行 `overlayPasses`

## 当前实现边界

- `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)