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/iloader/iloader.md
+++ b/docs/api/resources/iloader/iloader.md
@@ -0,0 +1,115 @@
+# IResourceLoader
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (abstract)
+
+**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。
+
+## 概述
+
+`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。
+
+## LoadResult 结构体
+
+加载操作的返回值结构体。
+
+```cpp
+struct LoadResult {
+    IResource* resource = nullptr;
+    bool success = false;
+    Containers::String errorMessage;
+    LoadResult() = default;
+    explicit LoadResult(IResource* res) : resource(res), success(res != nullptr) {}
+    explicit LoadResult(const Containers::String& error) : success(false), errorMessage(error) {}
+    explicit LoadResult(bool inSuccess, const Containers::String& error = "")
+        : success(inSuccess), errorMessage(error) {}
+    operator bool() const { return success && resource != nullptr; }
+};
+```
+
+## 公共方法
+
+### 资源信息
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 |
+| `Containers::Array<Containers::String> GetSupportedExtensions() const` | 获取支持的文件扩展名列表 |
+| `bool CanLoad(const Containers::String& path) const` | 检查此加载器是否能加载指定路径 |
+| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 |
+
+### 同步加载
+
+| 方法 | 描述 |
+|------|------|
+| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 同步加载资源 |
+
+### 异步加载
+
+| 方法 | 描述 |
+|------|------|
+| `void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function<void(LoadResult)> callback)` | 异步加载资源（内部默认实现调用同步 Load） |
+
+### 辅助方法（受保护）
+
+| 方法 | 描述 |
+|------|------|
+| `static Containers::Array<Core::uint8> ReadFileData(const Containers::String& path)` | 读取文件数据 |
+| `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 |
+
+## 宏
+
+### REGISTER_RESOURCE_LOADER
+
+自动注册加载器到 ResourceManager 的宏。
+
+```cpp
+REGISTER_RESOURCE_LOADER(TextureLoader)
+```
+
+## 使用示例
+
+```cpp
+class TextureLoader : public IResourceLoader {
+public:
+    ResourceType GetResourceType() const override {
+        return ResourceType::Texture;
+    }
+    
+    Containers::Array<Containers::String> GetSupportedExtensions() const override {
+        return {".png", ".jpg", ".jpeg", ".bmp", ".tga"};
+    }
+    
+    bool CanLoad(const Containers::String& path) const override {
+        Containers::String ext = GetExtension(path);
+        return ext == ".png" || ext == ".jpg" || ext == ".bmp";
+    }
+    
+    ImportSettings* GetDefaultSettings() const override {
+        return new TextureImportSettings();
+    }
+    
+    LoadResult Load(const Containers::String& path,
+                    const ImportSettings* settings = nullptr) override {
+        LoadResult result;
+        auto data = ReadFileData(path);
+        if (data.Empty()) {
+            return LoadResult("Failed to read file: " + path);
+        }
+        result.resource = new Texture();
+        result.success = true;
+        return result;
+    }
+};
+
+// 注册加载器
+ResourceManager::Get().RegisterLoader(new TextureLoader());
+```
+
+## 相关文档
+
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器
+- [ImportSettings](../importsettings/importsettings.md) - 导入设置
+- [Resources 总览](../resources.md) - 返回模块总览