From 6b90c2f6c3f896d958f15f6e281f08b449d7d324 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 10 Apr 2026 17:08:37 +0800 Subject: [PATCH] docs(api): sync xceditor roots and model importer --- docs/api/XCEngine/Editor/Editor.md | 9 +-- .../AssimpModelImporter.md | 57 ++++++++++++++++ docs/api/XCEngine/XCEngine.md | 14 +++- docs/api/_meta/rebuild-status.md | 61 +++++++++-------- docs/api/main.md | 68 ++++++++----------- 5 files changed, 134 insertions(+), 75 deletions(-) create mode 100644 docs/api/XCEngine/Resources/Model/AssimpModelImporter/AssimpModelImporter.md diff --git a/docs/api/XCEngine/Editor/Editor.md b/docs/api/XCEngine/Editor/Editor.md index 71afcb4e..d2d17000 100644 --- a/docs/api/XCEngine/Editor/Editor.md +++ b/docs/api/XCEngine/Editor/Editor.md @@ -67,13 +67,13 @@ - 当前编辑器主路径仍然以 Windows + D3D12 + Dear ImGui 为核心。 - 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 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/**`。 -- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，不再适合继续并入这棵旧树。 -- 后续会为 `XCEditor` 单独建立新的 API 文档根树，并把 `Collections / Fields / Foundation / Shell / Widgets` 迁到新结构下。 +- `docs/api/XCEditor/**` 现在单独对应 `new_editor/include/XCEditor/**` 的新 Editor 基础层 public headers。 +- `new_editor/app/**` 与 `new_editor/ui/**` 属于宿主与产品装配层，不并入这棵 public-header canonical 树。 ## 目录 @@ -101,5 +101,6 @@ - [Scene](../Scene/Scene.md) - [Components](../Components/Components.md) - [Rendering](../Rendering/Rendering.md) +- [XCEditor](../../XCEditor/XCEditor.md) - [Editor Architecture And Workflow](../../_guides/Editor/Editor-Architecture-And-Workflow.md) - [API 总索引](../../main.md) diff --git a/docs/api/XCEngine/Resources/Model/AssimpModelImporter/AssimpModelImporter.md b/docs/api/XCEngine/Resources/Model/AssimpModelImporter/AssimpModelImporter.md new file mode 100644 index 00000000..73db388d --- /dev/null +++ b/docs/api/XCEngine/Resources/Model/AssimpModelImporter/AssimpModelImporter.md @@ -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) diff --git a/docs/api/XCEngine/XCEngine.md b/docs/api/XCEngine/XCEngine.md index cd9bbe11..8646e18c 100644 --- a/docs/api/XCEngine/XCEngine.md +++ b/docs/api/XCEngine/XCEngine.md @@ -4,16 +4,23 @@ **类型**: `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 在当前版本里到底做到了什么程度。 -同时，这里也统一收纳编辑器侧 API 文档入口 [Editor](Editor/Editor.md)，用于描述与引擎并行协作的编辑器应用层接口。 +同时，这里继续收纳旧编辑器应用层入口 [Editor](Editor/Editor.md)，用于描述与引擎并行协作的工具应用接口。 本轮收口之后，`Core/Asset`、`Rendering`、`Resources` 和 `Scene` 这几个模块已经把基础 helper / 协议层 header 也纳入了 canonical 文档，而不只覆盖高层类和模块页。 @@ -50,4 +57,5 @@ ## 相关文档 - [API 总索引](../main.md) +- [XCEditor API 根](../XCEditor/XCEditor.md) - [API 文档重构状态](../_meta/rebuild-status.md) diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index fadabc86..2fc2f956 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.md @@ -1,17 +1,19 @@ # API 文档重构状态 -**生成时间**: `2026-04-10 00:07:30` +**生成时间**: `2026-04-10 17:07:09` **来源**: `docs/api/_tools/audit_api_docs.py` ## 摘要 -- Markdown 页面数（全部）: `3793` -- Markdown 页面数（canonical）: `3765` -- Public headers 数: `313` +- Markdown 页面数（全部）: `3934` +- Markdown 页面数（canonical）: `3906` +- Public headers 数: `384` +- `XCEditor` public headers 数: `64`（canonical 已覆盖 `64`） +- `XCEngine` public headers 数: `320`（canonical 已覆盖 `320`） - Editor source headers 数: `144` -- 有效头文件引用数（全部）: `313` -- 有效头文件引用数（canonical）: `313` +- 有效头文件引用数（全部）: `384` +- 有效头文件引用数（canonical）: `384` - 无效头文件引用数: `0` - 有效源文件引用数（全部）: `144` - 有效源文件引用数（Editor canonical）: `144` @@ -27,9 +29,9 @@ ## 平行目录 -- Canonical 根目录: `XCEngine` -- 源码目录节点数: `49` -- 已生成目录总览页节点数: `49` +- Canonical 根目录: `XCEngine, XCEditor` +- 源码目录节点数: `57` +- 已生成目录总览页节点数: `57` - 缺失目录总览页节点数: `0` - 支撑目录: `_meta, _tools` @@ -37,20 +39,25 @@ | 模块 | Public headers | 已覆盖 | 未覆盖 | |------|----------------|--------|--------| -| `Audio` | `11` | `11` | `0` | -| `Components` | `11` | `11` | `0` | -| `Core` | `48` | `48` | `0` | -| `Debug` | `10` | `10` | `0` | -| `Input` | `5` | `5` | `0` | -| `Memory` | `5` | `5` | `0` | -| `Platform` | `11` | `11` | `0` | -| `RHI` | `88` | `88` | `0` | -| `Rendering` | `42` | `42` | `0` | -| `Resources` | `22` | `22` | `0` | -| `Scene` | `4` | `4` | `0` | -| `Scripting` | `7` | `7` | `0` | -| `Threading` | `10` | `10` | `0` | -| `UI` | `39` | `39` | `0` | +| `XCEditor/Collections` | `9` | `9` | `0` | +| `XCEditor/Fields` | `23` | `23` | `0` | +| `XCEditor/Foundation` | `4` | `4` | `0` | +| `XCEditor/Shell` | `24` | `24` | `0` | +| `XCEditor/Widgets` | `4` | `4` | `0` | +| `XCEngine/Audio` | `11` | `11` | `0` | +| `XCEngine/Components` | `11` | `11` | `0` | +| `XCEngine/Core` | `48` | `48` | `0` | +| `XCEngine/Debug` | `10` | `10` | `0` | +| `XCEngine/Input` | `5` | `5` | `0` | +| `XCEngine/Memory` | `5` | `5` | `0` | +| `XCEngine/Platform` | `11` | `11` | `0` | +| `XCEngine/RHI` | `88` | `88` | `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 源文件页覆盖 @@ -76,8 +83,8 @@ | 字段 | 页面数 | |------|--------| -| `命名空间` | `2491` | -| `类型` | `2491` | -| `描述` | `550` | -| `头文件` | `1903` | +| `命名空间` | `2563` | +| `类型` | `2563` | +| `描述` | `617` | +| `头文件` | `1968` | | `源文件` | `520` | diff --git a/docs/api/main.md b/docs/api/main.md index 4308dee9..02906931 100644 --- a/docs/api/main.md +++ b/docs/api/main.md @@ -4,59 +4,45 @@ **类型**: `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 入口 -- [XCEngine/XCEngine.md](XCEngine/XCEngine.md) - 与 `engine/include/XCEngine` 平行的文档根目录 -- [_meta/rebuild-status.md](_meta/rebuild-status.md) - 当前覆盖率、链接检查和审计状态 +- [XCEngine/XCEngine.md](XCEngine/XCEngine.md) - 与 `engine/include/XCEngine/**` 并行的引擎运行时 API 根目录 +- [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 文档 | 对应源码目录 | |------|----------------|--------------| -| `Audio` | [XCEngine/Audio/Audio.md](XCEngine/Audio/Audio.md) | `XCEngine/Audio/` | -| `Components` | [XCEngine/Components/Components.md](XCEngine/Components/Components.md) | `XCEngine/Components/` | -| `Core` | [XCEngine/Core/Core.md](XCEngine/Core/Core.md) | `XCEngine/Core/` | -| `Debug` | [XCEngine/Debug/Debug.md](XCEngine/Debug/Debug.md) | `XCEngine/Debug/` | -| `Editor` | [XCEngine/Editor/Editor.md](XCEngine/Editor/Editor.md) | `editor/src/` | -| `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/` | +| `Collections` | [XCEditor/Collections/Collections.md](XCEditor/Collections/Collections.md) | `new_editor/include/XCEditor/Collections/` | +| `Fields` | [XCEditor/Fields/Fields.md](XCEditor/Fields/Fields.md) | `new_editor/include/XCEditor/Fields/` | +| `Foundation` | [XCEditor/Foundation/Foundation.md](XCEditor/Foundation/Foundation.md) | `new_editor/include/XCEditor/Foundation/` | +| `Shell` | [XCEditor/Shell/Shell.md](XCEditor/Shell/Shell.md) | `new_editor/include/XCEditor/Shell/` | +| `Widgets` | [XCEditor/Widgets/Widgets.md](XCEditor/Widgets/Widgets.md) | `new_editor/include/XCEditor/Widgets/` | ## 相关文档 -- [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) -- [XCEngine 架构设计](../used/XCEngine渲染引擎架构设计.md)