refactor: reorganize docs into plan/ and add skills/
This commit is contained in:
166
docs/api/resources/resources-resourcemanager.md
Normal file
166
docs/api/resources/resources-resourcemanager.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# 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 批量卸载 |
|
||||
|
||||
## 私有方法（内部使用）
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `IResource* FindInCache(ResourceGUID guid)` | 在缓存中查找资源 |
|
||||
| `void AddToCache(ResourceGUID guid, IResource* resource)` | 添加到缓存 |
|
||||
| `IResourceLoader* FindLoader(ResourceType type)` | 查找加载器 |
|
||||
| `void ReloadResource(ResourceGUID 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<Texture>("textures/terrain.png",
|
||||
[](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](./resources-iresource.md) - 资源基类
|
||||
- [ResourceHandle](./resources-resourcehandle.md) - 资源句柄
|
||||
- [ResourceCache](./resources-resourcecache.md) - 资源缓存
|
||||
- [AsyncLoader](./resources-asyncloader.md) - 异步加载器
|
||||
Reference in New Issue
Block a user