fix: improve doc link navigation and tree display

- Fix link resolution with proper relative/absolute path handling - Improve link styling with underline decoration - Hide leaf nodes from tree, only show directories - Fix log file path for packaged app
2026-03-19 12:44:08 +08:00
parent e003fe6513
commit 58a83f445a
1012 changed files with 56880 additions and 22 deletions
--- a/docs/api/resources/resourcemanager/exists.md
+++ b/docs/api/resources/resourcemanager/exists.md
@@ -0,0 +1,28 @@
+# ResourceManager::Exists
+
+```cpp
+bool Exists(const Containers::String& path) const
+bool Exists(ResourceGUID guid) const
+```
+
+检查资源是否已加载。
+
+**参数：**
+- `path` - 资源路径
+- `guid` - 资源全局唯一标识符
+
+**返回：** 如果资源在缓存中则返回 true
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+if (ResourceManager::Get().Exists("textures/player.png")) {
+    auto tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+}
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/find.md
+++ b/docs/api/resources/resourcemanager/find.md
@@ -0,0 +1,29 @@
+# ResourceManager::Find
+
+```cpp
+IResource* Find(const Containers::String& path)
+IResource* Find(ResourceGUID guid)
+```
+
+在资源缓存中查找资源。返回裸指针，不增加引用计数。
+
+**参数：**
+- `path` - 资源路径
+- `guid` - 资源全局唯一标识符
+
+**返回：** 找到则返回资源指针，否则返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+IResource* res = ResourceManager::Get().Find("textures/player.png");
+if (res && res->IsValid()) {
+    Texture* tex = static_cast<Texture*>(res);
+}
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/getloader.md
+++ b/docs/api/resources/resourcemanager/getloader.md
@@ -0,0 +1,27 @@
+# ResourceManager::GetLoader
+
+```cpp
+IResourceLoader* GetLoader(ResourceType type) const
+```
+
+获取指定类型的资源加载器。
+
+**参数：**
+- `type` - 资源类型
+
+**返回：** 对应的加载器指针，未找到则返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+IResourceLoader* texLoader = ResourceManager::Get().GetLoader(ResourceType::Texture);
+if (texLoader) {
+    auto extensions = texLoader->GetSupportedExtensions();
+}
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/load.md
+++ b/docs/api/resources/resourcemanager/load.md
@@ -0,0 +1,32 @@
+# ResourceManager::Load
+
+```cpp
+template<typename T>
+ResourceHandle<T> Load(const Containers::String& path, ImportSettings* settings = nullptr)
+```
+
+同步加载资源。模板方法，根据路径生成 GUID，先在缓存中查找是否已加载；若未加载则查找对应类型的加载器并同步加载，然后将结果加入缓存。
+
+**参数：**
+- `path` - 资源路径
+- `settings` - 导入设置（可选）
+
+**返回：** `ResourceHandle<T>`，持有加载的资源
+
+**复杂度：** O(n)，取决于加载器实现
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
+
+if (tex.IsValid()) {
+    // 使用纹理...
+}
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/loadasync.md
+++ b/docs/api/resources/resourcemanager/loadasync.md
@@ -0,0 +1,44 @@
+# ResourceManager::LoadAsync
+
+```cpp
+void LoadAsync(const Containers::String& path, ResourceType type,
+               std::function<void(LoadResult)> callback)
+void LoadAsync(const Containers::String& path, ResourceType type,
+               ImportSettings* settings, std::function<void(LoadResult)> callback)
+```
+
+异步加载资源。将加载请求提交到 `AsyncLoader`，在后台工作线程执行加载，完成后在主线程通过回调通知。
+
+**参数：**
+- `path` - 资源路径
+- `type` - 资源类型
+- `settings` - 导入设置（可为 nullptr）
+- `callback` - 加载完成回调
+
+**返回：** 无
+
+**复杂度：** 提交 O(1)，实际加载 O(n)
+
+**示例：**
+
+```cpp
+ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            printf("Loaded: %s\n", tex->GetPath().CStr());
+        }
+    });
+
+ResourceManager::Get().LoadAsync("models/player.fbx", ResourceType::Mesh,
+    nullptr,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Mesh> mesh(result.resource);
+        }
+    });
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/loadgroup.md
+++ b/docs/api/resources/resourcemanager/loadgroup.md
@@ -0,0 +1,35 @@
+# ResourceManager::LoadGroup
+
+```cpp
+template<typename T>
+void LoadGroup(const Containers::Array<Containers::String>& paths,
+               std::function<void(ResourceHandle<T>)> callback)
+```
+
+批量异步加载同类资源。为路径数组中的每个路径提交一个异步加载请求，所有加载完成时通过回调通知。
+
+**参数：**
+- `paths` - 资源路径数组
+- `callback` - 每个资源加载完成时的回调
+
+**返回：** 无
+
+**复杂度：** O(k)，k 为路径数量（每个加载为 O(n)）
+
+**示例：**
+
+```cpp
+Containers::Array<Containers::String> texPaths = {
+    "textures/a.png", "textures/b.png", "textures/c.png"
+};
+ResourceManager::Get().LoadGroup<Texture>(texPaths,
+    [](ResourceHandle<Texture> tex) {
+        if (tex.IsValid()) {
+            printf("Loaded: %s\n", tex->GetPath().CStr());
+        }
+    });
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/registerloader.md
+++ b/docs/api/resources/resourcemanager/registerloader.md
@@ -0,0 +1,26 @@
+# ResourceManager::RegisterLoader
+
+```cpp
+void RegisterLoader(IResourceLoader* loader)
+```
+
+注册资源加载器。管理器持有加载器指针所有权。
+
+**参数：**
+- `loader` - 加载器实例指针
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceManager::Get().RegisterLoader(new TextureLoader());
+ResourceManager::Get().RegisterLoader(new MeshLoader());
+ResourceManager::Get().RegisterLoader(new MaterialLoader());
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/resourcemanager.md
+++ b/docs/api/resources/resourcemanager/resourcemanager.md
@@ -0,0 +1,101 @@
+# ResourceManager
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (singleton)
+
+**描述**: 资源管理器单例，负责资源的加载、缓存、引用计数管理和异步加载调度。
+
+## 概述
+
+`ResourceManager` 是 XCEngine 资源管理系统的核心单例类。它提供统一的资源加载接口、自动缓存管理、引用计数跟踪和异步加载支持。所有资源访问都应通过 `ResourceManager` 进行。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static ResourceManager& Get()` | 获取单例实例 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | 初始化资源管理器 |
+| `void Shutdown()` | 关闭资源管理器，卸载所有资源 |
+| `void SetResourceRoot(const Containers::String& rootPath)` | 设置资源根目录 |
+| `const Containers::String& GetResourceRoot() const` | 获取资源根目录 |
+| `ResourceHandle<T> Load(const Containers::String& path, ImportSettings* settings = nullptr)` | 同步加载资源（模板方法） |
+| `void LoadAsync(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 异步加载资源 |
+| `void LoadAsync(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载 |
+| `void LoadGroup(const Containers::Array<Containers::String>& paths, std::function<void(ResourceHandle<T>)> callback)` | 批量异步加载同类资源 |
+| `void Unload(const Containers::String& path)` | 按路径卸载资源 |
+| `void Unload(ResourceGUID guid)` | 按 GUID 卸载资源 |
+| `void UnloadUnused()` | 卸载所有无引用的资源 |
+| `void UnloadAll()` | 卸载所有资源 |
+| `void AddRef(ResourceGUID guid)` | 增加引用计数（内部使用） |
+| `void Release(ResourceGUID guid)` | 减少引用计数（内部使用） |
+| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 |
+| `IResource* Find(const Containers::String& path)` | 按路径查找资源 |
+| `IResource* Find(ResourceGUID guid)` | 按 GUID 查找资源 |
+| `bool Exists(const Containers::String& path) const` | 检查资源是否存在 |
+| `bool Exists(ResourceGUID guid) const` | 检查 GUID 对应资源是否存在 |
+| `void RegisterLoader(IResourceLoader* loader)` | 注册资源加载器 |
+| `void UnregisterLoader(ResourceType type)` | 注销加载器 |
+| `IResourceLoader* GetLoader(ResourceType type) const` | 获取指定类型的加载器 |
+| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 |
+| `size_t GetMemoryUsage() const` | 获取当前内存使用量 |
+| `size_t GetMemoryBudget() const` | 获取内存预算 |
+| `void FlushCache()` | 清空缓存 |
+| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 将相对路径解析为绝对路径 |
+| `Containers::Array<Containers::String> GetResourcePaths() const` | 获取所有已加载资源的路径列表 |
+| `void UnloadGroup(const Containers::Array<ResourceGUID>& guids)` | 按 GUID 批量卸载 |
+
+## 实现说明
+
+```cpp
+// 初始化
+ResourceManager::Get().Initialize();
+ResourceManager::Get().SetResourceRoot("resources/");
+
+// 注册加载器
+ResourceManager::Get().RegisterLoader(new TextureLoader());
+ResourceManager::Get().RegisterLoader(new MeshLoader());
+ResourceManager::Get().RegisterLoader(new MaterialLoader());
+
+// 同步加载
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
+
+// 异步加载
+ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            // 使用纹理...
+        }
+    });
+
+// 批量加载
+Containers::Array<Containers::String> paths = {"a.png", "b.png", "c.png"};
+ResourceManager::Get().LoadGroup<Texture>(paths,
+    [](ResourceHandle<Texture> tex) {
+        if (tex.IsValid()) {
+            // 处理加载完成的纹理...
+        }
+    });
+
+// 设置内存预算
+ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024);  // 1GB
+
+// 卸载
+ResourceManager::Get().UnloadUnused();
+ResourceManager::Get().Shutdown();
+```
+
+## 相关文档
+
+- [IResource](../iresource/iresource.md) - 资源基类
+- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
+- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存
+- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器
+- [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/resourcemanager/setmemorybudget.md
+++ b/docs/api/resources/resourcemanager/setmemorybudget.md
@@ -0,0 +1,24 @@
+# ResourceManager::SetMemoryBudget
+
+```cpp
+void SetMemoryBudget(size_t bytes)
+```
+
+设置资源管理的内存预算上限。当缓存中资源的总内存占用超过预算时，会触发 LRU 驱逐策略释放内存。
+
+**参数：**
+- `bytes` - 内存预算大小（字节）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024);  // 1GB 预算
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/unload.md
+++ b/docs/api/resources/resourcemanager/unload.md
@@ -0,0 +1,31 @@
+# ResourceManager::Unload
+
+```cpp
+void Unload(const Containers::String& path)
+void Unload(ResourceGUID guid)
+```
+
+卸载指定资源。按路径或 GUID 查找资源，如果引用计数降至零则释放资源内存。
+
+**参数：**
+- `path` - 资源路径
+- `guid` - 资源全局唯一标识符
+
+**返回：** 无
+
+**复杂度：** O(1) 查找
+
+**示例：**
+
+```cpp
+// 按路径卸载
+ResourceManager::Get().Unload("textures/player.png");
+
+// 按 GUID 卸载
+ResourceGUID guid = tex.GetGUID();
+ResourceManager::Get().Unload(guid);
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览
--- a/docs/api/resources/resourcemanager/unloadunused.md
+++ b/docs/api/resources/resourcemanager/unloadunused.md
@@ -0,0 +1,26 @@
+# ResourceManager::UnloadUnused
+
+```cpp
+void UnloadUnused()
+```
+
+卸载所有无引用的资源。遍历资源缓存，将引用计数为零的资源全部释放。常在场景切换或内存紧张时调用。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+// 切换场景时清理无用资源
+void OnSceneUnload() {
+    ResourceManager::Get().UnloadUnused();
+}
+```
+
+## 相关文档
+
+- [ResourceManager 总览](resourcemanager.md) - 返回类总览