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