167 lines
5.0 KiB
Markdown
167 lines
5.0 KiB
Markdown
# 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) - 返回模块总览
|