XCEngine/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md

# BuiltinVolumetricPass

**命名空间**: `XCEngine::Rendering::Passes`

**类型**: `class`

**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`

**描述**: 内建体积绘制 pass，使用 cube 代理网格、材质 shader pass 和体积资源描述符把可见体积绘制到当前颜色目标。

## 概览

`BuiltinVolumetricPass` 是当前体积渲染链路的核心执行器。
它继承自 `RenderPass`，但和普通 mesh pass 相比有几处明显特点：

- 几何始终来自 builtin cube mesh，而不是体积资源自带网格
- 着色器必须声明 `PerObject` 与 `VolumeField` 资源绑定
- descriptor set 与 pipeline state 会按 shader pass、材质和 volume SRV 动态缓存

## 当前执行流程

1. [Initialize](Initialize.md) / `EnsureInitialized(...)` 加载 builtin cube mesh
2. [Execute](Execute.md) 校验 `RenderSurface` 是否具备单颜色附件和深度附件
3. 逐个遍历 `sceneData.visibleVolumes`
4. 为每个体积解析兼容的 volumetric shader pass
5. 构建或复用 pipeline layout、pipeline state 和动态 descriptor set
6. 把体积 bounds、材质常量、主方向光常量与 volume SRV 绑定后提交 draw

## 关键内部状态

| 状态 | 说明 |
|------|------|
| `m_builtinCubeMesh` | 所有体积绘制共用的 cube proxy mesh |
| `m_resourceCache` | 复用 mesh 与 volume GPU 资源 |
| `m_passResourceLayouts` | 按 shader/pass 缓存资源布局 |
| `m_pipelineStates` | 按 render state、shader、格式与 keyword 签名缓存 pipeline |
| `m_dynamicDescriptorSets` | 按对象、材质、volume field 缓存动态描述符集 |

## 当前实现边界

- 只处理 `VisibleVolumeItem`
- 只接受 `VolumeStorageKind::NanoVDB`
- 当前要求 surface 为“单颜色附件 + 深度附件”模型
- 若 shader pass 未声明 `PerObject` 或 `VolumeField` 绑定，会直接失败而不是做 legacy fallback

## 公开方法

| 方法 | 说明 |
|------|------|
| [BuildInputLayout](BuildInputLayout.md) | 返回体积 pass 使用的顶点布局 |
| [GetName](GetName.md) | 返回 pass 名称 |
| [Initialize](Initialize.md) | 预热 builtin cube mesh 等资源 |
| [Execute](Execute.md) | 绘制所有可见体积 |
| [Shutdown](Shutdown.md) | 销毁缓存的 RHI 资源 |

## 相关文档

- [Passes](../Passes.md)
- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md)
- [VolumeField](../../../Resources/Volume/VolumeField/VolumeField.md)
- [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md)