105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
|
# ResourceFileSystem
|
|||
|
|
|
|||
|
|
**命名空间**: `XCEngine::Resources`
|
|||
|
|
|
|||
|
|
**类型**: `class`
|
|||
|
|
|
|||
|
|
**描述**: 资源文件系统，负责资源文件的查找、读取和虚拟文件系统（支持目录和归档包）管理。
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
`ResourceFileSystem` 实现了虚拟资源文件系统，支持从多个目录和归档包（如 `.zip`、`.pak`）中查找和读取资源。它通过 `IArchive` 接口支持不同的归档格式，并提供资源信息缓存。
|
|||
|
|
|
|||
|
|
## 单例访问
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| `static ResourceFileSystem& Get()` | 获取单例实例 |
|
|||
|
|
|
|||
|
|
## IArchive 接口
|
|||
|
|
|
|||
|
|
抽象归档接口，用于封装单个归档包或目录的读取操作。
|
|||
|
|
|
|||
|
|
### 公共方法
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| `virtual bool Open(const Containers::String& path)` | 打开归档 |
|
|||
|
|
| `virtual void Close()` | 关闭归档 |
|
|||
|
|
| `virtual bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const` | 从归档中读取文件 |
|
|||
|
|
| `virtual size_t GetSize(const Containers::String& fileName) const` | 获取文件大小 |
|
|||
|
|
| `virtual bool Exists(const Containers::String& fileName) const` | 检查文件是否存在 |
|
|||
|
|
| `virtual void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举匹配的文件 |
|
|||
|
|
| `virtual bool IsValid() const` | 是否有效 |
|
|||
|
|
|
|||
|
|
## ResourceInfo 结构体
|
|||
|
|
|
|||
|
|
| 成员 | 类型 | 描述 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `path` | `Containers::String` | 资源相对路径 |
|
|||
|
|
| `size` | `size_t` | 文件大小（字节） |
|
|||
|
|
| `modifiedTime` | `Core::uint64` | 修改时间戳 |
|
|||
|
|
| `inArchive` | `bool` | 是否在归档包中 |
|
|||
|
|
| `archivePath` | `Containers::String` | 所属归档路径 |
|
|||
|
|
|
|||
|
|
## 公共方法
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| `void Initialize(const Containers::String& rootPath)` | 初始化，设置资源根目录 |
|
|||
|
|
| `void Shutdown()` | 关闭，释放所有归档 |
|
|||
|
|
| `bool AddArchive(const Containers::String& archivePath)` | 添加归档包（优先查找） |
|
|||
|
|
| `bool AddDirectory(const Containers::String& directoryPath)` | 添加资源目录 |
|
|||
|
|
| `void RemoveArchive(const Containers::String& archivePath)` | 移除归档包 |
|
|||
|
|
| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源的绝对路径 |
|
|||
|
|
| `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 |
|
|||
|
|
| `Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const` | 读取资源文件内容（字节数组） |
|
|||
|
|
| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） |
|
|||
|
|
| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） |
|
|||
|
|
|
|||
|
|
## 实现说明
|
|||
|
|
|
|||
|
|
**注意**: 当前 `GetResourceInfo()` 不填充 `modifiedTime` 字段，`EnumerateResources()` 为 stub 实现。
|
|||
|
|
|
|||
|
|
## 使用示例
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
// 初始化资源文件系统
|
|||
|
|
ResourceFileSystem::Get().Initialize("resources/");
|
|||
|
|
|
|||
|
|
// 添加归档包（优先于目录）
|
|||
|
|
ResourceFileSystem::Get().AddArchive("data/resources.pak");
|
|||
|
|
|
|||
|
|
// 添加额外资源目录
|
|||
|
|
ResourceFileSystem::Get().AddDirectory("user_content/");
|
|||
|
|
|
|||
|
|
// 检查资源是否存在
|
|||
|
|
if (ResourceFileSystem::Get().Exists("textures/player.png")) {
|
|||
|
|
// 读取资源
|
|||
|
|
auto data = ResourceFileSystem::Get().ReadResource("textures/player.png");
|
|||
|
|
// 使用数据...
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 获取资源信息
|
|||
|
|
ResourceInfo info;
|
|||
|
|
if (ResourceFileSystem::Get().GetResourceInfo("shaders/default.vert", info)) {
|
|||
|
|
printf("Size: %zu, InArchive: %s\n", info.size, info.inArchive ? "yes" : "no");
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 枚举资源
|
|||
|
|
Containers::Array<ResourceInfo> textures;
|
|||
|
|
ResourceFileSystem::Get().EnumerateResources("textures/*.png", textures);
|
|||
|
|
for (const auto& tex : textures) {
|
|||
|
|
printf("Found: %s\n", tex.path.CStr());
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 关闭
|
|||
|
|
ResourceFileSystem::Get().Shutdown();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
|||
|
|
- [IResourceLoader](../iloader/iloader.md) - 资源加载器
|
|||
|
|
- [Resources 总览](../resources.md) - 返回模块总览
|