From 681452c70e7f7a08381bc3e20e374adff42877fe Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 9 Apr 2026 23:40:43 +0800 Subject: [PATCH] docs(plan): add api doc restructure task board --- docs/api/XCEngine/Components/Components.md | 8 +- .../VolumeRendererComponent.md | 112 ++++++++++ .../RenderSceneExtractor.md | 5 +- .../XCEngine/Rendering/FrameData/FrameData.md | 5 +- .../RenderSceneData/RenderSceneData.md | 7 +- .../VisibleVolumeItem/VisibleVolumeItem.md | 43 ++++ .../BuiltinVolumetricPass/BuildInputLayout.md | 30 +++ .../BuiltinVolumetricPass.md | 75 +++++++ .../Passes/BuiltinVolumetricPass/Execute.md | 33 +++ .../Passes/BuiltinVolumetricPass/GetName.md | 25 +++ .../BuiltinVolumetricPass/Initialize.md | 28 +++ .../Passes/BuiltinVolumetricPass/Shutdown.md | 33 +++ .../BuiltinForwardPipeline.md | 21 +- docs/api/XCEngine/Resources/Resources.md | 2 + docs/api/XCEngine/Resources/Volume/Volume.md | 38 ++++ .../Volume/VolumeField/VolumeField.md | 67 ++++++ .../Volume/VolumeFieldLoader/CanLoad.md | 18 ++ .../Volume/VolumeFieldLoader/Constructor.md | 11 + .../Volume/VolumeFieldLoader/Destructor.md | 11 + .../VolumeFieldLoader/GetDefaultSettings.md | 11 + .../VolumeFieldLoader/GetResourceType.md | 11 + .../GetSupportedExtensions.md | 15 ++ .../Volume/VolumeFieldLoader/Load.md | 32 +++ .../VolumeFieldLoader/VolumeFieldLoader.md | 65 ++++++ ...目录结构重构并行任务板_2026-04-09_第二轮.md | 207 ++++++++++++++++++ 25 files changed, 898 insertions(+), 15 deletions(-) create mode 100644 docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md create mode 100644 docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuildInputLayout.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Execute.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/GetName.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Initialize.md create mode 100644 docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Shutdown.md create mode 100644 docs/api/XCEngine/Resources/Volume/Volume.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeField/VolumeField.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/CanLoad.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Constructor.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Destructor.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetDefaultSettings.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetResourceType.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetSupportedExtensions.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Load.md create mode 100644 docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/VolumeFieldLoader.md create mode 100644 docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md diff --git a/docs/api/XCEngine/Components/Components.md b/docs/api/XCEngine/Components/Components.md index 2e6af239..3c5e0dcc 100644 --- a/docs/api/XCEngine/Components/Components.md +++ b/docs/api/XCEngine/Components/Components.md @@ -4,7 +4,7 @@ **类型**: `module` -**描述**: 提供 `GameObject`/`Component` 组合式对象模型，以及相机、灯光、网格渲染、音频等场景组件的 public API。 +**描述**: 提供 `GameObject`/`Component` 组合式对象模型，以及相机、灯光、网格渲染、体积渲染、音频等场景组件的 public API。 ## 概览 @@ -23,7 +23,7 @@ - 生命周期由 `GameObject` 和 `Scene` 驱动，运行时直接 `AddComponent()` 并不会自动补发 `Awake`、`Start` 或 `OnEnable`。 - 序列化职责分层：`GameObject::Serialize()` 只写对象基础字段和 `Transform`，完整场景保存由 `Scene::SerializeToString()` 负责组件和父子关系。 - `ComponentFactoryRegistry` 只负责把序列化文本里的组件类型名还原为内建组件实例，`Transform` 不走这条路径。 -- 渲染组件链路当前是显式拆分的：`MeshFilterComponent` 负责 mesh 的运行时路径缓存、项目 `AssetRef` 与句柄绑定，`MeshRendererComponent` 负责材质槽的运行时路径缓存、项目 `AssetRef`、句柄以及渲染附加状态；对项目资产来说，正式持久化协议都优先是 `AssetRef`，而不是普通项目路径。 +- 渲染组件链路当前是显式拆分的：`MeshFilterComponent` 负责 mesh 的运行时路径缓存、项目 `AssetRef` 与句柄绑定，`MeshRendererComponent` 负责材质槽的运行时路径缓存、项目 `AssetRef`、句柄以及渲染附加状态；`VolumeRendererComponent` 则为体对象持有 `VolumeField`、体材质以及阴影参与标记。对项目资产来说，正式持久化协议都优先是 `AssetRef`，而不是普通项目路径。 ## 适用场景 @@ -52,13 +52,15 @@ - [LightComponent](LightComponent/LightComponent.md) - `LightComponent.h`，基础灯光参数。 - [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) - `MeshFilterComponent.h`，mesh 资源绑定、序列化路径和资产引用恢复。 - [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) - `MeshRendererComponent.h`，材质槽和渲染附加参数。 +- [VolumeRendererComponent](VolumeRendererComponent/VolumeRendererComponent.md) - `VolumeRendererComponent.h`，体积资源、体积材质与阴影标志绑定。 - [TransformComponent](TransformComponent/TransformComponent.md) - `TransformComponent.h`，局部/世界变换与层级矩阵。 +- [VolumeRendererComponent](VolumeRendererComponent/VolumeRendererComponent.md) - `VolumeRendererComponent.h`，体数据、体材质和阴影标记组件。 ## 推荐阅读顺序 1. 先读 [GameObject-Component Lifecycle And Serialization](../../_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md)，建立整体心智模型。 2. 再读 [GameObject](GameObject/GameObject.md) 和 [TransformComponent](TransformComponent/TransformComponent.md)，理解对象树和变换树的关系。 -3. 如果关注渲染资源绑定，再读 [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) 和 [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md)，理解几何、材质和渲染提取之间的分工。 +3. 如果关注渲染资源绑定，再读 [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md)、[MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) 和 [VolumeRendererComponent](VolumeRendererComponent/VolumeRendererComponent.md)，理解几何对象、体对象、材质和渲染提取之间的分工。 4. 最后按功能阅读其余组件页，例如 [CameraComponent](CameraComponent/CameraComponent.md)、[AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md)。 ## 相关文档 diff --git a/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md b/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md new file mode 100644 index 00000000..d8ae4581 --- /dev/null +++ b/docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md @@ -0,0 +1,112 @@ +# VolumeRendererComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/VolumeRendererComponent.h` + +**源文件**: `engine/src/Components/VolumeRendererComponent.cpp` + +**描述**: 体积渲染组件，负责把 `VolumeField`、体积材质和少量阴影标志绑定到 `GameObject` 上，并在序列化/反序列化与 deferred load 场景中保持资源身份恢复。 + +## 角色概述 + +`VolumeRendererComponent` 回答的问题是： + +- 这个对象是否要作为体积参与渲染？ +- 它绑定的是哪一个 `VolumeField`？ +- 它使用哪一个 `Material`？ +- 体积对象当前的阴影开关是什么？ + +和 [MeshRendererComponent](../MeshRendererComponent/MeshRendererComponent.md) 类似，它同时承担“运行时资源句柄”和“可持久化资源身份”两层职责。 + +## 当前状态模型 + +当前实现维护两组几乎对称的资源状态： + +| 状态 | 作用 | +|------|------| +| `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` | 阴影相关附加开关。 | + +## 绑定与恢复流程 + +### 1. 运行时按路径设置 + +- `SetVolumeFieldPath(...)` 会立即尝试 `ResourceManager::Load(path)`。 +- `SetMaterialPath(...)` 会立即尝试 `ResourceManager::Load(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"` 注册为内建组件类型 + +## 当前实现边界 + +- 正式持久化协议优先是 `AssetRef`，不是普通项目路径。 +- 只有 virtual scheme 路径才会在没有有效 `AssetRef` 时稳定保留。 +- 当前组件只维护一个体积资源和一个材质，不涉及更复杂的多体积槽位模型。 + +## 相关文档 + +- [当前模块](../Components.md) +- [VolumeField](../../Resources/Volume/VolumeField/VolumeField.md) +- [VisibleVolumeItem](../../Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md) +- [BuiltinVolumetricPass](../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) diff --git a/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md b/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md index 1670047b..8d668453 100644 --- a/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md +++ b/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md @@ -6,7 +6,7 @@ **头文件**: `XCEngine/Rendering/Extraction/RenderSceneExtractor.h` -**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、环境与光照提取，以及 `visibleItems` 收集。 +**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、环境与光照提取，以及网格 `visibleItems` 和体对象 `visibleVolumes` 收集。 ## 概览 @@ -25,11 +25,13 @@ - [RenderEnvironmentData](../../FrameData/RenderEnvironmentData/RenderEnvironmentData.md) - `RenderLightingData` - `visibleItems` +- `visibleVolumes` ## 当前实现边界 - 当前仍没有 frustum culling、occlusion culling 或 batching。 - 当前光照提取仍以主方向光和 additional lights 快照为主。 +- 体对象提取已经进入正式 `RenderSceneData` 主链，但更复杂的 volume-specific culling 或排序策略当前还没有单独拆层。 ## 相关文档 @@ -37,4 +39,3 @@ - [RenderSceneUtility](../RenderSceneUtility/RenderSceneUtility.md) - [RenderSceneData](../../FrameData/RenderSceneData/RenderSceneData.md) - [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) - diff --git a/docs/api/XCEngine/Rendering/FrameData/FrameData.md b/docs/api/XCEngine/Rendering/FrameData/FrameData.md index 9a499788..f9fd6f66 100644 --- a/docs/api/XCEngine/Rendering/FrameData/FrameData.md +++ b/docs/api/XCEngine/Rendering/FrameData/FrameData.md @@ -18,6 +18,8 @@ - [RenderEnvironmentData](RenderEnvironmentData/RenderEnvironmentData.md) - [RenderSceneData](RenderSceneData/RenderSceneData.md) - [VisibleRenderItem](VisibleRenderItem/VisibleRenderItem.md) +- [VisibleVolumeItem](VisibleVolumeItem/VisibleVolumeItem.md) +- [VisibleVolumeItem](VisibleVolumeItem/VisibleVolumeItem.md) ## 当前职责 @@ -25,6 +27,8 @@ - 承载环境与 skybox 语义 - 承载主方向光、阴影和 additional lights 快照 - 承载 scene extraction 之后的 `visibleItems` +- 承载 scene extraction 之后的 `visibleVolumes` +- 承载 scene extraction 之后的 `visibleVolumes` ## 相关文档 @@ -32,4 +36,3 @@ - [Planning](../Planning/Planning.md) - [Extraction](../Extraction/Extraction.md) - [Execution](../Execution/Execution.md) - diff --git a/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md b/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md index 21e02cc4..1a41feb5 100644 --- a/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md +++ b/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md @@ -6,7 +6,7 @@ **头文件**: `XCEngine/Rendering/FrameData/RenderSceneData.h` -**描述**: scene extraction 之后的核心帧数据块，汇总相机、环境、光照、全局 shader keywords 与 `visibleItems`。 +**描述**: scene extraction 之后的核心帧数据块，汇总相机、环境、光照、全局 shader keywords、网格 `visibleItems` 与体对象 `visibleVolumes`。 ## 头文件中的主要类型 @@ -43,6 +43,7 @@ - `lighting` - `globalShaderKeywords` - `visibleItems` +- `visibleVolumes` `HasCamera()` 当前只检查 `camera != nullptr`。 @@ -50,7 +51,7 @@ - [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) 生成 `RenderSceneData` - [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 消费它 -- builtin pipeline 和各类 pass 从它的 `visibleItems` / lighting / cameraData 继续取数 +- builtin pipeline 和各类 pass 从它的 `visibleItems`、`visibleVolumes`、lighting 与 cameraData 继续取数 ## 相关文档 @@ -58,5 +59,5 @@ - [RenderCameraData](../RenderCameraData/RenderCameraData.md) - [RenderEnvironmentData](../RenderEnvironmentData/RenderEnvironmentData.md) - [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md) +- [VisibleVolumeItem](../VisibleVolumeItem/VisibleVolumeItem.md) - [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) - diff --git a/docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md b/docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md new file mode 100644 index 00000000..c61942b7 --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md @@ -0,0 +1,43 @@ +# VisibleVolumeItem + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct` + +**头文件**: `XCEngine/Rendering/FrameData/VisibleVolumeItem.h` + +**描述**: scene extraction 之后交给体积渲染阶段消费的一条可见体积记录，已经带上体积组件、体积资源、材质、渲染队列、相机距离和世界变换。 + +## 字段 + +| 字段 | 说明 | +|------|------| +| `gameObject` | 来源场景对象。 | +| `volumeRenderer` | 提供体积资源与阴影标志的组件。 | +| `volumeField` | 当前解析出的体积资源。 | +| `material` | 当前解析出的材质指针，可为空。 | +| `renderQueue` | 当前体积项的渲染队列。 | +| `cameraDistanceSq` | 到当前相机的距离平方。 | +| `localToWorld` | 当前体积项的世界变换。 | + +## 当前语义 + +- 只有对象上存在有效 [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md) 且体积资源可解析时，scene extraction 才会生成这条记录。 +- opaque / transparent 的排序规则同样会消费 `renderQueue` 与 `cameraDistanceSq`。 +- 这条记录与 [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md) 平行存在，前者服务体积链路，后者服务 mesh 链路。 + +## 当前调用链 + +- `engine/src/Rendering/Extraction/RenderSceneUtility.cpp` + - 负责构造 `VisibleVolumeItem` +- `engine/src/Rendering/Extraction/RenderSceneExtractor.cpp` + - 负责提取与排序 `sceneData.visibleVolumes` +- [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) + - 当前消费 `visibleVolumes` + +## 相关文档 + +- [FrameData](../FrameData.md) +- [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md) +- [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md) +- [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuildInputLayout.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuildInputLayout.md new file mode 100644 index 00000000..7c5a2e25 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuildInputLayout.md @@ -0,0 +1,30 @@ +# BuiltinVolumetricPass::BuildInputLayout + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `method` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +## 签名 + +```cpp +static RHI::InputLayoutDesc BuildInputLayout(); +``` + +## 作用 + +返回 `BuiltinVolumetricPass` 当前使用的顶点布局描述。 + +## 当前行为 + +- 当前布局直接基于 `Resources::StaticMeshVertex`。 +- 依次声明： + - `POSITION` + - `NORMAL` + - `TEXCOORD0` +- 说明体积 pass 当前复用静态网格顶点结构，而不是定义单独的体积代理顶点格式。 + +## 相关文档 + +- [BuiltinVolumetricPass](BuiltinVolumetricPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md new file mode 100644 index 00000000..4eec474e --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md @@ -0,0 +1,75 @@ +# BuiltinVolumetricPass + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +**描述**: builtin 体积渲染 pass，消费 `RenderSceneData::visibleVolumes`，为每个可见体积解析 shader pass、管线状态、descriptor set 与 `VolumeField` GPU 资源后执行绘制。 + +## 概览 + +`BuiltinVolumetricPass` 当前是体积渲染进入 builtin forward 链路的实际执行者。它不是独立的体积框架，而是围绕现有 scene-pass 体系补出的一条专用路径： + +- 输入来自 `RenderSceneData::visibleVolumes` +- 几何代理当前固定使用 builtin cube mesh +- 资源绑定依赖 shader pass 的 builtin resource layout 解析 +- 当前只接受 `VolumeStorageKind::NanoVDB` + +## 当前执行流程 + +1. `Initialize(...)` / `EnsureInitialized(...)` 保证 device、backend 与 builtin cube mesh 就绪。 +2. `Execute(...)` 校验 `RenderContext`、颜色附件、深度附件和 render area。 +3. 遍历 `sceneData.visibleVolumes`。 +4. 每项调用 `DrawVisibleVolume(...)`： + - 通过 `ResolveVolumeShaderPass(...)` 选择兼容的 volumetric shader pass + - 通过 `GetOrCreatePassResourceLayout(...)` 创建或复用 pipeline layout + - 通过 `GetOrCreatePipelineState(...)` 创建或复用 graphics pipeline + - 通过 `RenderResourceCache` 获取 cube mesh 与 `VolumeField` 的 GPU 视图 + - 组装 `PerObjectConstants` 与 `LightingConstants` + - 写 descriptor set 并提交 draw call + +## 关键资源约束 + +- 需要单一颜色附件和有效深度附件。 +- `BuiltinPassResourceBindingPlan` 里必须至少存在： + - `PerObject` + - `VolumeField` +- 若 shader pass 还声明了 `Material`，则材质必须能提供有效的 schema constant payload。 +- 体积资源当前必须是 `NanoVDB`，否则该条目会被跳过。 + +## 当前缓存层 + +类内部当前维护三类缓存： + +- `m_passResourceLayouts` + - 以 `shader + passName` 为键缓存 pipeline layout 与 binding metadata +- `m_pipelineStates` + - 以 render state、shader、keyword signature、render target format 等为键缓存 pipeline state +- `m_dynamicDescriptorSets` + - 以 pass-layout、set、objectId、material、volumeField 为键缓存动态 descriptor set + +## 当前实现边界 + +- pass 本身不负责 scene extraction，也不负责决定 `visibleVolumes` 的排序策略。 +- 当前代理几何固定为 builtin cube，而不是从体数据本身生成裁剪几何。 +- 当前 lighting constants 只消费主方向光。 +- 资源清理通过 `Shutdown()` / 析构集中处理。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [BuildInputLayout](BuildInputLayout.md) | 构建当前体积 pass 使用的顶点布局。 | +| [GetName](GetName.md) | 返回 pass 名称。 | +| [Initialize](Initialize.md) | 预热 device/backend 相关资源。 | +| [Execute](Execute.md) | 遍历 `visibleVolumes` 并提交绘制。 | +| [Shutdown](Shutdown.md) | 销毁缓存的管线、descriptor 与资源状态。 | + +## 相关文档 + +- [Passes](../Passes.md) +- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md) +- [VolumeField](../../../Resources/Volume/VolumeField/VolumeField.md) +- [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Execute.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Execute.md new file mode 100644 index 00000000..b85eaa44 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Execute.md @@ -0,0 +1,33 @@ +# BuiltinVolumetricPass::Execute + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `method` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +## 签名 + +```cpp +bool Execute(const RenderPassContext& context) override; +``` + +## 作用 + +遍历 `visibleVolumes`，为每个可见体积提交一次 volumetric draw。 + +## 当前行为 + +- `renderContext` 无效时返回 `false`。 +- `visibleVolumes` 为空时直接返回 `true`，表示“没有工作但不算失败”。 +- 要求： + - 单一颜色附件 + - 非空深度附件 + - 正常的 `renderArea` +- 会设置 render target、viewport、scissor 和三角形拓扑。 +- 最终逐项调用内部 `DrawVisibleVolume(...)`。 + +## 相关文档 + +- [BuiltinVolumetricPass](BuiltinVolumetricPass.md) +- [VisibleVolumeItem](../../FrameData/VisibleVolumeItem/VisibleVolumeItem.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/GetName.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/GetName.md new file mode 100644 index 00000000..40ee292e --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/GetName.md @@ -0,0 +1,25 @@ +# BuiltinVolumetricPass::GetName + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `method` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +## 签名 + +```cpp +const char* GetName() const override; +``` + +## 作用 + +返回当前 pass 的稳定名称。 + +## 当前行为 + +- 固定返回 `"BuiltinVolumetricPass"`。 + +## 相关文档 + +- [BuiltinVolumetricPass](BuiltinVolumetricPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Initialize.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Initialize.md new file mode 100644 index 00000000..23372b7d --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Initialize.md @@ -0,0 +1,28 @@ +# BuiltinVolumetricPass::Initialize + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `method` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +## 签名 + +```cpp +bool Initialize(const RenderContext& context) override; +``` + +## 作用 + +预热当前 device/backend 相关资源。 + +## 当前行为 + +- 直接转发到内部 `EnsureInitialized(context)`。 +- 若 device/backend 变化，旧缓存会先被 `DestroyResources()` 清掉，再重新创建。 +- 当前初始化阶段最关键的资源是 builtin cube mesh。 + +## 相关文档 + +- [BuiltinVolumetricPass](BuiltinVolumetricPass.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Shutdown.md b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Shutdown.md new file mode 100644 index 00000000..ee6334f3 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass/Shutdown.md @@ -0,0 +1,33 @@ +# BuiltinVolumetricPass::Shutdown + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `method` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h` + +## 签名 + +```cpp +void Shutdown() override; +``` + +## 作用 + +销毁 `BuiltinVolumetricPass` 当前持有的缓存资源。 + +## 当前行为 + +- 转发到 `DestroyResources()`。 +- 会清理： + - `RenderResourceCache` + - 所有 pipeline state + - 所有动态 descriptor set + - 所有 pass resource layout + - builtin cube mesh 句柄 +- 最后把 device/backend 状态恢复到初始值。 + +## 相关文档 + +- [BuiltinVolumetricPass](BuiltinVolumetricPass.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md index 2fce04cb..3bfc06d2 100644 --- a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md @@ -6,7 +6,7 @@ **头文件**: `XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` -**描述**: 当前内建的前向主渲染管线实现。它会按 shader pass 的资源声明动态构建 `PassResourceLayout`、descriptor set 与 `RHIPipelineState`，并通过 `RenderPassSequence` 执行默认的 opaque pass。 +**描述**: 当前内建的前向主渲染管线实现。它会按 shader pass 的资源声明动态构建 `PassResourceLayout`、descriptor set 与 `RHIPipelineState`，并通过 `RenderPassSequence` 顺序执行 opaque、skybox、volumetric 和 transparent 阶段。 ## 概览 @@ -16,7 +16,14 @@ - `m_pipelineStates`：以 `(shader*, passName, material render state)` 为 key，缓存真正的图形 pipeline state。 - `m_dynamicDescriptorSets`：以 `(passLayout, setIndex, objectId, material)` 为 key，缓存逐物体或逐材质的 descriptor set。 -构造函数只向 `m_passSequence` 注册一个 `BuiltinForwardOpaquePass`。因此当前仍是一条单 pass 的前向路径，但生命周期已经统一收口到 [RenderPassSequence](../../RenderPass/RenderPass.md)。 +当前构造函数会向 `m_passSequence` 依次注册： + +- `BuiltinForwardOpaquePass` +- `BuiltinForwardSkyboxPass` +- [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) +- `BuiltinForwardTransparentPass` + +因此它已经不再是“单 opaque pass”的过渡版前向路径，而是一条正式的多阶段 builtin forward sequence。 ## 当前资源契约 @@ -52,9 +59,10 @@ binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况： 1. [Initialize](Initialize.md) 通过 `m_passSequence.Initialize(context)` 进入 pass 生命周期。 2. [Render](Render.md) 把 `RenderContext`、`RenderSurface` 和 `RenderSceneData` 打包成 `RenderPassContext`，再交给 `m_passSequence.Execute(...)`。 -3. `BuiltinForwardOpaquePass` 内部调用 `ExecuteForwardOpaquePass()`，处理 render target 绑定、viewport/scissor、颜色与深度清理，以及前后自动状态切换。 -4. 渲染阶段遍历 `RenderSceneData::visibleItems`，筛出 `BuiltinMaterialPass::ForwardLit` 物体。 -5. 每个物体都会按当前材质解析 shader/pass，获取或创建 pass layout、pipeline state、动态或静态 descriptor set，然后写入常量并发出 draw call。 +3. `BuiltinForwardOpaquePass` 处理主场景 opaque 物体。 +4. `BuiltinForwardSkyboxPass` 在环境允许时绘制天空盒。 +5. [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) 遍历 `RenderSceneData::visibleVolumes`，绘制当前已接入的体对象。 +6. `BuiltinForwardTransparentPass` 再处理透明阶段。 ## 当前实现细节 @@ -64,10 +72,11 @@ binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况： - 逐材质常量优先来自 `ResolveSchemaMaterialConstantPayload(material)` 暴露的 schema-driven payload； 如果 view 无效，才回退到内部 `FallbackPerMaterialConstants { baseColorFactor, alphaCutoffParams }`。 - 采样器和 1x1 白色 fallback 纹理在初始化后长期复用；具体 `Texture` 和 `Mesh` 的 GPU 资源则由 [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) 按需上传。 +- 体对象阶段当前已经正式接入 [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md)，因此 `RenderSceneData` 不再只有 `visibleItems` 一条几何主链。 ## 当前限制 -- 目前只注册了 `BuiltinForwardOpaquePass`，没有透明排序、阴影、延迟渲染或后处理主路径。 +- 当前虽然已经有 opaque / skybox / volumetric / transparent 四段 sequence，但仍不是延迟渲染、RenderGraph 或更通用的多管线框架。 - 资源语义是白名单模型，超出 `PerObject / Material / BaseColorTexture / LinearClampSampler` 的声明不会被接受。 - `Render()` 层面不会因为单个物体 `DrawVisibleItem()` 失败而整体返回 `false`；当前调用点仍然以“尽量继续绘制其余物体”为主。 diff --git a/docs/api/XCEngine/Resources/Resources.md b/docs/api/XCEngine/Resources/Resources.md index 9526cf18..190e91d5 100644 --- a/docs/api/XCEngine/Resources/Resources.md +++ b/docs/api/XCEngine/Resources/Resources.md @@ -24,6 +24,8 @@ - [Mesh](Mesh/Mesh.md) - [Shader](Shader/Shader.md) - [Texture](Texture/Texture.md) +- [Volume](Volume/Volume.md) +- [Volume](Volume/Volume.md) ## 头文件 diff --git a/docs/api/XCEngine/Resources/Volume/Volume.md b/docs/api/XCEngine/Resources/Volume/Volume.md new file mode 100644 index 00000000..efc3f58f --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/Volume.md @@ -0,0 +1,38 @@ +# Volume + +**命名空间**: `XCEngine::Resources` + +**类型**: `submodule` + +**描述**: 体积资源子模块，承载 `VolumeField` 运行时资源对象与 `VolumeFieldLoader` 的 `.nvdb` / `.xcvol` 加载链路。 + +## 概览 + +该目录与 `XCEngine/Resources/Volume` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 + +当前 `Resources/Volume` 这条链路主要覆盖两件事： + +- [VolumeField](VolumeField/VolumeField.md) + - 运行时体积资源对象，保存 payload、边界、体素尺寸和 grid 元数据。 +- [VolumeFieldLoader](VolumeFieldLoader/VolumeFieldLoader.md) + - 负责 source `.nvdb` 与 artifact `.xcvol` 的加载。 + +## 当前主链路 + +1. 项目里的 `.nvdb` 体积文件通过 `VolumeFieldLoader` 读取。 +2. `AssetDatabase` 会把可复用的导入结果写成 `.xcvol` artifact。 +3. 运行时或编辑器通过 `ResourceManager` 加载 `VolumeField`。 +4. 渲染侧再通过 `RenderResourceCache` 把 `VolumeField` payload 上传成 GPU 可读结构化缓冲。 + +## 头文件 + +- [VolumeField](VolumeField/VolumeField.md) - `VolumeField.h` +- [VolumeFieldLoader](VolumeFieldLoader/VolumeFieldLoader.md) - `VolumeFieldLoader.h` + +## 相关文档 + +- [AssetDatabase](../../Core/Asset/AssetDatabase/AssetDatabase.md) +- [ArtifactFormats](../../Core/Asset/ArtifactFormats/ArtifactFormats.md) +- [RenderResourceCache](../../Rendering/RenderResourceCache/RenderResourceCache.md) +- [上级目录](../Resources.md) +- [API 总索引](../../../main.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeField/VolumeField.md b/docs/api/XCEngine/Resources/Volume/VolumeField/VolumeField.md new file mode 100644 index 00000000..977d3c29 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeField/VolumeField.md @@ -0,0 +1,67 @@ +# VolumeField + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum + struct + class` + +**头文件**: `XCEngine/Resources/Volume/VolumeField.h` + +**源文件**: `engine/src/Resources/Volume/VolumeField.cpp` + +**描述**: 体积资源对象，保存体积 payload、包围盒、体素尺寸、index bounds 与 grid 元数据，供资源系统、资产导入链路和体积渲染 pass 共同消费。 + +## 声明概览 + +| 声明 | 类型 | 说明 | +|------|------|------| +| `VolumeStorageKind` | `enum class` | 当前体积 payload 的存储格式，现阶段主要是 `NanoVDB`。 | +| `VolumeIndexBounds` | `struct` | 体素索引空间的最小/最大坐标范围，并提供 `==` / `!=`。 | +| `VolumeField` | `class` | 运行时体积资源对象。 | + +## 当前资源模型 + +`VolumeField` 继承 `IResource`，因此同时具备两层信息： + +- 资源身份 + - `name` + - `path` + - `guid` + - `memorySize` +- 体积内容 + - `storageKind` + - `bounds` + - `voxelSize` + - `indexBounds` + - `gridType` + - `gridClass` + - 原始 payload + +这意味着它不是“只给渲染器看的裸 payload 缓冲”，而是资源系统可缓存、可导入、可按 `AssetRef` 恢复的正式资源对象。 + +## 创建与读取语义 + +- `Create(...)` 要求 `payload != nullptr` 且 `payloadSize > 0`，否则直接失败。 +- 创建成功后会拷贝整份 payload，而不是只保存外部指针。 +- `GetWorldBounds()` 当前直接返回 `m_bounds`，尚未引入独立的局部/世界体积边界变换语义。 +- `GetPayloadData()` / `GetPayloadSize()` 暴露的是当前缓存 payload，用于后续 GPU 上传。 + +## 当前实现边界 + +- 当前正式声明的存储格式只有 `Unknown` 与 `NanoVDB`。 +- `VolumeField` 自身不负责解析 `.nvdb` 文件格式；格式解析由 [VolumeFieldLoader](../VolumeFieldLoader/VolumeFieldLoader.md) 完成。 +- 运行时 `memorySize` 由 `UpdateMemorySize()` 基于对象本体、资源身份字符串和 payload 大小估算。 + +## 测试与调用链 + +- `tests/Resources/Volume/test_volume_field.cpp` + - 覆盖 `Create(...)` 对 payload、bounds、voxelSize、indexBounds、gridType、gridClass 的保留行为。 +- `engine/src/Rendering/Caches/RenderResourceCache.cpp` + - 当前会读取 payload 并把它上传成 GPU 结构化缓冲。 +- [BuiltinVolumetricPass](../../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) + - 通过 `RenderResourceCache` 消费 `VolumeField`。 + +## 相关文档 + +- [Volume](../Volume.md) +- [VolumeFieldLoader](../VolumeFieldLoader/VolumeFieldLoader.md) +- [RenderResourceCache](../../../Rendering/RenderResourceCache/RenderResourceCache.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/CanLoad.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/CanLoad.md new file mode 100644 index 00000000..dca49c5d --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/CanLoad.md @@ -0,0 +1,18 @@ +# VolumeFieldLoader::CanLoad + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +按路径扩展名判断当前 loader 是否可处理该资源。 + +## 当前规则 + +- 先提取扩展名并转小写 +- 仅接受 `nvdb` 与 `xcvol` +- 不在这里区分“构建是否启用 NanoVDB”，因此 `nvdb` 的真正可加载性仍要到 `Load(...)` 阶段确认 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Constructor.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Constructor.md new file mode 100644 index 00000000..03612af9 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Constructor.md @@ -0,0 +1,11 @@ +# VolumeFieldLoader::VolumeFieldLoader + +```cpp +VolumeFieldLoader(); +``` + +构造体积资源加载器。当前构造函数不携带额外状态，主要用于满足资源加载器注册与实例化流程。 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Destructor.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Destructor.md new file mode 100644 index 00000000..34940c62 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Destructor.md @@ -0,0 +1,11 @@ +# VolumeFieldLoader::~VolumeFieldLoader + +```cpp +~VolumeFieldLoader() override; +``` + +析构体积资源加载器。当前头文件未暴露需要手工释放的额外成员状态。 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetDefaultSettings.md new file mode 100644 index 00000000..eca0ceb3 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetDefaultSettings.md @@ -0,0 +1,11 @@ +# VolumeFieldLoader::GetDefaultSettings + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +当前固定返回 `nullptr`，说明体积资源加载器还没有公开的独立导入设置对象。 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetResourceType.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetResourceType.md new file mode 100644 index 00000000..e9b99da4 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetResourceType.md @@ -0,0 +1,11 @@ +# VolumeFieldLoader::GetResourceType + +```cpp +ResourceType GetResourceType() const override; +``` + +返回 `ResourceType::VolumeField`，用于把当前 loader 注册到体积资源类型。 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetSupportedExtensions.md new file mode 100644 index 00000000..88c37eb3 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/GetSupportedExtensions.md @@ -0,0 +1,15 @@ +# VolumeFieldLoader::GetSupportedExtensions + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +返回当前支持的体积扩展名列表： + +- `nvdb` +- `xcvol` + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) +- [CanLoad](CanLoad.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Load.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Load.md new file mode 100644 index 00000000..8e93c42a --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/Load.md @@ -0,0 +1,32 @@ +# VolumeFieldLoader::Load + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +读取体积文件并返回 `VolumeField` 资源或错误信息。 + +## 当前实现流程 + +1. 忽略 `settings` +2. 若 `CanLoad(...)` 返回 `false`，直接返回 unsupported-format 错误 +3. `xcvol` + - 解析 artifact header + - 校验 magic、schema version 与 payload size + - 读取 payload 和边界元数据 +4. `nvdb` + - 启用 `XCENGINE_HAS_NANOVDB` 时读取 NanoVDB grid + - 提取 world bounds、voxel size、index bbox、grid type/class +5. 最终统一创建 `VolumeField` + +## 关键语义 + +- `.xcvol` 是引擎规范化后的体积 artifact；加载时会做严格头校验。 +- `.nvdb` 是源文件输入；如果当前构建未启用 NanoVDB，会返回“当前构建不支持”错误，而不是静默失败。 +- 返回值始终通过 `LoadResult` 表示，成功时内部资源类型为 `VolumeField`。 + +## 相关文档 + +- [VolumeFieldLoader](VolumeFieldLoader.md) +- [CanLoad](CanLoad.md) +- [VolumeField](../VolumeField/VolumeField.md) diff --git a/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/VolumeFieldLoader.md b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/VolumeFieldLoader.md new file mode 100644 index 00000000..a65ab333 --- /dev/null +++ b/docs/api/XCEngine/Resources/Volume/VolumeFieldLoader/VolumeFieldLoader.md @@ -0,0 +1,65 @@ +# VolumeFieldLoader + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**头文件**: `XCEngine/Resources/Volume/VolumeFieldLoader.h` + +**源文件**: `engine/src/Resources/Volume/VolumeFieldLoader.cpp` + +**描述**: `VolumeField` 资源加载器，负责识别 source `.nvdb` 与 artifact `.xcvol` 路径，并把它们统一转换成 `VolumeField` 资源对象。 + +## 概览 + +`VolumeFieldLoader` 当前承载两条正式加载路径： + +1. `.xcvol` + - 读取引擎自己的体积 artifact 格式。 +2. `.nvdb` + - 在启用 `XCENGINE_HAS_NANOVDB` 时直接读取 NanoVDB source 文件。 + +因此它既是运行时加载器，也是 `AssetDatabase` 体积导入链路的核心入口。 + +## 当前加载模型 + +- `GetSupportedExtensions()` 当前返回 `nvdb` 和 `xcvol`。 +- `CanLoad(...)` 只按扩展名判定，不预先验证文件存在。 +- 相对路径会先尝试当前路径；若不存在，再回退到 `ResourceManager::Get().GetResourceRoot()`。 +- `.xcvol` 路径会读取 `VolumeFieldArtifactHeader`，要求： + - `magic == "XCVOL02"` + - schema 版本匹配 + - `payloadSize > 0` +- `.nvdb` 路径在支持 NanoVDB 时会读取 grid metadata，并回填： + - `bounds` + - `voxelSize` + - `indexBounds` + - `gridType` + - `gridClass` + +## 当前实现边界 + +- 未启用 `XCENGINE_HAS_NANOVDB` 时，source `.nvdb` 会返回 `NanoVDB source-file support is unavailable in this build`。 +- `GetDefaultSettings()` 当前固定返回 `nullptr`，说明这条导入链路暂时没有独立的 volume import settings 对象。 +- 当前 loader 通过 `REGISTER_RESOURCE_LOADER(VolumeFieldLoader)` 注册到资源系统。 + +## 测试与真实调用点 + +- `tests/Resources/Volume/test_volume_field_loader.cpp` + - 覆盖 `GetResourceType` + - 覆盖 `CanLoad` + - 覆盖无效路径加载 + - 覆盖直接读取 NanoVDB source payload + - 覆盖 `AssetDatabase` 生成与复用 `.xcvol` artifact + - 覆盖按 `AssetRef` 回读项目体积资源 +- `engine/src/Core/Asset/AssetDatabase.cpp` + - 当前通过 `VolumeFieldLoader` 导入项目体积资源并写出 `.xcvol` +- `engine/src/Core/Asset/ResourceManager.cpp` + - 当前会注册这条 loader + +## 相关文档 + +- [Volume](../Volume.md) +- [VolumeField](../VolumeField/VolumeField.md) +- [AssetDatabase](../../../Core/Asset/AssetDatabase/AssetDatabase.md) +- [ResourceManager](../../../Core/Asset/ResourceManager/ResourceManager.md) diff --git a/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md b/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md new file mode 100644 index 00000000..bb504cce --- /dev/null +++ b/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md @@ -0,0 +1,207 @@ +# API 文档目录结构重构并行任务板（第二轮，2026-04-09） + +## 背景 + +本轮不是普通补页，而是一次“目录归位 + 失效页清理 + 新模块补平”混合重构。 + +已确认的事实来源： + +- 本地源码目录对照 + - `engine/include/XCEngine/**` + - `editor/src/**` +- 最新审计 + - `python -B docs/api/_tools/audit_api_docs.py` +- 多路 `GPT-5.4 high` 子代理并行审计结论 + +## 当前已确认的结构问题 + +### 1. Rendering 根目录存在明显错位页面 + +以下文档目录名是对的，但父目录已经错了，应该先迁回真实源码子模块： + +- `docs/api/XCEngine/Rendering/CameraRenderer` + - 实际应对应 `engine/include/XCEngine/Rendering/Execution/CameraRenderer.h` + - 目标路径：`docs/api/XCEngine/Rendering/Execution/CameraRenderer` +- `docs/api/XCEngine/Rendering/SceneRenderer` + - 实际应对应 `engine/include/XCEngine/Rendering/Execution/SceneRenderer.h` + - 目标路径：`docs/api/XCEngine/Rendering/Execution/SceneRenderer` +- `docs/api/XCEngine/Rendering/CameraRenderRequest` + - 实际应对应 `engine/include/XCEngine/Rendering/Planning/CameraRenderRequest.h` + - 目标路径：`docs/api/XCEngine/Rendering/Planning/CameraRenderRequest` +- `docs/api/XCEngine/Rendering/SceneRenderRequestPlanner` + - 实际应对应 `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h` + - 目标路径：`docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner` +- `docs/api/XCEngine/Rendering/SceneRenderRequestUtils` + - 实际应对应 `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestUtils.h` + - 目标路径：`docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils` +- `docs/api/XCEngine/Rendering/RenderSceneExtractor` + - 实际应对应 `engine/include/XCEngine/Rendering/Extraction/RenderSceneExtractor.h` + - 目标路径：`docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor` +- `docs/api/XCEngine/Rendering/RenderSceneUtility` + - 实际应对应 `engine/include/XCEngine/Rendering/Extraction/RenderSceneUtility.h` + - 目标路径：`docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility` +- `docs/api/XCEngine/Rendering/RenderResourceCache` + - 实际应对应 `engine/include/XCEngine/Rendering/Caches/RenderResourceCache.h` + - 目标路径：`docs/api/XCEngine/Rendering/Caches/RenderResourceCache` +- `docs/api/XCEngine/Rendering/RenderCameraData` + - 实际应对应 `engine/include/XCEngine/Rendering/FrameData/RenderCameraData.h` + - 目标路径：`docs/api/XCEngine/Rendering/FrameData/RenderCameraData` +- `docs/api/XCEngine/Rendering/ObjectIdPass` + - 当前属于旧命名 + - 实际应归入 `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass` + +### 1.1 已确认“正确目录已存在，但错位旧目录仍保留”的重复区 + +以下区域不是“目标目录不存在”，而是“新目录已经有页，旧错位目录还没清掉”： + +- `Rendering/CameraRenderer` 与 `Rendering/Execution/CameraRenderer` +- `Rendering/SceneRenderer` 与 `Rendering/Execution/SceneRenderer` +- `Rendering/RenderSceneExtractor` 与 `Rendering/Extraction/RenderSceneExtractor` +- `Rendering/RenderSceneUtility` 与 `Rendering/Extraction/RenderSceneUtility` +- `Rendering/RenderResourceCache` 与 `Rendering/Caches/RenderResourceCache` +- `Rendering/RenderCameraData` 与 `Rendering/FrameData/RenderCameraData` +- `Rendering/CameraRenderRequest` 与 `Rendering/Planning/CameraRenderRequest` +- `Rendering/SceneRenderRequestPlanner` 与 `Rendering/Planning/SceneRenderRequestPlanner` +- `Rendering/SceneRenderRequestUtils` 与 `Rendering/Planning/SceneRenderRequestUtils` + +### 2. 已经脱离源码现实的失效页 + +- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md` + - 当前仍引用不存在的 `editor/src/panels/XCUIDemoPanel.h` + - 这是当前审计里唯一明确的失效源文件引用 +- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayRenderer` + - 当前 `editor/src/Viewport` 下已无对应头文件 + - 优先视为待清理历史目录 +- 以下页面仍引用或延续了这条旧链路： + - `docs/api/XCEngine/Editor/panels/panels.md` + - `docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md` + - `docs/api/XCEngine/UI/DrawData/DrawData.md` + +### 3. 旧概念或旧结构残留页 + +以下目录需要先做“是否仍有真实源码对应物”的确认，再决定迁移还是删除： + +- `docs/api/XCEngine/Rendering/RenderMaterialUtility` +- `docs/api/XCEngine/Rendering/ObjectIdEncoding` +- `docs/api/XCEngine/Rendering/VisibleRenderObject` +- `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipelineAsset` +- `docs/api/XCEngine/Rendering/Passes/ObjectIdOutlineStyle` +- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassPlan` +- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassSequenceBuilder` +- `docs/api/XCEngine/Resources/Shader/ShaderRenderState` + +### 4. 本轮新暴露出来的结构缺页 + +这些目录现在是真实源码节点，且已经进入主链，应尽快补平： + +- `docs/api/XCEngine/Resources/Volume/Volume` +- `docs/api/XCEngine/Resources/Volume/VolumeField` +- `docs/api/XCEngine/Resources/Volume/VolumeFieldLoader` +- `docs/api/XCEngine/Components/VolumeRendererComponent` +- `docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem` +- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionMaskPass` +- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass` +- `docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass` +- `docs/api/XCEngine/UI/Widgets/UIDragDropInteraction` +- `docs/api/XCEngine/UI/Widgets/UIScrollModel` +- `docs/api/XCEngine/Editor/ComponentEditors/VolumeRendererComponentEditor` +- `docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialState` +- `docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO` + +## 并行认领规则 + +- 一次只认领一个任务块 +- 认领人必须同时处理： + - 目标页面 + - 所在模块索引页 + - 交叉引用修正 +- 做删除前先执行： + - `rg -n "<名称>" docs/api/XCEngine docs/api/_guides docs/plan` +- 每完成一个任务块后必须执行： + - `python -B docs/api/_tools/audit_api_docs.py` +- 每完成一个阶段后必须： + - `git commit` + - `git push` + +## 并行任务块 + +| ID | 范围 | 目标改动 | 主要路径 | 状态 | 认领人 | +|----|------|----------|----------|------|--------| +| `R1` | Rendering 目录归位 | 把错挂在 `Rendering` 根目录下的页面迁回 `Execution / Planning / Extraction / Caches / FrameData / Passes`，并与已存在的正确目录合并 | `docs/api/XCEngine/Rendering/**` | `pending` | | +| `R2` | 旧概念 Rendering 清理 | 核查并清理 `RenderMaterialUtility / ObjectIdEncoding / VisibleRenderObject / BuiltinForwardPipelineAsset / ObjectIdOutlineStyle / BuiltinPostProcessPassPlan / BuiltinPostProcessPassSequenceBuilder / ShaderRenderState` | `docs/api/XCEngine/Rendering/**` `docs/api/XCEngine/Resources/Shader/**` | `pending` | | +| `R3` | Editor 失效页清理 | 删除或退役 `XCUIDemoPanel / SceneViewportOverlayRenderer`，并修正所有反向引用 | `docs/api/XCEngine/Editor/**` | `pending` | | +| `R4` | Volume 资源与运行时主链 | 补齐 `Volume / VolumeField / VolumeFieldLoader / VolumeRendererComponent / VisibleVolumeItem / BuiltinVolumetricPass` | `docs/api/XCEngine/Resources/**` `docs/api/XCEngine/Components/**` `docs/api/XCEngine/Rendering/**` | `pending` | | +| `R5` | Selection pass 结构补齐 | 补齐 `BuiltinSelectionMaskPass` 与 `BuiltinSelectionOutlinePass`，并同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `pending` | | +| `R6` | UI 新 helper | 补齐 `UIDragDropInteraction` 与 `UIScrollModel`，并同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `pending` | | +| `R7` | Editor 当前真实 helper | 补齐 `VolumeRendererComponentEditor / MaterialInspectorMaterialState / MaterialInspectorMaterialStateIO`，并同步 `ComponentEditors.md` 与 `panels.md` | `docs/api/XCEngine/Editor/**` | `pending` | | +| `R8` | 结构规范补齐 | 修正仍不满足“一类型一文件夹”的点，例如 `Editor/UI/UI`、`Resources/Material/MaterialRenderState` 这类混挂页 | `docs/api/XCEngine/**` | `pending` | | +| `R9` | 全量回归 | 统一修链、清理空目录、重跑审计、收口索引页 | `docs/api/**` | `pending` | | + +## 推荐阶段顺序 + +### Phase 1 + +- `R3` +- `R1` +- `R2` + +说明： + +- 先把失效页和错位目录处理掉，后续内容重写才不会继续落在错误路径上 + +### Phase 2 + +- `R4` +- `R5` +- `R6` +- `R7` +- `R8` + +说明： + +- 这一阶段是把新主链和当前真实 helper 补平 + +### Phase 3 + +- `R9` + +说明： + +- 统一收口、审计、整理最终状态 + +## 最低验收标准 + +### `R1` + +- 所有迁移后的页面目录与真实头文件父目录一致 +- 原路径不再保留 active canonical 页面 + +### `R2` + +- 每个旧概念页都给出明确结论： + - 删除 + - 迁移 + - 改写为真实对应页 + +### `R3` + +- `Invalid source refs` 归零 +- `XCUIDemoPanel` 不再作为当前有效 API 页面存在于 canonical 树 + +### `R4` - `R8` + +- 每个类型都是“一文件夹 + 一主页面” +- 页面描述必须基于当前源码与测试 +- 模块索引页同步更新 + +### `R9` + +- `Invalid header refs = 0` +- `Invalid source refs = 0` +- `Broken .md links = 0` +- `Missing directory index pages = 0` + +## 备注 + +- 当前仓库存在多会话并行改动，尤其是 `Rendering`、`RHI`、`Editor/Viewport` 相关头文件；真正执行重构时优先选择干净路径，避免和其他会话冲突 +- 如果某个任务块执行过程中发现真实源码再次变动，应先回到本任务板更新状态，不要硬做