Files

ssdfasd dc850d7739 docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录
- 重命名 index.md 为 main.md
- 修正所有模块文档中的错误:
  - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式
  - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节
  - core: 修复 types 链接错误
  - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI
  - memory: 修复头文件路径, malloc vs operator new, 新增方法文档
  - resources: 修复 Shader/Texture 链接错误
  - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接
- 验证: fix_links.py 确认 0 个断裂引用

2026-03-19 00:22:30 +08:00

5.1 KiB

Raw Blame History

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 批量卸载

使用示例

// 初始化
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();

5.1 KiB Raw Blame History