docs: update resources API docs
This commit is contained in:
51
docs/api/resources/resource-file-system/add-archive.md
Normal file
51
docs/api/resources/resource-file-system/add-archive.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# ResourceFileSystem::AddArchive
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
bool AddArchive(const Containers::String& archivePath);
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
添加档案压缩包作为资源来源。档案文件（如 ZIP、Pak 等格式）会被注册为可搜索的资源位置。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `archivePath` | `const Containers::String&` | 档案压缩包的路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 成功添加返回 `true`
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
|
||||
// 添加多个档案作为资源来源
|
||||
fs.AddArchive("C:/Game/Paks/Common.pak");
|
||||
fs.AddArchive("C:/Game/Paks/Textures.pak");
|
||||
fs.AddArchive("C:/Game/Paks/Audio.pak");
|
||||
|
||||
// 读取档案中的资源
|
||||
auto data = fs.ReadResource("textures/player/diffuse.png");
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 当前实现仅存储路径，实际档案加载功能待实现
|
||||
- 档案中的资源会通过 `FindInArchives` 被搜索
|
||||
51
docs/api/resources/resource-file-system/add-directory.md
Normal file
51
docs/api/resources/resource-file-system/add-directory.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# ResourceFileSystem::AddDirectory
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
bool AddDirectory(const Containers::String& directoryPath);
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
添加文件系统目录作为资源来源。指定的目录会被注册为可搜索的资源位置。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `directoryPath` | `const Containers::String&` | 目录的路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 成功添加返回 `true`
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
|
||||
// 添加多个目录作为资源来源
|
||||
fs.AddDirectory("C:/Game/Assets/Textures");
|
||||
fs.AddDirectory("C:/Game/Assets/Shaders");
|
||||
fs.AddDirectory("C:/Game/Assets/Models");
|
||||
|
||||
// 读取目录中的资源
|
||||
auto data = fs.ReadResource("textures/player/diffuse.png");
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 目录搜索优先级：根路径 > 先添加的目录
|
||||
- 路径末尾的斜杠会自动处理
|
||||
@@ -0,0 +1,63 @@
|
||||
# ResourceFileSystem::EnumerateResources
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const;
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
枚举所有匹配指定模式的资源。模式支持通配符（如 `*.png`、`textures/**` 等）。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `pattern` | `const Containers::String&` | 文件名匹配模式 |
|
||||
| `outResources` | `Containers::Array<ResourceInfo>&` | 输出容器，接收匹配的资源信息列表 |
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
|
||||
Containers::Array<ResourceInfo> resources;
|
||||
|
||||
// 枚举所有 PNG 纹理
|
||||
fs.EnumerateResources("**/*.png", resources);
|
||||
printf("Found %zu PNG files:\n", resources.Size());
|
||||
for (const auto& res : resources) {
|
||||
printf(" - %s (%zu bytes)\n", res.path.CStr(), res.size);
|
||||
}
|
||||
|
||||
// 枚举所有着色器
|
||||
resources.Clear();
|
||||
fs.EnumerateResources("**/*.glsl", resources);
|
||||
printf("Found %zu shader files:\n", resources.Size());
|
||||
|
||||
// 枚举特定目录下的资源
|
||||
resources.Clear();
|
||||
fs.EnumerateResources("textures/**/*.png", resources);
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 当前实现尚未完成，输出容器可能为空
|
||||
- 模式语法的具体支持情况待实现
|
||||
63
docs/api/resources/resource-file-system/exists.md
Normal file
63
docs/api/resources/resource-file-system/exists.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# ResourceFileSystem::Exists
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
bool Exists(const Containers::String& relativePath) const;
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
检查指定相对路径的资源是否存在。该方法会搜索所有已注册的目录和档案。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `relativePath` | `const Containers::String&` | 资源的相对路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 资源存在返回 `true`，不存在返回 `false`
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
fs.AddArchive("C:/Game/Paks/Textures.pak");
|
||||
|
||||
// 检查各种资源是否存在
|
||||
if (fs.Exists("textures/player/diffuse.png")) {
|
||||
// 加载纹理
|
||||
}
|
||||
|
||||
if (fs.Exists("shaders/forward.glsl")) {
|
||||
// 加载着色器
|
||||
}
|
||||
|
||||
if (fs.Exists("audio/bgm/main_theme.ogg")) {
|
||||
// 加载音频
|
||||
}
|
||||
|
||||
// 检查可能不存在的资源
|
||||
if (!fs.Exists("textures/legacy/old_texture.png")) {
|
||||
printf("Using default texture\n");
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 内部调用 `FindResource` 实现
|
||||
- 档案中的资源同样可以被检查
|
||||
60
docs/api/resources/resource-file-system/find-resource.md
Normal file
60
docs/api/resources/resource-file-system/find-resource.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# ResourceFileSystem::FindResource
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const;
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
查找指定相对路径的资源，并返回其绝对路径。搜索顺序为：目录（根路径 + 已注册目录）→ 档案。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `relativePath` | `const Containers::String&` | 资源的相对路径 |
|
||||
| `outAbsolutePath` | `Containers::String&` | 输出参数，接收资源的绝对路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 找到资源返回 `true`，未找到返回 `false`
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
|
||||
Containers::String absolutePath;
|
||||
|
||||
// 查找纹理资源
|
||||
if (fs.FindResource("textures/player/diffuse.png", absolutePath)) {
|
||||
printf("Found at: %s\n", absolutePath.CStr());
|
||||
// 使用绝对路径加载纹理
|
||||
} else {
|
||||
printf("Resource not found\n");
|
||||
}
|
||||
|
||||
// 查找着色器资源
|
||||
if (fs.FindResource("shaders/forward.glsl", absolutePath)) {
|
||||
printf("Shader at: %s\n", absolutePath.CStr());
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 搜索路径格式应使用正斜杠 `/`
|
||||
- 档案内资源返回的绝对路径格式为 `archive://relative/path`
|
||||
63
docs/api/resources/resource-file-system/get-resource-info.md
Normal file
63
docs/api/resources/resource-file-system/get-resource-info.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# ResourceFileSystem::GetResourceInfo
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const;
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
获取指定资源的详细信息，包括路径、大小、修改时间和所属档案等。查询结果会被缓存以提高后续查询性能。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `relativePath` | `const Containers::String&` | 资源的相对路径 |
|
||||
| `outInfo` | `ResourceInfo&` | 输出参数，接收资源信息 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 成功获取返回 `true`，资源不存在返回 `false`
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
fs.AddArchive("C:/Game/Paks/Textures.pak");
|
||||
|
||||
ResourceInfo info;
|
||||
|
||||
// 获取目录中的资源信息
|
||||
if (fs.GetResourceInfo("shaders/forward.glsl", info)) {
|
||||
printf("Path: %s\n", info.path.CStr());
|
||||
printf("Size: %zu bytes\n", info.size);
|
||||
printf("In Archive: %s\n", info.inArchive ? "Yes" : "No");
|
||||
}
|
||||
|
||||
// 获取档案中的资源信息
|
||||
if (fs.GetResourceInfo("textures/player/diffuse.png", info)) {
|
||||
printf("Path: %s\n", info.path.CStr());
|
||||
printf("Archive: %s\n", info.archivePath.CStr());
|
||||
printf("In Archive: %s\n", info.inArchive ? "Yes" : "No");
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 首次查询后信息会被缓存
|
||||
- 当前实现的大小和修改时间为占位值，待完整实现
|
||||
- `ResourceInfo::size` 和 `ResourceInfo::modifiedTime` 的获取需要操作系统 API 支持
|
||||
59
docs/api/resources/resource-file-system/get.md
Normal file
59
docs/api/resources/resource-file-system/get.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# ResourceFileSystem::Get
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
static ResourceFileSystem& Get();
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
获取 `ResourceFileSystem` 的单例实例。该方法是获取全局资源文件系统的唯一入口。
|
||||
|
||||
## 参数
|
||||
|
||||
无
|
||||
|
||||
## 返回值
|
||||
|
||||
- `ResourceFileSystem&` - 单例实例的引用
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
// 推荐用法：通过引用访问
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
|
||||
// 多次调用返回相同实例
|
||||
ResourceFileSystem& fs2 = ResourceFileSystem::Get();
|
||||
assert(&fs == &fs2); // 相同地址
|
||||
|
||||
// 完整使用流程
|
||||
ResourceFileSystem& fs3 = ResourceFileSystem::Get();
|
||||
fs3.Initialize("C:/Game/Resources");
|
||||
fs3.AddDirectory("C:/Game/Assets");
|
||||
fs3.AddArchive("C:/Game/Paks/Common.pak");
|
||||
|
||||
if (fs3.Exists("textures/player/diffuse.png")) {
|
||||
auto data = fs3.ReadResource("textures/player/diffuse.png");
|
||||
// 处理数据
|
||||
}
|
||||
|
||||
// 程序结束时清理
|
||||
fs3.Shutdown();
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 内部使用局部静态变量实现单例
|
||||
- 第一次调用时自动构造实例
|
||||
- 线程安全（局部静态变量初始化线程安全）
|
||||
123
docs/api/resources/resource-file-system/iarchive.md
Normal file
123
docs/api/resources/resource-file-system/iarchive.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# IArchive 接口
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Resources/ResourceFileSystem.h"
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Resources`
|
||||
|
||||
## 类型
|
||||
|
||||
抽象接口类
|
||||
|
||||
## 描述
|
||||
|
||||
`IArchive` 是档案压缩包资源的抽象接口，定义了访问档案内资源的基本操作。具体的档案实现（如 ZIP、Pak 等）需要继承此接口。
|
||||
|
||||
## 方法详情
|
||||
|
||||
### Open
|
||||
|
||||
```cpp
|
||||
virtual bool Open(const Containers::String& path) = 0;
|
||||
```
|
||||
|
||||
打开指定路径的档案文件。
|
||||
|
||||
**参数：**
|
||||
- `path` - 档案文件的路径
|
||||
|
||||
**返回值：**
|
||||
- `bool` - 成功返回 `true`，失败返回 `false`
|
||||
|
||||
---
|
||||
|
||||
### Close
|
||||
|
||||
```cpp
|
||||
virtual void Close() = 0;
|
||||
```
|
||||
|
||||
关闭当前打开的档案，释放相关资源。
|
||||
|
||||
---
|
||||
|
||||
### Read
|
||||
|
||||
```cpp
|
||||
virtual bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const = 0;
|
||||
```
|
||||
|
||||
从档案中读取指定的文件数据。
|
||||
|
||||
**参数：**
|
||||
- `fileName` - 要读取的文件名
|
||||
- `buffer` - 接收数据的缓冲区指针
|
||||
- `size` - 要读取的字节数
|
||||
- `offset` - 文件内的读取偏移量
|
||||
|
||||
**返回值：**
|
||||
- `bool` - 成功返回 `true`，失败返回 `false`
|
||||
|
||||
---
|
||||
|
||||
### GetSize
|
||||
|
||||
```cpp
|
||||
virtual size_t GetSize(const Containers::String& fileName) const = 0;
|
||||
```
|
||||
|
||||
获取档案内指定文件的大小。
|
||||
|
||||
**参数：**
|
||||
- `fileName` - 文件名
|
||||
|
||||
**返回值：**
|
||||
- `size_t` - 文件大小（字节），若文件不存在则返回 0
|
||||
|
||||
---
|
||||
|
||||
### Exists
|
||||
|
||||
```cpp
|
||||
virtual bool Exists(const Containers::String& fileName) const = 0;
|
||||
```
|
||||
|
||||
检查档案内是否存在指定文件。
|
||||
|
||||
**参数：**
|
||||
- `fileName` - 要检查的文件名
|
||||
|
||||
**返回值：**
|
||||
- `bool` - 存在返回 `true`，不存在返回 `false`
|
||||
|
||||
---
|
||||
|
||||
### Enumerate
|
||||
|
||||
```cpp
|
||||
virtual void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const = 0;
|
||||
```
|
||||
|
||||
枚举档案内匹配指定模式的文件。
|
||||
|
||||
**参数：**
|
||||
- `pattern` - 文件名匹配模式（支持通配符）
|
||||
- `outFiles` - 输出容器，接收匹配的文件名列表
|
||||
|
||||
---
|
||||
|
||||
### IsValid
|
||||
|
||||
```cpp
|
||||
virtual bool IsValid() const = 0;
|
||||
```
|
||||
|
||||
检查档案是否已正确打开且有效。
|
||||
|
||||
**返回值：**
|
||||
- `bool` - 有效返回 `true`，无效返回 `false`
|
||||
88
docs/api/resources/resource-file-system/index.md
Normal file
88
docs/api/resources/resource-file-system/index.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 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)
|
||||
49
docs/api/resources/resource-file-system/initialize.md
Normal file
49
docs/api/resources/resource-file-system/initialize.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# ResourceFileSystem::Initialize
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
void Initialize(const Containers::String& rootPath);
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
初始化资源文件系统，设置资源根目录路径。调用此方法后，资源系统将以指定路径作为基础路径进行资源搜索。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `rootPath` | `const Containers::String&` | 资源根目录的绝对路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
|
||||
// 初始化资源文件系统
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
|
||||
// 现在可以添加其他资源来源并访问资源
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 应在程序启动早期调用此方法
|
||||
- 如果已存在资源，系统会先清空现有配置
|
||||
- `Shutdown()` 会重置根路径设置
|
||||
66
docs/api/resources/resource-file-system/read-resource.md
Normal file
66
docs/api/resources/resource-file-system/read-resource.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# ResourceFileSystem::ReadResource
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const;
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
读取指定相对路径的资源内容，以字节数组形式返回。该方法会首先查找资源的绝对路径，然后从文件系统读取数据。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `relativePath` | `const Containers::String&` | 资源的相对路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
- `Containers::Array<Core::uint8>` - 资源数据的字节数组。如果读取失败或资源不存在，返回空数组。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
fs.AddDirectory("C:/Game/Assets");
|
||||
|
||||
// 读取文本资源
|
||||
auto textData = fs.ReadResource("shaders/forward.glsl");
|
||||
if (textData.Size() > 0) {
|
||||
printf("Shader size: %zu bytes\n", textData.Size());
|
||||
// 处理着色器源码
|
||||
}
|
||||
|
||||
// 读取二进制资源
|
||||
auto texData = fs.ReadResource("textures/player/diffuse.png");
|
||||
if (texData.Size() > 0) {
|
||||
// 使用图像数据
|
||||
const uint8_t* pixels = texData.Data();
|
||||
size_t width = *reinterpret_cast<const size_t*>(pixels);
|
||||
}
|
||||
|
||||
// 读取不存在的资源
|
||||
auto invalidData = fs.ReadResource("nonexistent/file.txt");
|
||||
if (invalidData.Empty()) {
|
||||
printf("Resource not found or read error\n");
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 返回的数组直接包含文件的原始字节数据
|
||||
- 当前实现仅支持从文件系统读取，档案读取待实现
|
||||
- 读取失败时返回空数组，可通过 `Empty()` 方法检查
|
||||
56
docs/api/resources/resource-file-system/remove-archive.md
Normal file
56
docs/api/resources/resource-file-system/remove-archive.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# ResourceFileSystem::RemoveArchive
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
void RemoveArchive(const Containers::String& archivePath);
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
移除已注册的档案压缩包。移除后，该档案内的资源将无法通过此资源系统访问。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数名 | 类型 | 描述 |
|
||||
|--------|------|------|
|
||||
| `archivePath` | `const Containers::String&` | 要移除的档案路径 |
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
fs.Initialize("C:/Game/Resources");
|
||||
|
||||
fs.AddArchive("C:/Game/Paks/Common.pak");
|
||||
fs.AddArchive("C:/Game/Paks/DLC.pak");
|
||||
|
||||
// 检查资源是否存在
|
||||
if (fs.Exists("dlc/special_texture.png")) {
|
||||
// 使用 DLC 资源
|
||||
}
|
||||
|
||||
// 移除 DLC 包
|
||||
fs.RemoveArchive("C:/Game/Paks/DLC.pak");
|
||||
|
||||
// 现在 DLC 资源无法访问
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 如果档案不存在，则此方法不做任何操作
|
||||
- 当前实现从目录列表中移除匹配路径（档案与目录共用存储）
|
||||
46
docs/api/resources/resource-file-system/resource-info.md
Normal file
46
docs/api/resources/resource-file-system/resource-info.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# ResourceInfo 结构
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Resources/ResourceFileSystem.h"
|
||||
```
|
||||
|
||||
## 命名空间
|
||||
|
||||
`XCEngine::Resources`
|
||||
|
||||
## 描述
|
||||
|
||||
`ResourceInfo` 结构体用于存储资源的元数据信息，包括资源路径、大小、修改时间和所属档案等。
|
||||
|
||||
## 成员变量
|
||||
|
||||
| 变量 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `path` | `Containers::String` | 资源的相对路径 |
|
||||
| `size` | `size_t` | 资源大小（字节） |
|
||||
| `modifiedTime` | `Core::uint64` | 最后修改时间戳 |
|
||||
| `inArchive` | `bool` | 是否位于档案压缩包内 |
|
||||
| `archivePath` | `Containers::String` | 所属档案的路径（如果位于档案内） |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
ResourceInfo info;
|
||||
|
||||
if (fs.GetResourceInfo("textures/player/diffuse.png", info)) {
|
||||
printf("Path: %s\n", info.path.CStr());
|
||||
printf("Size: %zu bytes\n", info.size);
|
||||
printf("Modified: %llu\n", info.modifiedTime);
|
||||
printf("In Archive: %s\n", info.inArchive ? "Yes" : "No");
|
||||
if (info.inArchive) {
|
||||
printf("Archive: %s\n", info.archivePath.CStr());
|
||||
}
|
||||
}
|
||||
```
|
||||
44
docs/api/resources/resource-file-system/shutdown.md
Normal file
44
docs/api/resources/resource-file-system/shutdown.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# ResourceFileSystem::Shutdown
|
||||
|
||||
## 方法签名
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
## 所属类
|
||||
|
||||
`XCEngine::Resources::ResourceFileSystem`
|
||||
|
||||
## 描述
|
||||
|
||||
关闭资源文件系统，释放所有已分配的资源。此方法会清空所有已注册的档案和目录，清除资源信息缓存，并将根路径重置为空字符串。
|
||||
|
||||
此方法线程安全。
|
||||
|
||||
## 参数
|
||||
|
||||
无
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include "Resources/ResourceFileSystem.h"
|
||||
|
||||
using namespace XCEngine::Resources;
|
||||
|
||||
ResourceFileSystem& fs = ResourceFileSystem::Get();
|
||||
|
||||
// 程序结束时关闭资源系统
|
||||
fs.Shutdown();
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 应在程序退出前调用此方法
|
||||
- 调用后系统处于未初始化状态，需要重新调用 `Initialize()` 才能使用
|
||||
- 已打开的档案会被自动关闭
|
||||
Reference in New Issue
Block a user