XCEngine/docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md

VisibleVolumeItem

命名空间: XCEngine::Rendering

类型: struct

头文件: XCEngine/Rendering/FrameData/VisibleVolumeItem.h

描述: scene extraction 之后交给体积渲染阶段消费的一条可见体积记录，已经带上组件、资源、渲染队列、相机距离和世界变换。

字段

字段	说明
gameObject	来源场景对象
volumeRenderer	提供体积资源与阴影标志的组件
volumeField	当前要渲染的体积资源
material	当前体积对象使用的材质
renderQueue	当前体积对象的渲染队列
cameraDistanceSq	到当前相机的距离平方
localToWorld	当前体积对象的世界变换

当前语义

• 同一个 GameObject 至多展开成一条 VisibleVolumeItem，不像网格那样会按 section 细分。
• renderQueue 与 cameraDistanceSq 当前会参与稳定排序：
  • opaque 队列按近到远
  • transparent 队列按远到近
• localToWorld 当前直接来自 TransformComponent::GetLocalToWorldMatrix()，下游体积 pass 会据此构造 model 与 inverseModel 常量。

测试与调用链

• engine/src/Rendering/Extraction/RenderSceneUtility.cpp
  • 当前负责从 VolumeRendererComponent 组装本结构
• engine/src/Rendering/Extraction/RenderSceneExtractor.cpp
  • 当前对 visibleVolumes 执行稳定排序
• engine/src/Rendering/Passes/BuiltinVolumetricPass.cpp
  • 当前直接消费本结构执行逐体积绘制
• tests/Rendering/unit/test_render_scene_extractor.cpp
  • 覆盖可见体积提取、剔除和按 renderQueue 排序

当前实现边界

• 这是 extraction 与 execution 之间的中间结构，不负责资源生命周期。
• 本结构不记录 GPU 资源句柄；GPU 上传由 RenderResourceCache 处理。
• 当前没有额外的体积 section、LOD 或 batching 语义。

相关文档

• FrameData
• RenderSceneData
• VolumeRendererComponent
• BuiltinVolumetricPass
• RenderSceneUtility