XCEngine/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md

VolumeRendererComponent

命名空间: XCEngine::Components

类型: class

头文件: XCEngine/Components/VolumeRendererComponent.h

描述: 体积渲染组件，保存 VolumeField 与 Material 的运行时句柄、项目资源身份与序列化路径，并暴露阴影相关开关。

角色概述

VolumeRendererComponent 是当前场景里体积对象进入渲染链路的组件侧入口。它回答的是：

• 这个 GameObject 当前绑定的是哪份体积资源？
• 这个体积资源应当使用哪份材质参与 BuiltinVolumetricPass？
• 反序列化后是立即同步加载，还是在 deferred scene load 模式下延迟到首次访问时异步兑现？

按当前实现，它同时维护两组并行状态：

• VolumeField
  • 运行时 ResourceHandle
  • 路径缓存 m_volumeFieldPath
  • 项目资源身份 m_volumeFieldRef
  • deferred async load 挂起状态
• Material
  • 运行时 ResourceHandle
  • 路径缓存 m_materialPath
  • 项目资源身份 m_materialRef
  • deferred async load 挂起状态

当前实现语义

资源绑定

• SetVolumeFieldPath(...) / SetMaterialPath(...)
  • 立即清空挂起异步状态
  • 同步调用 ResourceManager::Load<T>(path)
  • 尝试把路径回填成稳定的 AssetRef
• SetVolumeField(...) / SetMaterial(...)
  • 从句柄反推当前路径
  • 如果路径可解析为项目资源，则同步回填 AssetRef
• ClearVolumeField() / ClearMaterial()
  • 同时清空句柄、路径、AssetRef 与挂起异步状态

序列化与反序列化

当前序列化优先级是：

• 对有有效 AssetRef 的项目资源，优先写 volumeRef= / materialRef=
• 只有在没有有效 AssetRef 且路径带虚拟 scheme 时，才额外写 volumePath= / materialPath=
• 阴影标志始终写为 castShadows= 与 receiveShadows=

Deserialize(...) 的恢复顺序是：

1. 先重置当前绑定与阴影标志。
2. 如果存在有效 AssetRef，优先按 AssetRef 恢复。
3. 在 deferred scene load 模式下，优先只恢复可解析路径，不立刻加载资源。
4. 只有虚拟路径在没有 AssetRef 时会被保留并作为恢复入口。

这意味着：

• 普通项目资源的正式持久化协议是 AssetRef
• test://、builtin:// 这类虚拟路径才长期依赖路径文本本身

deferred async load

GetVolumeField() / GetVolumeFieldHandle() 与 GetMaterial() / GetMaterialHandle() 都带副作用：

• 如果当前只有路径没有已兑现句柄，会先触发 EnsureDeferredAsync*LoadStarted()
• 如果异步结果已经完成，会在读取前调用 ResolvePending*() 收口结果

因此在 deferred scene load 模式下，组件常见的中间状态是：

• 路径与 AssetRef 已恢复
• 运行时句柄仍为空
• 首次读取句柄时才真正发起或收口异步加载

公开接口

接口	作用
GetVolumeField() / GetVolumeFieldHandle()	读取体积资源，并在需要时触发 deferred async load 收口
GetVolumeFieldPath() / GetVolumeFieldAssetRef()	读取体积资源元数据，不直接暴露 GPU/渲染行为
SetVolumeFieldPath(...) / SetVolumeField(...) / ClearVolumeField()	绑定或清空体积资源
GetMaterial() / GetMaterialHandle()	读取材质，并在需要时触发 deferred async load 收口
GetMaterialPath() / GetMaterialAssetRef()	读取材质元数据
SetMaterialPath(...) / SetMaterial(...) / ClearMaterial()	绑定或清空材质
GetCastShadows() / SetCastShadows(...)	控制组件层阴影投射标志
GetReceiveShadows() / SetReceiveShadows(...)	控制组件层阴影接收标志
Serialize(...) / Deserialize(...)	负责场景文本中的体积/材质引用恢复协议

测试与调用链

• tests/Components/test_volume_renderer_component.cpp
  • 覆盖句柄/路径缓存
  • 覆盖虚拟路径序列化
  • 覆盖 deferred scene load 下按路径异步恢复体积资源
• engine/src/Rendering/Extraction/RenderSceneUtility.cpp
  • 当前通过本组件读取 VolumeField 与 Material，组装 VisibleVolumeItem
• editor/src/ComponentEditors/VolumeRendererComponentEditor.h
  • 当前 Inspector 里的 Volume Renderer 面板直接调用本组件的路径与阴影接口

当前实现边界

• 组件只负责 CPU 侧资源引用与场景序列化，不负责 GPU 上传。
• 当前 Get*Handle() / Get*() 不是纯读取器，调用方要接受其会触发异步加载状态推进。
• 没有有效 AssetRef 的普通项目路径不会被当成正式持久化协议长期保留。
• 阴影标志当前在组件侧可读写可序列化，但具体是否在所有渲染路径都生效，要看上游提取与 pass 实现。

相关文档

• Components
• VolumeField
• Material
• VisibleVolumeItem
• BuiltinVolumetricPass
• VolumeRendererComponentEditor