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、材质、surface 格式以及采样参数动态缓存

当前执行流程

1. Initialize / EnsureInitialized(...) 加载 builtin cube mesh 和基础资源
2. PrepareVolumeResources 预热当前帧可见体积需要的 mesh / volume GPU 资源
3. Execute 校验 RenderSurface 是否具备单颜色附件、深度附件和有效 render area
4. 逐个遍历 sceneData.visibleVolumes
5. 为每个体积解析兼容的 volumetric shader pass
6. 构建或复用 pipeline layout、pipeline state 和动态 descriptor set
7. 把体积 bounds、材质常量、光照常量与 volume SRV 绑定后提交 draw

关键内部状态

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

当前实现边界

• 只处理 VisibleVolumeItem
• 当前只为 VolumeStorageKind::NanoVDB 体积准备 GPU 资源并参与绘制
• 当前要求 surface 为“单颜色附件 + 深度附件”模型
• 若 shader pass 未声明 PerObject 或 VolumeField 绑定，会直接失败而不是做 legacy fallback
• 这仍然是 builtin forward 链路中的一个 scene pass，不是独立的体渲染框架或 render graph 子系统

公开方法

方法	说明
BuildInputLayout	返回体积 pass 使用的顶点布局
GetName	返回 pass 名称
Initialize	预热 builtin cube mesh 等基础资源
PrepareVolumeResources	为当前帧可见体积预热 mesh 与 volume GPU 资源
Execute	绘制所有可见体积
Shutdown	销毁缓存的 RHI 资源

真实接入位置

• BuiltinForwardPipeline 在场景存在 visibleVolumes 时，会先调用 PrepareVolumeResources 预热资源，再把当前 pass 放进 scene-pass 执行序列
• RenderSceneExtractor 负责把体积对象提取到 sceneData.visibleVolumes

相关文档

• Passes
• VisibleVolumeItem
• VolumeField
• RenderResourceCache
• VolumeRendererComponent