5.7 KiB
5.7 KiB
BuiltinObjectIdOutlinePass
命名空间: XCEngine::Rendering::Passes
类型: class
头文件: XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h
描述: 内建的全屏后处理 pass，读取 object-id 纹理并把选中对象轮廓或调试 selection mask 合成到当前颜色目标；真正使用哪份 shader 由调用方通过 shaderPath 注入。
概览
BuiltinObjectIdOutlinePass 处在“object-id 已经生成，但主场景也已经画完”的阶段。它本身不负责提取可见物体，也不负责生成 object-id 纹理，而是消费这些上游结果：
- object-id 纹理通常来自
BuiltinObjectIdPass。 - 选中对象列表和 style 当前通常由 editor 侧的 Scene View render plan 提供。
- 调用时机当前由
editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp这类包装 pass 决定，并最终通过 CameraRenderer 的postScenePasses提交。
因此它更接近一个“builtin selection feedback compositor”，而不是一个通用 post-process 框架。
和早期实现不同，当前类已经不再把 outline shader 写死为 engine builtin 资源。源码里的职责边界是：
BuiltinObjectIdOutlinePass只负责资源创建、object-id 采样、常量编码和一次全屏三角形执行。- editor 调用方 通过 SetShaderPath 或构造函数参数注入具体 shader 路径。
SceneViewportSelectionOutlinePass当前用 SceneViewportResourcePaths 生成 editor-owned object-id outline shader 路径，再交给这里执行；SceneViewportShaderPaths只是兼容 include 层。
输入与输出契约
| 输入 / 输出 | 当前要求 |
|---|---|
renderContext |
必须有效，且后端类型必须是 D3D12。 |
surface |
至少要有一个有效的颜色附件；pass 只写 colorAttachments[0]。 |
objectIdTextureView |
不能为空，并且调用方要保证它已经处于可作为 SRV 读取的状态。 |
selectedObjectIds |
不能为空；超过 256 个时只会取前 256 个。 |
style |
决定轮廓颜色、宽度和是否改为输出 debug mask。 |
| 输出 | 在主颜色目标上 alpha 混合轮廓，或在 debug 模式下输出黑白 selection mask。 |
当前渲染算法
按 BuiltinObjectIdOutlinePass.cpp 与当前配置 shader 的实现，流程是：
- 校验上下文、后端、object-id SRV 和选中对象列表。
- 懒初始化内部资源，必要时重新创建 pipeline layout、pipeline state 和两个 descriptor set；这一步要求
shaderPath非空且可成功加载。 - 从
surface.GetWidth()/GetHeight()计算视口尺寸与 texel size。 - 用
EncodeObjectIdToColor()把选中对象 ID 编码进常量缓冲，最多写入kMaxSelectedObjectCount = 256项。 - 绑定一个 CBV set 和一个 SRV set，设置目标为
surface的第一个颜色附件。 - 以全屏三角形方式执行
Draw(3, 1, 0, 0)。
生命周期
- Constructor 只做状态清零，不会立刻创建 GPU 资源。
- SetShaderPath 更新路径时，会立刻销毁当前缓存的 RHI 资源，等待下一次
Render()重新初始化。 - 第一次 Render 成功进入初始化路径时，才会真正创建 descriptor 和 PSO。
- Shutdown 会显式销毁所有内部缓存对象。
- Destructor 当前是默认析构，因此如果把它作为长期 renderer 成员使用，调用方仍需在销毁前显式执行
Shutdown()。
当前实现边界
- 只接受
D3D12，其它后端直接返回false。 - 在第一次创建资源前必须先提供有效
shaderPath；空路径会记录错误并返回false。 - 不处理资源状态切换，也不负责清屏；这些由调用方保证。
- 当前完全忽略
surface.GetRenderArea()，viewport 和 scissor 都直接取整张 surface 的宽高。 - 只使用第一个颜色附件；多 render target 场景不会同步写其它附件。
公开方法
| 方法 | 说明 |
|---|---|
| Constructor | 创建一个 outline pass 对象，并可选地预置 shader 路径。 |
| Destructor | 默认析构；不会自动释放内部 RHI 资源。 |
| SetShaderPath | 更新当前要加载的 shader 路径，并清空已创建资源。 |
| GetShaderPath | 返回当前记录的 shader 路径。 |
| Shutdown | 销毁已创建的 pipeline、descriptor 和 shader handle。 |
| Render | 读取 object-id SRV，并把轮廓或 debug mask 写入颜色目标。 |
真实使用位置
editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp用SceneViewportSelectionOutlinePassRenderer包装它， 并通过GetSceneViewportObjectIdOutlineShaderPath()注入 editor-owned shader 路径。- SceneViewportRenderPlan 决定当前帧是否要创建 selection outline pass。
- CameraRenderer 在主场景与 object-id pass 之后执行这些
postScenePasses。 editor/src/Viewport/ViewportHostRenderFlowUtils.h当前为 Scene View 组装默认橙色、2px的 outline style。