docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
--- a/docs/api/resources/asyncloader/asyncloader.md
+++ b/docs/api/resources/asyncloader/asyncloader.md
@@ -0,0 +1,116 @@
+# AsyncLoader
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (singleton)
+
+**描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。
+
+## 概述
+
+`AsyncLoader` 是 XCEngine 的后台异步加载系统。它使用独立工作线程从磁盘加载资源，并在加载完成后通过回调通知调用者。它维护待处理队列和完成队列，通过双缓冲机制实现无锁的线程安全操作。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static AsyncLoader& Get()` | 获取单例实例 |
+
+## LoadRequest 结构体
+
+异步加载请求结构体。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `path` | `Containers::String` | 资源路径 |
+| `type` | `ResourceType` | 资源类型 |
+| `callback` | `std::function<void(LoadResult)>` | 加载完成回调函数 |
+| `settings` | `ImportSettings*` | 导入设置（可为 nullptr） |
+| `requestId` | `Core::uint64` | 请求唯一标识符 |
+
+### 构造方法
+
+| 方法 | 描述 |
+|------|------|
+| `LoadRequest()` | 默认构造 |
+| `LoadRequest(const Containers::String& p, ResourceType t, std::function<void(LoadResult)> cb, ImportSettings* s = nullptr)` | 从参数构造 |
+| `LoadRequest(LoadRequest&& other) noexcept` | 移动构造 |
+| `LoadRequest(const LoadRequest&) = default` | 拷贝构造 |
+
+### 赋值
+
+| 方法 | 描述 |
+|------|------|
+| `LoadRequest& operator=(LoadRequest&& other) noexcept` | 移动赋值 |
+| `LoadRequest& operator=(const LoadRequest&) = default` | 拷贝赋值 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize(Core::uint32 workerThreadCount = 2)` | 初始化异步加载器，创建工作线程 |
+| `void Shutdown()` | 关闭异步加载器，等待所有挂起任务完成 |
+
+### 提交请求
+
+| 方法 | 描述 |
+|------|------|
+| `void Submit(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 提交异步加载请求 |
+| `void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载请求 |
+
+### 进度查询
+
+| 方法 | 描述 |
+|------|------|
+| `void Update()` | 更新函数，在主线程调用，处理完成的加载请求 |
+| `bool IsLoading() const` | 是否有正在加载的资源 |
+| `Core::uint32 GetPendingCount() const` | 获取待处理加载请求数量 |
+| `float GetProgress() const` | 获取整体加载进度（0.0f ~ 1.0f） |
+
+### 取消操作
+
+| 方法 | 描述 |
+|------|------|
+| `void CancelAll()` | 取消所有待处理的加载请求 |
+| `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 |
+
+## 使用示例
+
+```cpp
+// 初始化（使用 4 个工作线程）
+AsyncLoader::Get().Initialize(4);
+
+// 提交多个异步加载请求
+AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            printf("Texture loaded: %s\n", tex->GetPath().CStr());
+        }
+    });
+
+AsyncLoader::Get().Submit("models/player.fbx", ResourceType::Mesh,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Mesh> mesh(result.resource);
+            printf("Mesh loaded: %s\n", mesh->GetPath().CStr());
+        }
+    });
+
+// 在主循环中调用 Update 处理完成回调
+while (AsyncLoader::Get().IsLoading()) {
+    AsyncLoader::Get().Update();  // 在主线程分发回调
+    // 其他渲染逻辑...
+}
+
+// 关闭
+AsyncLoader::Get().Shutdown();
+```
+
+## 相关文档
+
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
+- [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/asyncloader/cancelall.md
+++ b/docs/api/resources/asyncloader/cancelall.md
@@ -0,0 +1,26 @@
+# AsyncLoader::CancelAll
+
+```cpp
+void CancelAll()
+```
+
+取消所有待处理的加载请求。清空待处理队列，不会触发任何回调。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+// 场景切换时取消所有加载请求
+void OnSceneChange() {
+    AsyncLoader::Get().CancelAll();
+}
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览
--- a/docs/api/resources/asyncloader/getprogress.md
+++ b/docs/api/resources/asyncloader/getprogress.md
@@ -0,0 +1,24 @@
+# AsyncLoader::GetProgress
+
+```cpp
+float GetProgress() const
+```
+
+获取整体加载进度。返回已完成加载数与总请求数的比值，范围 0.0f ~ 1.0f。
+
+**参数：** 无
+
+**返回：** 加载进度（0.0f ~ 1.0f）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+float progress = AsyncLoader::Get().GetProgress();
+printf("Loading: %.1f%%\n", progress * 100.0f);
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览
--- a/docs/api/resources/asyncloader/submit.md
+++ b/docs/api/resources/asyncloader/submit.md
@@ -0,0 +1,35 @@
+# AsyncLoader::Submit
+
+```cpp
+void Submit(const Containers::String& path, ResourceType type,
+            std::function<void(LoadResult)> callback)
+void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings,
+            std::function<void(LoadResult)> callback)
+```
+
+提交异步加载请求。将请求加入待处理队列，由工作线程在后台执行加载。
+
+**参数：**
+- `path` - 资源路径
+- `type` - 资源类型
+- `settings` - 导入设置（可为 nullptr）
+- `callback` - 加载完成回调
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+        }
+    });
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览
--- a/docs/api/resources/asyncloader/update.md
+++ b/docs/api/resources/asyncloader/update.md
@@ -0,0 +1,27 @@
+# AsyncLoader::Update
+
+```cpp
+void Update()
+```
+
+更新函数，在主线程调用。处理完成的加载请求，将结果从完成队列取出并在主线程执行回调。必须在主线程调用以确保线程安全。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为完成队列中的请求数
+
+**示例：**
+
+```cpp
+// 在主循环中调用
+while (running) {
+    AsyncLoader::Get().Update();  // 分发完成的加载回调
+    RenderFrame();
+}
+```
+
+## 相关文档
+
+- [AsyncLoader 总览](asyncloader.md) - 返回类总览