diff --git a/docs/api/resources/asyncloader/asyncloader.md b/docs/api/resources/asyncloader/asyncloader.md index abb28caf..a422deb3 100644 --- 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) - 返回模块总览 diff --git a/docs/api/resources/dependencygraph/dependencygraph.md b/docs/api/resources/dependencygraph/dependencygraph.md index 8bfcce8c..055ae329 100644 --- 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) - 返回模块总览 diff --git a/docs/api/resources/importsettings/importsettings.md b/docs/api/resources/importsettings/importsettings.md index 2c942e40..63a67b79 100644 --- a/docs/api/resources/importsettings/importsettings.md +++ b/docs/api/resources/importsettings/importsettings.md @@ -169,5 +169,5 @@ ResourceHandle mesh = ResourceManager::Get().Load("model.fbx", &mesh ## 相关文档 - [IResourceLoader](../iloader/iloader.md) - 资源加载器 -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器 - [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resource-manager/resource-manager.md b/docs/api/resources/resource-manager/resource-manager.md new file mode 100644 index 00000000..f31049ee --- /dev/null +++ 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 ResourceHandle Load(const Containers::String& path, ImportSettings* settings = nullptr)` | 同步加载资源 | + +### 异步加载 + +| 方法 | 描述 | +|------|------| +| `void LoadAsync(const Containers::String& path, ResourceType type, std::function callback)` | 异步加载资源 | +| `void LoadAsync(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function 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 void LoadGroup(const Containers::Array& paths, std::function)> callback)` | 批量异步加载同类型资源 | + +### 资源路径 + +| 方法 | 描述 | +|------|------| +| `Containers::Array GetResourcePaths() const` | 获取所有已加载资源的路径 | +| `void UnloadGroup(const Containers::Array& guids)` | 批量卸载资源 | + +## 实现说明 + +**注意**: `LoadGroup()` 方法通过多次调用 `LoadAsync()` 实现批量加载,所有加载请求会被提交到 `AsyncLoader` 的队列中。 + +## 使用示例 + +```cpp +#include + +// 获取单例实例 +ResourceManager& resMgr = ResourceManager::Get(); + +// 初始化 +resMgr.Initialize(); +resMgr.SetResourceRoot("resources/"); + +// 同步加载资源 +ResourceHandle tex = resMgr.Load("textures/player.png"); +ResourceHandle mesh = resMgr.Load("models/player.fbx"); +ResourceHandle mat = resMgr.Load("materials/player.mat"); + +// 检查加载结果 +if (tex.IsValid()) { + // 使用纹理 +} + +// 异步加载 +resMgr.LoadAsync("textures/terrain.png", ResourceType::Texture, + [](LoadResult result) { + if (result.success) { + ResourceHandle 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) - 返回模块总览 diff --git a/docs/api/resources/resourcecache.md b/docs/api/resources/resourcecache.md new file mode 100644 index 00000000..b3565da6 --- /dev/null +++ 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 GetLRUList(size_t count) const` | 获取最近最少使用的资源 GUID 列表 | + +## 实现说明 + +**LRU 策略**: 缓存使用 LRU(Least Recently Used)策略淘汰资源。当 `OnMemoryPressure()` 被调用时,会从最近最少使用的资源开始淘汰,直到释放足够的内存。 + +**线程安全**: 缓存操作通过互斥锁保护,部分只读操作使用读锁以提高并发性能。 + +## 使用示例 + +```cpp +#include + +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) - 返回模块总览 diff --git a/docs/api/resources/resourcehandle.md b/docs/api/resources/resourcehandle.md new file mode 100644 index 00000000..0a1a16ab --- /dev/null +++ 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 bool operator==(const ResourceHandle& lhs, const ResourceHandle& rhs)` | 判断两个句柄是否引用同一资源 | +| `template bool operator!=(const ResourceHandle& lhs, const ResourceHandle& rhs)` | 判断两个句柄是否引用不同资源 | + +## 实现说明 + +**引用计数**: 每次构造(拷贝或原始指针)或赋值操作都会调用 `ResourceManager::AddRef()` 增加引用计数。每次析构或 `Reset()` 调用都会调用 `ResourceManager::Release()` 减少引用计数。 + +**线程安全**: 引用计数操作在 `ResourceManager` 内部通过互斥锁保护。 + +**空句柄处理**: 对空句柄调用 `GetGUID()` 返回 `ResourceGUID(0)`,调用 `GetResourceType()` 返回 `ResourceType::Unknown`。 + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Resources; + +// 创建句柄(从加载结果) +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); + +// 检查有效性 +if (tex.IsValid()) { + // 使用箭头操作符访问资源方法 + const Containers::String& path = tex->GetPath(); +} + +// 拷贝构造(引用计数 +1) +ResourceHandle tex2 = tex; + +// 移动构造(引用计数不变) +ResourceHandle tex3 = std::move(tex2); + +// 句柄失效,引用计数 -1 +tex.Reset(); + +// 比较操作 +ResourceHandle texA = ResourceManager::Get().Load("a.png"); +ResourceHandle texB = ResourceManager::Get().Load("b.png"); + +if (texA == texB) { + // 同一资源 +} +``` + +## 相关文档 + +- [IResource](iresource/iresource.md) - 资源基类 +- [ResourceManager](resource-manager/resource-manager.md) - 资源管理器 +- [Resources 总览](resources.md) - 返回模块总览 diff --git a/docs/api/resources/texture-loader/index.md b/docs/api/resources/texture-loader/index.md index 7395defc..5006e52c 100644 --- 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) - 返回模块总览 ## 实现说明