xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): sync xceditor roots and model importer

Browse Source
This commit is contained in:
ssdfasd
2026-04-10 17:08:37 +08:00
parent 4d8a51aee2
commit 6b90c2f6c3
5 changed files with 134 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/api/XCEngine/Editor/Editor.md
View File

@@ -67,13 +67,13 @@
- 当前编辑器主路径仍然以 Windows + D3D12 + Dear ImGui 为核心。 - 当前编辑器主路径仍然以 Windows + D3D12 + Dear ImGui 为核心。
- 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 SDK。 - 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 SDK。
- 自动审计脚本目前主要覆盖 `engine/include/XCEngine/**` 的 public headers；Editor 这组文档更依赖目录并行约束、链接校验和人工核对源码行为。 - 自动审计脚本现在同时覆盖 `engine/include/XCEngine/**` 与 `new_editor/include/XCEditor/**` 的 public headers；`docs/api/XCEngine/Editor/**` 这组 source-backed 文档仍更依赖目录并行约束、链接校验和人工核对源码行为。
## 文档边界更新（2026-04-09） ## 文档边界更新（2026-04-10）
- `docs/api/XCEngine/Editor/**` 当前严格对应旧 `editor/src/**`。 - `docs/api/XCEngine/Editor/**` 当前严格对应旧 `editor/src/**`。
- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，不再适合继续并入这棵旧树。 - `docs/api/XCEditor/**` 现在单独对应 `new_editor/include/XCEditor/**` 的新 Editor 基础层 public headers。
- 后续会为 `XCEditor` 单独建立新的 API 文档根树，并把 `Collections / Fields / Foundation / Shell / Widgets` 迁到新结构下。 - `new_editor/app/**` 与 `new_editor/ui/**` 属于宿主与产品装配层，不并入这棵 public-header canonical 树。
## 目录 ## 目录
@@ -101,5 +101,6 @@
- [Scene](../Scene/Scene.md) - [Scene](../Scene/Scene.md)
- [Components](../Components/Components.md) - [Components](../Components/Components.md)
- [Rendering](../Rendering/Rendering.md) - [Rendering](../Rendering/Rendering.md)
- [XCEditor](../../XCEditor/XCEditor.md)
- [Editor Architecture And Workflow](../../_guides/Editor/Editor-Architecture-And-Workflow.md) - [Editor Architecture And Workflow](../../_guides/Editor/Editor-Architecture-And-Workflow.md)
- [API 总索引](../../main.md) - [API 总索引](../../main.md)

57
docs/api/XCEngine/Resources/Model/AssimpModelImporter/AssimpModelImporter.md Normal file
View File

@@ -0,0 +1,57 @@
# AssimpModelImporter
**命名空间**: `XCEngine::Resources`
**类型**: `header`
**头文件**: `XCEngine/Resources/Model/AssimpModelImporter.h`
**源文件**: `engine/src/Resources/Model/AssimpModelImporter.cpp`
**描述**: Assimp 模型导入 helper 的 contract 头文件，声明导入结果结构体和 `ImportAssimpModel(...)` 入口。
## 概述
`AssimpModelImporter.h` 当前声明的是“把源模型文件导入成 `Model + Mesh + Material + Texture` 组合结果”的接口层，而不是 `.xcmodel` artifact loader。
按当前头文件，它主要暴露：
- `ImportedModelMesh`
- 单个导入 mesh 的 local id、mesh 指针和材质 local id 列表
- `ImportedModelMaterial`
- 单个导入 material 的 local id 与 material 指针
- `ImportedModelData`
- 一次导入得到的 `Model`、mesh/material 集合与纹理集合
- `ImportAssimpModel(...)`
- 以 `sourcePath + MeshImportSettings` 为输入，把导入结果写进 `ImportedModelData`
## 声明概览
| 声明 | 类型 | 说明 |
|------|------|------|
| `ImportedModelMesh` | `struct` | 单个 mesh 导入结果与材质绑定索引。 |
| `ImportedModelMaterial` | `struct` | 单个 material 导入结果。 |
| `ImportedModelData` | `struct` | 一次模型导入得到的资源集合。 |
| `ImportAssimpModel(...)` | `function` | 以 Assimp 为前端的模型导入入口。 |
## 当前状态模型
| 结构 | 关键字段 | 说明 |
|------|----------|------|
| `ImportedModelMesh` | `localID`, `mesh`, `materialLocalIDs` | 导入出的 mesh 及其材质绑定 |
| `ImportedModelMaterial` | `localID`, `material` | 导入出的 material |
| `ImportedModelData` | `model`, `meshes`, `materials`, `textures` | 一次导入得到的完整资源集合 |
## 当前实现边界
- 当前实现已经落在 `engine/src/Resources/Model/AssimpModelImporter.cpp`，内部直接依赖 Assimp、`ResourceManager`、`TextureLoader` 与若干 `Resources/*` 运行时类型。
- 头文件只暴露导入结果结构与顶层入口；路径解析、纹理缓存、Assimp 后处理参数与子资源构建细节都收敛在 `.cpp` 内部 helper。
- 现有 `AssetDatabase::ImportModelAsset(...)` 仍会把导入结果进一步落到模型相关资源与 artifact 流程里，因此这里负责的是“源模型导入前端”，不是 `.xcmodel` artifact loader。
- 即便如此，这个头文件仍是 `XCEngine/Resources/Model` 下真实存在的 public header，因此需要保留 canonical API 页面。
## 相关文档
- [Model 子模块](../Model.md)
- [Model](../Model/Model.md)
- [ModelLoader](../ModelLoader/ModelLoader.md)
- [API 总索引](../../../../main.md)

14
docs/api/XCEngine/XCEngine.md
View File

@@ -4,16 +4,23 @@
**类型**: `module-root` **类型**: `module-root`
**描述**: `XCEngine` public API 的根目录入口，对齐 `engine/include/XCEngine` 的源码模块结构。 **描述**: `XCEngine` runtime public API 与旧编辑器应用层文档根，对齐 `engine/include/XCEngine` 与 `editor/src` 的现有 canonical 结构。
## 概览 ## 概览
`docs/api/XCEngine` 是当前唯一的 canonical API 文档树。它和 `engine/include/XCEngine` 保持平行目录结构，用来回答两类问题： `docs/api/XCEngine` 不再是唯一的 canonical API 根树。它当前负责：
- `engine/include/XCEngine/**` 这组 runtime public headers
- `editor/src/**` 这组旧编辑器应用层文档入口
新编辑器基础层 public headers 已转到 [XCEditor](../XCEditor/XCEditor.md)。
这棵树和 `engine/include/XCEngine` 保持平行目录结构，用来回答两类问题：
- 这个模块在引擎里负责什么，边界在哪里。 - 这个模块在引擎里负责什么，边界在哪里。
- 这个 public header 在当前版本里到底做到了什么程度。 - 这个 public header 在当前版本里到底做到了什么程度。
同时，这里也统一收纳编辑器侧 API 文档入口 [Editor](Editor/Editor.md)，用于描述与引擎并行协作的编辑器应用层接口。 同时，这里继续收纳旧编辑器应用层入口 [Editor](Editor/Editor.md)，用于描述与引擎并行协作的工具应用接口。
本轮收口之后，`Core/Asset`、`Rendering`、`Resources` 和 `Scene` 这几个模块已经把基础 helper / 协议层 header 也纳入了 canonical 文档，而不只覆盖高层类和模块页。 本轮收口之后，`Core/Asset`、`Rendering`、`Resources` 和 `Scene` 这几个模块已经把基础 helper / 协议层 header 也纳入了 canonical 文档，而不只覆盖高层类和模块页。
@@ -50,4 +57,5 @@
## 相关文档 ## 相关文档
- [API 总索引](../main.md) - [API 总索引](../main.md)
- [XCEditor API 根](../XCEditor/XCEditor.md)
- [API 文档重构状态](../_meta/rebuild-status.md) - [API 文档重构状态](../_meta/rebuild-status.md)

61
docs/api/_meta/rebuild-status.md
View File

@@ -1,17 +1,19 @@
# API 文档重构状态 # API 文档重构状态
**生成时间**: `2026-04-10 00:07:30` **生成时间**: `2026-04-10 17:07:09`
**来源**: `docs/api/_tools/audit_api_docs.py` **来源**: `docs/api/_tools/audit_api_docs.py`
## 摘要 ## 摘要
- Markdown 页面数（全部）: `3793` - Markdown 页面数（全部）: `3934`
- Markdown 页面数（canonical）: `3765` - Markdown 页面数（canonical）: `3906`
- Public headers 数: `313` - Public headers 数: `384`
- `XCEditor` public headers 数: `64`（canonical 已覆盖 `64`）
- `XCEngine` public headers 数: `320`（canonical 已覆盖 `320`）
- Editor source headers 数: `144` - Editor source headers 数: `144`
- 有效头文件引用数（全部）: `313` - 有效头文件引用数（全部）: `384`
- 有效头文件引用数（canonical）: `313` - 有效头文件引用数（canonical）: `384`
- 无效头文件引用数: `0` - 无效头文件引用数: `0`
- 有效源文件引用数（全部）: `144` - 有效源文件引用数（全部）: `144`
- 有效源文件引用数（Editor canonical）: `144` - 有效源文件引用数（Editor canonical）: `144`
@@ -27,9 +29,9 @@
## 平行目录 ## 平行目录
- Canonical 根目录: `XCEngine` - Canonical 根目录: `XCEngine, XCEditor`
- 源码目录节点数: `49` - 源码目录节点数: `57`
- 已生成目录总览页节点数: `49` - 已生成目录总览页节点数: `57`
- 缺失目录总览页节点数: `0` - 缺失目录总览页节点数: `0`
- 支撑目录: `_meta, _tools` - 支撑目录: `_meta, _tools`
@@ -37,20 +39,25 @@
| 模块 | Public headers | 已覆盖 | 未覆盖 | | 模块 | Public headers | 已覆盖 | 未覆盖 |
|------|----------------|--------|--------| |------|----------------|--------|--------|
| `Audio` | `11` | `11` | `0` | | `XCEditor/Collections` | `9` | `9` | `0` |
| `Components` | `11` | `11` | `0` | | `XCEditor/Fields` | `23` | `23` | `0` |
| `Core` | `48` | `48` | `0` | | `XCEditor/Foundation` | `4` | `4` | `0` |
| `Debug` | `10` | `10` | `0` | | `XCEditor/Shell` | `24` | `24` | `0` |
| `Input` | `5` | `5` | `0` | | `XCEditor/Widgets` | `4` | `4` | `0` |
| `Memory` | `5` | `5` | `0` | | `XCEngine/Audio` | `11` | `11` | `0` |
| `Platform` | `11` | `11` | `0` | | `XCEngine/Components` | `11` | `11` | `0` |
| `RHI` | `88` | `88` | `0` | | `XCEngine/Core` | `48` | `48` | `0` |
| `Rendering` | `42` | `42` | `0` | | `XCEngine/Debug` | `10` | `10` | `0` |
| `Resources` | `22` | `22` | `0` | | `XCEngine/Input` | `5` | `5` | `0` |
| `Scene` | `4` | `4` | `0` | | `XCEngine/Memory` | `5` | `5` | `0` |
| `Scripting` | `7` | `7` | `0` | | `XCEngine/Platform` | `11` | `11` | `0` |
| `Threading` | `10` | `10` | `0` | | `XCEngine/RHI` | `88` | `88` | `0` |
| `UI` | `39` | `39` | `0` | | `XCEngine/Rendering` | `42` | `42` | `0` |
| `XCEngine/Resources` | `29` | `29` | `0` |
| `XCEngine/Scene` | `4` | `4` | `0` |
| `XCEngine/Scripting` | `7` | `7` | `0` |
| `XCEngine/Threading` | `10` | `10` | `0` |
| `XCEngine/UI` | `39` | `39` | `0` |
## Editor 源文件页覆盖 ## Editor 源文件页覆盖
@@ -76,8 +83,8 @@
| 字段 | 页面数 | | 字段 | 页面数 |
|------|--------| |------|--------|
| `命名空间` | `2491` | | `命名空间` | `2563` |
| `类型` | `2491` | | `类型` | `2563` |
| `描述` | `550` | | `描述` | `617` |
| `头文件` | `1903` | | `头文件` | `1968` |
| `源文件` | `520` | | `源文件` | `520` |

68
docs/api/main.md
View File

@@ -4,59 +4,45 @@
**类型**: `index` **类型**: `index`
**描述**: 指向 `docs/api/XCEngine` 平行目录树与审计状态页的统一 API 文档入口。 **描述**: 指向 `docs/api/XCEngine` 与 `docs/api/XCEditor` 两棵 canonical API 文档树以及审计状态页的统一入口。
## 概览 ## 概述
`docs/api/XCEngine/**` 是当前唯一正式的 canonical API 文档树，其层级与 `engine/include/XCEngine/**` 保持平行。 `docs/api` 当前维护两组并行的 public API 文档：
根索引负责两件事： - `docs/api/XCEngine/**`
- 对齐 `engine/include/XCEngine/**`
- `docs/api/XCEditor/**`
- 对齐 `new_editor/include/XCEditor/**`
- 给出所有主要模块的入口导航。 除此之外，`docs/api/XCEngine/Editor/**` 仍然描述 `editor/src/**` 这组 source-backed 旧编辑器 API。它和 `XCEditor` 不是同一棵树，后者对应的是新编辑器 UI / shell / widgets public headers。
- 指向最新的文档审计状态，方便确认覆盖率、断链和遗留缺口。
## Canonical 入口 ## Canonical 入口
- [XCEngine/XCEngine.md](XCEngine/XCEngine.md) - 与 `engine/include/XCEngine` 平行的文档根目录 - [XCEngine/XCEngine.md](XCEngine/XCEngine.md) - 与 `engine/include/XCEngine/**` 并行的引擎运行时 API 根目录
- [_meta/rebuild-status.md](_meta/rebuild-status.md) - 当前覆盖率、链接检查和审计状态 - [XCEditor/XCEditor.md](XCEditor/XCEditor.md) - 与 `new_editor/include/XCEditor/**` 并行的新编辑器 public API 根目录
- [_meta/rebuild-status.md](_meta/rebuild-status.md) - 当前覆盖率、断链检查和目录索引审计状态
## 模块导航 ## 文档根树
| 文档根 | Canonical 文档 | 对应源码目录 |
|------|----------------|--------------|
| `XCEngine` | [XCEngine/XCEngine.md](XCEngine/XCEngine.md) | `engine/include/XCEngine/` |
| `XCEditor` | [XCEditor/XCEditor.md](XCEditor/XCEditor.md) | `new_editor/include/XCEditor/` |
## XCEditor 模块导航
| 模块 | Canonical 文档 | 对应源码目录 | | 模块 | Canonical 文档 | 对应源码目录 |
|------|----------------|--------------| |------|----------------|--------------|
| `Audio` | [XCEngine/Audio/Audio.md](XCEngine/Audio/Audio.md) | `XCEngine/Audio/` | | `Collections` | [XCEditor/Collections/Collections.md](XCEditor/Collections/Collections.md) | `new_editor/include/XCEditor/Collections/` |
| `Components` | [XCEngine/Components/Components.md](XCEngine/Components/Components.md) | `XCEngine/Components/` | | `Fields` | [XCEditor/Fields/Fields.md](XCEditor/Fields/Fields.md) | `new_editor/include/XCEditor/Fields/` |
| `Core` | [XCEngine/Core/Core.md](XCEngine/Core/Core.md) | `XCEngine/Core/` | | `Foundation` | [XCEditor/Foundation/Foundation.md](XCEditor/Foundation/Foundation.md) | `new_editor/include/XCEditor/Foundation/` |
| `Debug` | [XCEngine/Debug/Debug.md](XCEngine/Debug/Debug.md) | `XCEngine/Debug/` | | `Shell` | [XCEditor/Shell/Shell.md](XCEditor/Shell/Shell.md) | `new_editor/include/XCEditor/Shell/` |
| `Editor` | [XCEngine/Editor/Editor.md](XCEngine/Editor/Editor.md) | `editor/src/` | | `Widgets` | [XCEditor/Widgets/Widgets.md](XCEditor/Widgets/Widgets.md) | `new_editor/include/XCEditor/Widgets/` |
| `Input` | [XCEngine/Input/Input.md](XCEngine/Input/Input.md) | `XCEngine/Input/` |
| `Memory` | [XCEngine/Memory/Memory.md](XCEngine/Memory/Memory.md) | `XCEngine/Memory/` |
| `Platform` | [XCEngine/Platform/Platform.md](XCEngine/Platform/Platform.md) | `XCEngine/Platform/` |
| `Rendering` | [XCEngine/Rendering/Rendering.md](XCEngine/Rendering/Rendering.md) | `XCEngine/Rendering/` |
| `Resources` | [XCEngine/Resources/Resources.md](XCEngine/Resources/Resources.md) | `XCEngine/Resources/` |
| `RHI` | [XCEngine/RHI/RHI.md](XCEngine/RHI/RHI.md) | `XCEngine/RHI/` |
| `Scene` | [XCEngine/Scene/Scene.md](XCEngine/Scene/Scene.md) | `XCEngine/Scene/` |
| `Scripting` | [XCEngine/Scripting/Scripting.md](XCEngine/Scripting/Scripting.md) | `XCEngine/Scripting/` |
| `Threading` | [XCEngine/Threading/Threading.md](XCEngine/Threading/Threading.md) | `XCEngine/Threading/` |
## 关键子模块
| 子模块 | Canonical 文档 | 对应源码目录 |
|--------|----------------|--------------|
| `Core/Asset` | [XCEngine/Core/Asset/Asset.md](XCEngine/Core/Asset/Asset.md) | `XCEngine/Core/Asset/` |
| `Core/Containers` | [XCEngine/Core/Containers/Containers.md](XCEngine/Core/Containers/Containers.md) | `XCEngine/Core/Containers/` |
| `Core/IO` | [XCEngine/Core/IO/IO.md](XCEngine/Core/IO/IO.md) | `XCEngine/Core/IO/` |
| `Core/Math` | [XCEngine/Core/Math/Math.md](XCEngine/Core/Math/Math.md) | `XCEngine/Core/Math/` |
| `Editor/Viewport` | [XCEngine/Editor/Viewport/Viewport.md](XCEngine/Editor/Viewport/Viewport.md) | `editor/src/Viewport/` |
| `Rendering/Passes` | [XCEngine/Rendering/Passes/Passes.md](XCEngine/Rendering/Passes/Passes.md) | `XCEngine/Rendering/Passes/` |
| `Platform/Windows` | [XCEngine/Platform/Windows/Windows.md](XCEngine/Platform/Windows/Windows.md) | `XCEngine/Platform/Windows/` |
| `Resources/Mesh` | [XCEngine/Resources/Mesh/Mesh.md](XCEngine/Resources/Mesh/Mesh.md) | `XCEngine/Resources/Mesh/` |
| `Resources/Texture` | [XCEngine/Resources/Texture/Texture.md](XCEngine/Resources/Texture/Texture.md) | `XCEngine/Resources/Texture/` |
| `RHI/D3D12` | [XCEngine/RHI/D3D12/D3D12.md](XCEngine/RHI/D3D12/D3D12.md) | `XCEngine/RHI/D3D12/` |
| `RHI/OpenGL` | [XCEngine/RHI/OpenGL/OpenGL.md](XCEngine/RHI/OpenGL/OpenGL.md) | `XCEngine/RHI/OpenGL/` |
## 相关文档 ## 相关文档
- [XCEngine 平行目录根](XCEngine/XCEngine.md) - [XCEngine 根目录](XCEngine/XCEngine.md)
- [XCEditor 根目录](XCEditor/XCEditor.md)
- [XCEngine Editor source-backed API](XCEngine/Editor/Editor.md)
- [API 文档重构状态](_meta/rebuild-status.md) - [API 文档重构状态](_meta/rebuild-status.md)
- [XCEngine 架构设计](../used/XCEngine渲染引擎架构设计.md)