XCEngine/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md

ObjectIdPass

命名空间: XCEngine::Rendering

类型: interface

头文件: XCEngine/Rendering/ObjectIdPass.h

描述: 定义把 RenderSceneData 渲染到 object-id 目标表面的抽象接口，供 CameraRenderer 注入具体实现。

概览

ObjectIdPass 是 CameraRenderer 主链路里的一个可替换插槽。

它的职责很明确：

• 输入已经提取好的 RenderSceneData
• 输出一张 object-id 颜色目标
• 不参与主管线本身的颜色绘制

当前默认实现是 BuiltinObjectIdPass，但 CameraRenderer 允许调用方替换成别的实现，测试里也正是通过 mock pass 验证执行时序和失败回滚。

接口契约

Render()

调用方会把：

• 当前帧的 RenderContext
• object-id 输出目标 RenderSurface
• 已经提取完成的 RenderSceneData

一起传进来。返回 false 表示本次 object-id 渲染失败，CameraRenderer::Render() 会直接终止本次相机提交。

Shutdown()

默认实现为空，用于给具体 pass 释放缓存的 GPU 资源或内部状态。

CameraRenderer 会在以下时机调用它：

• 替换 object-id pass 时
• CameraRenderer 自身析构时

当前接入位置

在 CameraRenderer 里，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

相关文档

• 当前模块
• CameraRenderer
• ObjectIdRenderRequest
• BuiltinObjectIdPass