refactor(docs): fix Resources module links and add new ResourceManager/ResourceHandle docs

2026-03-26 01:57:22 +08:00
parent 56ee358b5c
commit 52d5e98f62
7 changed files with 377 additions and 10 deletions
--- a/docs/api/resources/asyncloader/asyncloader.md
+++ b/docs/api/resources/asyncloader/asyncloader.md
@@ -116,6 +116,6 @@ AsyncLoader::Get().Shutdown();

 ## 相关文档

- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
 - [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
 - [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/dependencygraph/dependencygraph.md
+++ b/docs/api/resources/dependencygraph/dependencygraph.md
@@ -85,6 +85,6 @@ graph.DecrementRefCount(guid);

 ## 相关文档

- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
+- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
+- [ResourceHandle](../resourcehandle.md) - 资源句柄
 - [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/importsettings/importsettings.md
+++ b/docs/api/resources/importsettings/importsettings.md
@@ -169,5 +169,5 @@ ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx", &mesh
 ## 相关文档

 - [IResourceLoader](../iloader/iloader.md) - 资源加载器
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
 - [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/resource-manager/resource-manager.md
+++ b/docs/api/resources/resource-manager/resource-manager.md
@@ -0,0 +1,166 @@
+# ResourceManager
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (singleton)
+
+**头文件**: `XCEngine/Core/Asset/ResourceManager.h`
+
+**描述**: 资源管理器单例，负责资源的注册、加载、缓存和生命周期管理。
+
+## 概述
+
+`ResourceManager` 是 XCEngine 资源管理系统的核心单例类。它管理所有资源加载器，维护资源缓存，处理资源的引用计数，并提供同步和异步加载接口。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static ResourceManager& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | 初始化资源管理器 |
+| `void Shutdown()` | 关闭资源管理器，释放所有资源 |
+
+### 资源根路径
+
+| 方法 | 描述 |
+|------|------|
+| `void SetResourceRoot(const Containers::String& rootPath)` | 设置资源根目录 |
+| `const Containers::String& GetResourceRoot() const` | 获取资源根目录 |
+
+### 同步加载
+
+| 方法 | 描述 |
+|------|------|
+| `template<typename T> 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 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` | 获取资源引用计数 |
+
+### 加载器管理
+
+| 方法 | 描述 |
+|------|------|
+| `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()` | 刷新缓存 |
+
+### 资源查询
+
+| 方法 | 描述 |
+|------|------|
+| `IResource* Find(const Containers::String& path)` | 通过路径查找资源 |
+| `IResource* Find(ResourceGUID guid)` | 通过 GUID 查找资源 |
+| `bool Exists(const Containers::String& path) const` | 检查资源是否存在 |
+| `bool Exists(ResourceGUID guid) const` | 检查资源是否存在 |
+
+### 路径解析
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 解析相对路径为绝对路径 |
+
+### 组加载
+
+| 方法 | 描述 |
+|------|------|
+| `template<typename T> void LoadGroup(const Containers::Array<Containers::String>& paths, std::function<void(ResourceHandle<T>)> callback)` | 批量异步加载同类型资源 |
+
+### 资源路径
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<Containers::String> GetResourcePaths() const` | 获取所有已加载资源的路径 |
+| `void UnloadGroup(const Containers::Array<ResourceGUID>& guids)` | 批量卸载资源 |
+
+## 实现说明
+
+**注意**: `LoadGroup()` 方法通过多次调用 `LoadAsync()` 实现批量加载，所有加载请求会被提交到 `AsyncLoader` 的队列中。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Asset/ResourceManager.h>
+
+// 获取单例实例
+ResourceManager& resMgr = ResourceManager::Get();
+
+// 初始化
+resMgr.Initialize();
+resMgr.SetResourceRoot("resources/");
+
+// 同步加载资源
+ResourceHandle<Texture> tex = resMgr.Load<Texture>("textures/player.png");
+ResourceHandle<Mesh> mesh = resMgr.Load<Mesh>("models/player.fbx");
+ResourceHandle<Material> mat = resMgr.Load<Material>("materials/player.mat");
+
+// 检查加载结果
+if (tex.IsValid()) {
+    // 使用纹理
+}
+
+// 异步加载
+resMgr.LoadAsync("textures/terrain.png", ResourceType::Texture,
+    [](LoadResult result) {
+        if (result.success) {
+            ResourceHandle<Texture> tex(result.resource);
+            // 处理加载完成的纹理
+        }
+    });
+
+// 引用计数
+ResourceGUID guid = tex.GetGUID();
+resMgr.AddRef(guid);
+// ... 使用资源 ...
+resMgr.Release(guid);
+
+// 卸载
+resMgr.UnloadUnused();
+
+// 关闭
+resMgr.Shutdown();
+```
+
+## 相关文档
+
+- [IResourceLoader](iloader/iloader.md) - 资源加载器接口
+- [AsyncLoader](asyncloader/asyncloader.md) - 异步加载器
+- [ResourceCache](resourcecache.md) - 资源缓存
+- [ResourceHandle](resourcehandle.md) - 资源句柄
+- [Resources 总览](resources.md) - 返回模块总览
--- a/docs/api/resources/resourcecache.md
+++ b/docs/api/resources/resourcecache.md
@@ -0,0 +1,88 @@
+# ResourceCache
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Core/Asset/ResourceCache.h`
+
+**描述**: 资源缓存管理器，实现 LRU（最近最少使用）淘汰策略的资源缓存。
+
+## 概述
+
+`ResourceCache` 维护了一个内存资源缓存，使用 LRU 策略管理资源条目。当内存使用超过预算时，会自动淘汰最近最少使用的资源。
+
+## 公共方法
+
+### 缓存操作
+
+| 方法 | 描述 |
+|------|------|
+| `void Add(ResourceGUID guid, IResource* resource)` | 添加资源到缓存 |
+| `void Remove(ResourceGUID guid)` | 从缓存移除资源 |
+| `IResource* Find(ResourceGUID guid) const` | 查找缓存中的资源 |
+| `void Touch(ResourceGUID guid)` | 更新资源的访问时间 |
+
+### 缓存信息
+
+| 方法 | 描述 |
+|------|------|
+| `size_t GetSize() const` | 获取缓存条目数量 |
+| `size_t GetMemoryUsage() const` | 获取缓存内存使用量（字节） |
+
+### 内存管理
+
+| 方法 | 描述 |
+|------|------|
+| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 |
+| `size_t GetMemoryBudget() const` | 获取内存预算 |
+| `void OnMemoryPressure(size_t requiredBytes)` | 内存压力回调，淘汰资源释放内存 |
+| `void OnZeroRefCount(ResourceGUID guid)` | 引用计数归零时的回调 |
+
+### 缓存刷新
+
+| 方法 | 描述 |
+|------|------|
+| `void Flush()` | 刷新所有缓存资源 |
+| `void Clear()` | 清空缓存 |
+
+### LRU 操作
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<ResourceGUID> GetLRUList(size_t count) const` | 获取最近最少使用的资源 GUID 列表 |
+
+## 实现说明
+
+**LRU 策略**: 缓存使用 LRU（Least Recently Used）策略淘汰资源。当 `OnMemoryPressure()` 被调用时，会从最近最少使用的资源开始淘汰，直到释放足够的内存。
+
+**线程安全**: 缓存操作通过互斥锁保护，部分只读操作使用读锁以提高并发性能。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Asset/ResourceCache.h>
+
+using namespace XCEngine::Resources;
+
+// 获取缓存实例（ResourceManager 内部使用）
+ResourceCache& cache = /* ... */;
+
+// 设置内存预算 256MB
+cache.SetMemoryBudget(256 * 1024 * 1024);
+
+// 手动触发内存压力释放
+cache.OnMemoryPressure(50 * 1024 * 1024); // 释放 50MB
+
+// 获取 LRU 列表
+auto lruItems = cache.GetLRUList(10);
+for (const auto& guid : lruItems) {
+    // 处理每个 LRU 条目
+}
+```
+
+## 相关文档
+
+- [ResourceManager](resource-manager/resource-manager.md) - 资源管理器
+- [IResource](iresource/iresource.md) - 资源基类
+- [Resources 总览](resources.md) - 返回模块总览
--- a/docs/api/resources/resourcehandle.md
+++ b/docs/api/resources/resourcehandle.md
@@ -0,0 +1,113 @@
+# ResourceHandle
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class template`
+
+**头文件**: `XCEngine/Core/Asset/ResourceHandle.h`
+
+**模板参数**: `T` - 资源类型，必须继承自 `IResource`
+
+**描述**: 资源句柄模板类，提供资源的类型安全引用和自动引用计数管理。
+
+## 概述
+
+`ResourceHandle` 是一个模板智能指针类，用于安全引用 `IResource` 子类实例。它自动管理引用计数，当句柄被销毁或重置时，相应的资源引用计数会递减。这确保了资源在其被所有句柄释放前不会被卸载。
+
+## 公共方法
+
+### 构造与赋值
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle()` | 默认构造，创建空句柄 |
+| `explicit ResourceHandle(T* resource)` | 从原始指针构造，增加引用计数 |
+| `ResourceHandle(const ResourceHandle& other)` | 拷贝构造，增加引用计数 |
+| `ResourceHandle(ResourceHandle&& other) noexcept` | 移动构造，不增加引用计数 |
+| `ResourceHandle& operator=(const ResourceHandle& other)` | 拷贝赋值，先释放当前引用再增加新引用 |
+| `ResourceHandle& operator=(ResourceHandle&& other) noexcept` | 移动赋值 |
+
+### 资源访问
+
+| 方法 | 描述 |
+|------|------|
+| `T* Get() const` | 获取原始指针 |
+| `T* operator->() const` | 通过箭头操作符访问资源方法 |
+| `T& operator*() const` | 解引用获取资源引用 |
+
+### 状态查询
+
+| 方法 | 描述 |
+|------|------|
+| `bool IsValid() const` | 检查句柄是否有效（非空且资源有效） |
+| `explicit operator bool() const` | 隐式转换为 bool |
+
+### GUID 与类型
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceGUID GetGUID() const` | 获取资源的全局唯一标识符 |
+| `ResourceType GetResourceType() const` | 获取资源类型 |
+
+### 句柄操作
+
+| 方法 | 描述 |
+|------|------|
+| `void Reset()` | 释放当前引用，将句柄置为空 |
+| `void Swap(ResourceHandle& other)` | 交换两个句柄的引用 |
+
+## 操作符重载
+
+| 操作符 | 描述 |
+|------|------|
+| `template<typename T> bool operator==(const ResourceHandle<T>& lhs, const ResourceHandle<T>& rhs)` | 判断两个句柄是否引用同一资源 |
+| `template<typename T> bool operator!=(const ResourceHandle<T>& lhs, const ResourceHandle<T>& rhs)` | 判断两个句柄是否引用不同资源 |
+
+## 实现说明
+
+**引用计数**: 每次构造（拷贝或原始指针）或赋值操作都会调用 `ResourceManager::AddRef()` 增加引用计数。每次析构或 `Reset()` 调用都会调用 `ResourceManager::Release()` 减少引用计数。
+
+**线程安全**: 引用计数操作在 `ResourceManager` 内部通过互斥锁保护。
+
+**空句柄处理**: 对空句柄调用 `GetGUID()` 返回 `ResourceGUID(0)`，调用 `GetResourceType()` 返回 `ResourceType::Unknown`。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Asset/ResourceHandle.h>
+#include <XCEngine/Resources/Texture.h>
+
+using namespace XCEngine::Resources;
+
+// 创建句柄（从加载结果）
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+
+// 检查有效性
+if (tex.IsValid()) {
+    // 使用箭头操作符访问资源方法
+    const Containers::String& path = tex->GetPath();
+}
+
+// 拷贝构造（引用计数 +1）
+ResourceHandle<Texture> tex2 = tex;
+
+// 移动构造（引用计数不变）
+ResourceHandle<Texture> tex3 = std::move(tex2);
+
+// 句柄失效，引用计数 -1
+tex.Reset();
+
+// 比较操作
+ResourceHandle<Texture> texA = ResourceManager::Get().Load<Texture>("a.png");
+ResourceHandle<Texture> texB = ResourceManager::Get().Load<Texture>("b.png");
+
+if (texA == texB) {
+    // 同一资源
+}
+```
+
+## 相关文档
+
+- [IResource](iresource/iresource.md) - 资源基类
+- [ResourceManager](resource-manager/resource-manager.md) - 资源管理器
+- [Resources 总览](resources.md) - 返回模块总览
--- a/docs/api/resources/texture-loader/index.md
+++ b/docs/api/resources/texture-loader/index.md
@@ -36,11 +36,11 @@
 |------|------|
 | [TextureLoader](constructor.md) | 构造函数 |
 | [~TextureLoader](destructor.md) | 析构函数 |
-| [GetResourceType](../shader-loader/methods/get-resource-type.md) | 返回 `ResourceType::Texture` |
-| [GetSupportedExtensions](../audio-loader/get-supported-extensions.md) | 获取支持的扩展名列表 |
-| [CanLoad](../audio-loader/can-load.md) | 检查是否支持加载指定路径的纹理 |
-| [Load](../../scene/scene/load.md) | 加载纹理资源 |
-| [GetDefaultSettings](../audio-loader/get-default-settings.md) | 获取默认导入设置 |
+| `GetResourceType()` | 返回 `ResourceType::Texture` |
+| `GetSupportedExtensions()` | 获取支持的扩展名列表 |
+| `CanLoad()` | 检查是否支持加载指定路径的纹理 |
+| `Load()` | 加载纹理资源 |
+| `GetDefaultSettings()` | 获取默认导入设置 |

 ### GetResourceType

@@ -133,7 +133,7 @@ if (loader.CanLoad("assets/image.dds")) {

 - [Texture](../texture/texture.md) - 纹理资源类
 - [IResourceLoader](../iloader/iloader.md) - 资源加载器基类
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
 - [Resources 总览](../resources.md) - 返回模块总览

 ## 实现说明