docs(api): finish volume and volumetric pass coverage

2026-04-09 23:50:33 +08:00
parent b0625a30bd
commit cb3d558aaa
13 changed files with 293 additions and 330 deletions
--- a/docs/api/XCEngine/Components/Components.md
+++ b/docs/api/XCEngine/Components/Components.md
@@ -54,7 +54,6 @@
 - [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) - `MeshRendererComponent.h`，材质槽和渲染附加参数。
 - [VolumeRendererComponent](VolumeRendererComponent/VolumeRendererComponent.md) - `VolumeRendererComponent.h`，体积资源、体积材质与阴影标志绑定。
 - [TransformComponent](TransformComponent/TransformComponent.md) - `TransformComponent.h`，局部/世界变换与层级矩阵。
- [VolumeRendererComponent](VolumeRendererComponent/VolumeRendererComponent.md) - `VolumeRendererComponent.h`，体数据、体材质和阴影标记组件。

 ## 推荐阅读顺序

--- a/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md
+++ b/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md
@@ -6,107 +6,113 @@

 **头文件**: `XCEngine/Components/VolumeRendererComponent.h`

-**源文件**: `engine/src/Components/VolumeRendererComponent.cpp`
-
-**描述**: 体积渲染组件，负责把 `VolumeField`、体积材质和少量阴影标志绑定到 `GameObject` 上，并在序列化/反序列化与 deferred load 场景中保持资源身份恢复。
+**描述**: 体积渲染组件，保存 `VolumeField` 与 `Material` 的运行时句柄、项目资源身份与序列化路径，并暴露阴影相关开关。

 ## 角色概述

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

- 这个对象是否要作为体积参与渲染？
- 它绑定的是哪一个 `VolumeField`？
- 它使用哪一个 `Material`？
- 体积对象当前的阴影开关是什么？
+- 这个 `GameObject` 当前绑定的是哪份体积资源？
+- 这个体积资源应当使用哪份材质参与 `BuiltinVolumetricPass`？
+- 反序列化后是立即同步加载，还是在 deferred scene load 模式下延迟到首次访问时异步兑现？

-和 [MeshRendererComponent](../MeshRendererComponent/MeshRendererComponent.md) 类似，它同时承担“运行时资源句柄”和“可持久化资源身份”两层职责。
+按当前实现，它同时维护两组并行状态：

-## 当前状态模型
+- `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` 已恢复
+- 运行时句柄仍为空
+- 首次读取句柄时才真正发起或收口异步加载
+
+## 公开接口
+
+| 接口 | 作用 |
 |------|------|
-| `m_volumeField` / `m_volumeFieldPath` / `m_volumeFieldRef` | 体积资源句柄、路径缓存与稳定 `AssetRef`。 |
-| `m_material` / `m_materialPath` / `m_materialRef` | 材质句柄、路径缓存与稳定 `AssetRef`。 |
-| `m_pendingVolumeLoad` / `m_pendingMaterialLoad` | deferred async load 的挂起结果。 |
-| `m_asyncVolumeLoadRequested` / `m_asyncMaterialLoadRequested` | 防止重复发起异步加载。 |
-| `m_castShadows` / `m_receiveShadows` | 阴影相关附加开关。 |
+| `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(...)` | 负责场景文本中的体积/材质引用恢复协议 |

-## 绑定与恢复流程
-
-### 1. 运行时按路径设置
-
- `SetVolumeFieldPath(...)` 会立即尝试 `ResourceManager::Load<VolumeField>(path)`。
- `SetMaterialPath(...)` 会立即尝试 `ResourceManager::Load<Material>(path)`。
- 两条路径都会额外调用 `TryGetAssetRef(...)`，尽量把项目路径回填成稳定资源身份。
-
-### 2. 运行时按句柄设置
-
- `SetVolumeField(...)` 与 `SetMaterial(...)` 会从句柄反推出路径。
- 若路径对应项目资产，也会同步尝试回填 `AssetRef`。
-
-### 3. 序列化与反序列化
-
-`Serialize()` 当前优先写：
-
- `volumeRef`
- `materialRef`
-
-只有在没有有效 `AssetRef` 且路径带 virtual scheme 时，才会保留：
-
- `volumePath`
- `materialPath`
-
-`Deserialize()` 当前会先清空旧状态，再恢复：
-
- 体积资源身份
- 材质资源身份
- `castShadows`
- `receiveShadows`
-
-若开启 deferred scene load，则会优先只恢复路径/身份，等首次访问句柄时再启动异步兑现。
-
-## 与 deferred scene load 的关系
-
- `GetVolumeField()` / `GetVolumeFieldHandle()` 会触发：
-  - `EnsureDeferredAsyncVolumeLoadStarted()`
-  - `ResolvePendingVolumeField()`
- `GetMaterial()` / `GetMaterialHandle()` 会触发：
-  - `EnsureDeferredAsyncMaterialLoadStarted()`
-  - `ResolvePendingMaterial()`
-
-因此这几个 getter 不是纯只读访问器，而是带有“补发异步兑现”的副作用。
-
-## 与渲染链路的关系
-
- `RenderSceneUtility` 当前会从对象上提取 `VolumeRendererComponent`，并构造 [VisibleVolumeItem](../../Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md)。
- 后续 [BuiltinVolumetricPass](../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) 会消费这些可见体积项。
- 这意味着“组件存在”不等于“这一帧一定有可绘制体积”：
-  - 体积资源可能尚未兑现
-  - 材质可能为空
-  - deferred load 可能仍在挂起
-
-## 测试与锚点
+## 测试与调用链

 - `tests/Components/test_volume_renderer_component.cpp`
-  - `SetResourcesCachesHandlesPathsAndFlags`
-  - `SerializeAndDeserializePreservesVirtualPathsAndFlags`
-  - `DeferredSceneDeserializeLoadsVolumeFieldAsyncByPath`
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
-  - 覆盖体积对象被提取进渲染场景数据
- `engine/src/Components/ComponentFactoryRegistry.cpp`
-  - 当前把 `"VolumeRenderer"` 注册为内建组件类型
+  - 覆盖句柄/路径缓存
+  - 覆盖虚拟路径序列化
+  - 覆盖 deferred scene load 下按路径异步恢复体积资源
+- `engine/src/Rendering/Extraction/RenderSceneUtility.cpp`
+  - 当前通过本组件读取 `VolumeField` 与 `Material`，组装 `VisibleVolumeItem`
+- `editor/src/ComponentEditors/VolumeRendererComponentEditor.h`
+  - 当前 Inspector 里的 Volume Renderer 面板直接调用本组件的路径与阴影接口

 ## 当前实现边界

- 正式持久化协议优先是 `AssetRef`，不是普通项目路径。
- 只有 virtual scheme 路径才会在没有有效 `AssetRef` 时稳定保留。
- 当前组件只维护一个体积资源和一个材质，不涉及更复杂的多体积槽位模型。
+- 组件只负责 CPU 侧资源引用与场景序列化，不负责 GPU 上传。
+- 当前 `Get*Handle()` / `Get*()` 不是纯读取器，调用方要接受其会触发异步加载状态推进。
+- 没有有效 `AssetRef` 的普通项目路径不会被当成正式持久化协议长期保留。
+- 阴影标志当前在组件侧可读写可序列化，但具体是否在所有渲染路径都生效，要看上游提取与 pass 实现。

 ## 相关文档

- [当前模块](../Components.md)
+- [Components](../Components.md)
 - [VolumeField](../../Resources/Volume/VolumeField/VolumeField.md)
+- [Material](../../Resources/Material/Material/Material.md)
 - [VisibleVolumeItem](../../Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md)
 - [BuiltinVolumetricPass](../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md)
+- [VolumeRendererComponentEditor](../../Editor/ComponentEditors/VolumeRendererComponentEditor/VolumeRendererComponentEditor.md)