89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# ResourceFileSystem
|
|
|
|
## 命名空间
|
|
|
|
`XCEngine::Resources`
|
|
|
|
## 类型
|
|
|
|
| 类型 | 名称 | 描述 |
|
|
|------|------|------|
|
|
| class | `ResourceFileSystem` | 资源文件系统管理器 |
|
|
| class | `IArchive` | 档案压缩包接口 |
|
|
| struct | `ResourceInfo` | 资源信息结构 |
|
|
|
|
## 概述
|
|
|
|
`ResourceFileSystem` 是 XCEngine 资源管理模块的核心组件，负责管理游戏资源的加载与访问。它支持从文件系统目录和档案压缩包（如 ZIP、Pak 等）中检索资源，并提供统一的资源访问接口。
|
|
|
|
该类采用单例模式，通过 `Get()` 静态方法获取全局实例。线程安全，通过内部互斥锁保护数据结构。
|
|
|
|
### 主要功能
|
|
|
|
- 支持多目录和多档案的资源来源
|
|
- 资源路径解析（相对路径 → 绝对路径）
|
|
- 资源读取（以字节数组形式返回）
|
|
- 资源存在性检查
|
|
- 资源元数据查询
|
|
- 资源枚举（支持通配符模式）
|
|
- 信息缓存以提高查询性能
|
|
|
|
## 公共方法表格
|
|
|
|
| 方法 | 签名 | 描述 |
|
|
|------|------|------|
|
|
| `Initialize` | `void Initialize(const Containers::String& rootPath)` | 初始化资源文件系统，设置根路径 |
|
|
| `Shutdown` | `void Shutdown()` | 关闭文件系统，释放所有资源 |
|
|
| `AddArchive` | `bool AddArchive(const Containers::String& archivePath)` | 添加档案压缩包作为资源来源 |
|
|
| `AddDirectory` | `bool AddDirectory(const Containers::String& directoryPath)` | 添加目录作为资源来源 |
|
|
| `RemoveArchive` | `void RemoveArchive(const Containers::String& archivePath)` | 移除指定的档案压缩包 |
|
|
| `FindResource` | `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源并返回绝对路径 |
|
|
| `ReadResource` | `Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const` | 读取资源数据 |
|
|
| `Exists` | `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 |
|
|
| `GetResourceInfo` | `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源详细信息 |
|
|
| `EnumerateResources` | `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配模式的资源 |
|
|
| `Get` | `static ResourceFileSystem& Get()` | 获取单例实例 |
|
|
|
|
## 使用示例
|
|
|
|
```cpp
|
|
#include "Resources/ResourceFileSystem.h"
|
|
|
|
using namespace XCEngine;
|
|
using namespace XCEngine::Resources;
|
|
|
|
// 初始化资源文件系统
|
|
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
|
fs.Initialize("C:/Game/Resources");
|
|
|
|
// 添加资源来源
|
|
fs.AddDirectory("C:/Game/Assets/Textures");
|
|
fs.AddArchive("C:/Game/Paks/Common.pak");
|
|
|
|
// 读取资源
|
|
Containers::Array<Core::uint8> data = fs.ReadResource("textures/player/diffuse.png");
|
|
if (data.Size() > 0) {
|
|
// 处理资源数据
|
|
}
|
|
|
|
// 检查资源是否存在
|
|
if (fs.Exists("shaders/forward.glsl")) {
|
|
// 加载着色器
|
|
}
|
|
|
|
// 获取资源信息
|
|
ResourceInfo info;
|
|
if (fs.GetResourceInfo("audio/bgm/main_theme.ogg", info)) {
|
|
printf("Resource size: %zu\n", info.size);
|
|
}
|
|
|
|
// 枚举资源
|
|
Containers::Array<ResourceInfo> resources;
|
|
fs.EnumerateResources("textures/**/*.png", resources);
|
|
```
|
|
|
|
## 相关文档
|
|
|
|
- [IArchive 接口](iarchive.md)
|
|
- [ResourceInfo 结构](resource-info.md)
|