docs(api): add gaussian splat pages and fix doc generators

2026-04-10 17:12:55 +08:00
parent 66ae9ec919
commit f917040e9a
8 changed files with 246 additions and 104 deletions
--- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md
+++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md
@@ -4,20 +4,20 @@

 **类型**: `submodule`

-**描述**: Gaussian Splat 资源子模块，覆盖运行时 splat payload、artifact I/O 与对应 loader。
+**描述**: 3DGS 资源子模块，覆盖 `GaussianSplat` 运行时资源、`.xcgsplat` artifact 协议与标准 loader。

-## 概述
+## 概览

-`Resources::GaussianSplat` 当前负责把压缩后的 splat payload 以资源形式接入引擎。按当前实现，这条链路分成三层：
+`Resources/GaussianSplat` 当前把 3DGS 资源链拆成三层：

-1. `GaussianSplat`
-   - 保存 metadata、section table 与原始 payload
-2. `GaussianSplatArtifactIO`
-   - 读写 `.xcgsplat` artifact，并在加载时构造 `GaussianSplat`
-3. `GaussianSplatLoader`
-   - 作为 `IResourceLoader` 接入 `ResourceManager`
+- [GaussianSplat](GaussianSplat/GaussianSplat.md)
+  运行时资源对象，保存 section 元数据与 payload。
+- [GaussianSplatArtifactIO](GaussianSplatArtifactIO/GaussianSplatArtifactIO.md)
+  `.xcgsplat` 的写入与回读协议。
+- [GaussianSplatLoader](GaussianSplatLoader/GaussianSplatLoader.md)
+  只面向 `.xcgsplat` artifact 的标准资源加载器。

-和 [Model](../Model/Model.md) / [Mesh](../Mesh/Mesh.md) 这类图结构资源不同，`GaussianSplat` 更像“多 section 二进制块 + metadata”的只读 payload 资源。
+这条链路当前只负责资源层与 artifact 层，不在这里直接创建 GPU residency，也不在这里承担最终渲染 pass。

 ## 头文件

@@ -28,5 +28,6 @@
 ## 相关文档

 - [Resources](../Resources.md)
- [Core / Asset](../../Core/Asset/Asset.md)
- [Model](../Model/Model.md)
+- [Volume](../Volume/Volume.md)
+- [Rendering](../../Rendering/Rendering.md)
+- [API 总索引](../../../main.md)
--- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md
+++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md
@@ -8,54 +8,62 @@

 **源文件**: `engine/src/Resources/GaussianSplat/GaussianSplat.cpp`

-**描述**: Gaussian Splat 运行时资源对象，保存 metadata、section table 与原始 payload。
+**描述**: 3DGS 运行时资源对象，保存 splat metadata、section table 和 artifact payload 字节数据。

-## 概述
+## 概览

-`GaussianSplat` 当前把 splat 数据拆成三层状态：
+`GaussianSplat` 是当前 3DGS 资源在运行时的最小封装。它并不直接创建 GPU buffer 或 texture，而是把 `.xcgsplat` loader 读出的内容保存在 CPU 侧，供后续：

- `GaussianSplatMetadata`
-  - 内容版本、splat/chunk/camera 数量、bounds 与 section format
- `GaussianSplatSection`
-  - 每个 section 的类型、格式、payload 偏移、大小和元素布局
- `payload`
-  - 实际的二进制块数据
+- 资源系统缓存
+- artifact round-trip
+- 渲染缓存层上传 GPU 资源

-这让资源对象可以在不理解每种 section 语义的前提下，统一保存和查询 payload。
+使用。
+
+## 声明概览
+
+| 声明 | 类型 | 说明 |
+|------|------|------|
+| `GaussianSplatSectionType` | `enum class` | section 语义类型，区分 `Positions`、`Color`、`SH`、`Chunks` 等 payload 分区。 |
+| `GaussianSplatSectionFormat` | `enum class` | section 数据布局格式，描述 float/packed/color/sh/chunk 等编码方式。 |
+| `GaussianSplatSection` | `struct` | 单个 section 的偏移、大小、元素数和 stride 描述。 |
+| `GaussianSplatMetadata` | `struct` | 资源级 metadata，记录 splat 数量、bounds 与各 section 的格式。 |

 ## 当前状态模型

 | 字段 | 说明 |
 |------|------|
-| `m_metadata` | 版本、bounds、计数和 section format |
-| `m_sections` | section 描述表 |
-| `m_payload` | 原始二进制 payload |
+| `m_metadata` | 当前资源的 splat 数量、bounds、chunk/camera 计数与 section format |
+| `m_sections` | section table，描述每个 payload 分段的偏移和布局 |
+| `m_payload` | artifact 读回的原始 payload 字节数组 |

 ## 当前实现行为

 - `CreateOwned(...)`
-  - 先验证 section table，再接管 metadata / sections / payload
- `FindSection(...)`
-  - 按 `GaussianSplatSectionType` 查找 section 记录
- `GetSectionData(...)`
-  - 根据 section 的 `dataOffset` 返回 payload 里的起始地址
+  - 先校验 section 类型唯一且范围不越界
+  - 成功时接管 section 与 payload 所有权，并把资源标记为 valid
 - `Clear()`
-  - 清空 metadata、section table 和 payload，并把资源标记为 invalid
+  - 清空 metadata、section table 和 payload，并重置 valid 状态
+- `FindSection(...)`
+  - 按 section type 线性查找当前资源里的分段定义
+- `GetSectionData(...)`
+  - 若目标 section 不存在或 `dataSize == 0`，返回 `nullptr`
+  - 否则返回 payload 中对应偏移的只读指针
 - `Release()`
  - 当前直接执行 `delete this`

 ## 测试与调用链

- `tests/Resources/GaussianSplat/test_gaussian_splat.cpp`
-  - 覆盖 `CreateOwned(...)` 的 metadata / payload 保存与非法 section layout 拒绝
 - `engine/src/Resources/GaussianSplat/GaussianSplatArtifactIO.cpp`
-  - 当前把 artifact 读回结果装配成 `GaussianSplat`
+  - 当前通过 `CreateOwned(...)` 构造 loader 读回的运行时资源
+- `GaussianSplatLoader`
+  - 负责把 `.xcgsplat` artifact 交给资源系统并恢复成 `GaussianSplat`

 ## 当前实现边界

- 当前对象只提供按 section 粗粒度查询，不做更高层语义解码。
- `ValidateSections(...)` 会拒绝 `Unknown` section、越界 payload 区间和重复 section type。
- payload 生命周期完全由资源对象拥有，不借用外部内存。
+- 当前资源只保存 CPU 侧 metadata 和 payload，不直接持有 GPU 资源。
+- section 校验当前只保证类型唯一和边界合法，不做更高层的 3DGS 语义验证。
+- 后续 GPU residency cache 需要自行决定哪些 section 被上传成 buffer、哪些被上传成 texture。

 ## 相关文档

--- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md
+++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md
@@ -8,48 +8,41 @@

 **源文件**: `engine/src/Resources/GaussianSplat/GaussianSplatArtifactIO.cpp`

-**描述**: `.xcgsplat` artifact 的读写入口，负责把 Gaussian Splat payload 序列化到磁盘并恢复成运行时资源。
+**描述**: `.xcgsplat` artifact 的读写入口，负责把 `GaussianSplat` 资源写成磁盘协议并恢复为运行时对象。

-## 概述
+## 概览

 `GaussianSplatArtifactIO` 当前公开两个函数：

 - `WriteGaussianSplatArtifactFile(...)`
-  - 把 `GaussianSplat` 的 metadata、section table 和 payload 写成 `.xcgsplat`
+  - 把 `GaussianSplat` 写成 `.xcgsplat`
 - `LoadGaussianSplatArtifact(...)`
-  - 读取 `.xcgsplat` 并恢复成 `GaussianSplat`
+  - 读取 `.xcgsplat` 并恢复 `GaussianSplat`
+
+这两个函数共同构成当前 3DGS 资源的 artifact 协议边界。

 ## 当前实现行为

 ### 写入路径

- 会先解析 artifact 路径并在需要时创建父目录。
- 文件头 magic 当前校验为 `XCGSP01` 协议。
- 写入顺序是：
-  - `GaussianSplatArtifactFileHeader`
-  - `GaussianSplatArtifactHeader`
-  - section table
-  - payload 字节块
+- 会先解析 artifact 路径，必要时创建父目录。
+- 文件头当前写入 `GaussianSplatArtifactFileHeader`，magic 固定校验为 `XCGSP01`。
+- metadata 会序列化 splat 数量、chunk/camera 计数、bounds 和各 section format。
+- section table 会顺序写入 section type、format、offset、size、elementCount 与 stride。
+- 若 payload 非空，最后会把整段 payload 原样写入文件尾。

 ### 读取路径

- 会解析真实路径，必要时回退到 `ResourceManager::Get().GetResourceRoot()`。
- header 校验失败会直接返回错误的 `LoadResult`。
- 读取 section table 后会还原成 `GaussianSplatSection` 数组，再读 payload。
- 成功时通过内部 `CreateOwnedGaussianSplatResource(...)` 构造资源对象。
-
-## 测试与调用链
-
- `tests/Resources/GaussianSplat/test_gaussian_splat_loader.cpp`
-  - 覆盖写 artifact、再由 loader 读回的往返路径
- `engine/src/Resources/GaussianSplat/GaussianSplatLoader.cpp`
-  - 当前把实际 `.xcgsplat` 读取委托给 `LoadGaussianSplatArtifact(...)`
+- 会先解析真实路径，必要时回退到 `ResourceManager::Get().GetResourceRoot()`。
+- 会校验 file header 和 `kGaussianSplatArtifactSchemaVersion`。
+- 读取 section table 后恢复 `GaussianSplatSection` 数组。
+- payload 读回后会通过内部 `CreateOwnedGaussianSplatResource(...)` 构造运行时资源。

 ## 当前实现边界

- 当前只处理 `.xcgsplat` artifact，不直接解析外部原始 Gaussian Splat 源格式。
- artifact 的 section 语义依赖 header 里的 metadata/format，不在这里做高层解释。
- 读取失败时直接返回错误，不做容错修复。
+- 当前只处理 `.xcgsplat` artifact，不直接解析 `.ply` 等 source asset。
+- schema version 不匹配时直接失败，不做向后兼容恢复。
+- artifact 协议当前只保证 section 化 payload 的稳定保存，不承担 GPU 资源预热。

 ## 相关文档

--- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md
+++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md
@@ -10,9 +10,9 @@

 **描述**: `GaussianSplat` 资源的标准 loader，负责识别 `.xcgsplat` artifact 并通过 `GaussianSplatArtifactIO` 读入运行时资源。

-## 概述
+## 概览

-`GaussianSplatLoader` 继承自 `IResourceLoader`，是 `ResourceManager` 当前注册的 Gaussian Splat 资源入口。实现策略和 `ModelLoader` 类似：
+`GaussianSplatLoader` 继承自 `IResourceLoader`，是当前 3DGS 资源进入 `ResourceManager` 的正式入口。它的实现刻意保持很窄：

 - 只接受 `.xcgsplat`
 - 实际反序列化委托给 `LoadGaussianSplatArtifact(...)`
@@ -38,12 +38,11 @@
 - `GetDefaultSettings()` 当前返回 `nullptr`
 - 文件末尾通过 `REGISTER_RESOURCE_LOADER(GaussianSplatLoader)` 注册到资源系统

-## 测试与调用链
+## 当前实现边界

- `tests/Resources/GaussianSplat/test_gaussian_splat_loader.cpp`
-  - 覆盖扩展名判断、非法路径、artifact 往返加载与 `ResourceManager` 注册
- `engine/src/Core/Asset/ResourceManager.cpp`
-  - 当前持有全局 `GaussianSplatLoader` 并注册到资源系统
+- 当前只面向 `.xcgsplat` artifact，不承担 `.ply` source import。
+- loader 只构造 CPU 侧运行时资源，不直接创建设备侧 GPU 资源。
+- 更底层的 schema 校验与 payload 反序列化继续留在 [GaussianSplatArtifactIO](../GaussianSplatArtifactIO/GaussianSplatArtifactIO.md)。

 ## 相关文档