docs: Add missing resources module documentation
Added documentation for undocumented classes: - ResourcePath: Path manipulation and GUID conversion utilities - FileArchive: Archive file reading support - ResourcePackage/ResourcePackageBuilder: Resource packaging system Updated resources.md overview to include new documentation modules and added ImportSettings and ResourceFileSystem to core components.
This commit is contained in:
80
docs/api/resources/filearchive/filearchive.md
Normal file
80
docs/api/resources/filearchive/filearchive.md
Normal file
@@ -0,0 +1,80 @@
|
|||||||
|
# FileArchive
|
||||||
|
|
||||||
|
**命名空间**: `XCEngine::Resources`
|
||||||
|
|
||||||
|
**类型**: `class` (extends IArchive)
|
||||||
|
|
||||||
|
**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。
|
||||||
|
|
||||||
|
## 头文件
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
#include <XCEngine/Resources/FileArchive.h>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 继承关系
|
||||||
|
|
||||||
|
```
|
||||||
|
IArchive
|
||||||
|
└── FileArchive
|
||||||
|
```
|
||||||
|
|
||||||
|
## 公共方法
|
||||||
|
|
||||||
|
### 构造与析构
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `FileArchive()` | 默认构造 |
|
||||||
|
| `~FileArchive()` | 析构函数，关闭归档 |
|
||||||
|
|
||||||
|
### IArchive 接口实现
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool Open(const Containers::String& path) override` | 打开归档文件 |
|
||||||
|
| `void Close() override` | 关闭归档文件 |
|
||||||
|
| `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 |
|
||||||
|
| `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 |
|
||||||
|
| `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 |
|
||||||
|
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件 |
|
||||||
|
| `bool IsValid() const override` | 检查归档是否有效 |
|
||||||
|
|
||||||
|
### 访问器
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `const Containers::String& GetPath() const` | 获取归档文件路径 |
|
||||||
|
|
||||||
|
## 使用示例
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
FileArchive archive;
|
||||||
|
if (archive.Open("data/resources.pak")) {
|
||||||
|
// 检查文件是否存在
|
||||||
|
if (archive.Exists("textures/player.png")) {
|
||||||
|
// 获取文件大小
|
||||||
|
size_t size = archive.GetSize("textures/player.png");
|
||||||
|
|
||||||
|
// 读取文件内容
|
||||||
|
Containers::Array<Core::uint8> buffer(size);
|
||||||
|
archive.Read("textures/player.png", buffer.Data(), size, 0);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 枚举文件
|
||||||
|
Containers::Array<Containers::String> files;
|
||||||
|
archive.Enumerate("textures/*.png", files);
|
||||||
|
|
||||||
|
archive.Close();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [IArchive](../filesystem/filesystem.md) - 归档接口
|
||||||
|
- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
|
||||||
|
- [Resources 总览](../resources.md) - 返回模块总览
|
||||||
157
docs/api/resources/resourcepackage/resourcepackage.md
Normal file
157
docs/api/resources/resourcepackage/resourcepackage.md
Normal file
@@ -0,0 +1,157 @@
|
|||||||
|
# ResourcePackage
|
||||||
|
|
||||||
|
**命名空间**: `XCEngine::Resources`
|
||||||
|
|
||||||
|
**类型**: `class`
|
||||||
|
|
||||||
|
**描述**: 资源包读写工具，支持打包多个资源文件到单个包文件中，以及从包中读取资源。
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
`ResourcePackage` 提供了资源打包功能，可以将多个资源文件打包成单个包文件，方便分发和加载。包文件包含文件清单和数据区域。
|
||||||
|
|
||||||
|
## 头文件
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
#include <XCEngine/Resources/ResourcePackage.h>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PackageFileEntry 结构体
|
||||||
|
|
||||||
|
打包文件条目信息。
|
||||||
|
|
||||||
|
| 成员 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| `relativePath` | `Containers::String` | 相对路径 |
|
||||||
|
| `size` | `size_t` | 文件大小 |
|
||||||
|
| `checksum` | `Core::uint64` | 校验和 |
|
||||||
|
| `offset` | `size_t` | 数据偏移量 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ResourcePackageBuilder
|
||||||
|
|
||||||
|
资源包构建器，用于创建新的资源包。
|
||||||
|
|
||||||
|
### 构造与析构
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `ResourcePackageBuilder()` | 默认构造 |
|
||||||
|
| `~ResourcePackageBuilder()` | 析构函数 |
|
||||||
|
|
||||||
|
### 包构建
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool AddFile(const Containers::String& sourcePath, const Containers::String& relativePath)` | 添加单个文件到包 |
|
||||||
|
| `bool AddDirectory(const Containers::String& sourceDir, const Containers::String& relativeBase = "")` | 添加整个目录到包 |
|
||||||
|
| `void SetOutputPath(const Containers::String& path)` | 设置输出包文件路径 |
|
||||||
|
| `const Containers::String& GetOutputPath() const` | 获取输出路径 |
|
||||||
|
| `bool Build()` | 构建包文件 |
|
||||||
|
| `float GetProgress() const` | 获取构建进度（0.0f ~ 1.0f） |
|
||||||
|
| `const Containers::String& GetError() const` | 获取错误信息 |
|
||||||
|
|
||||||
|
## 使用示例（构建）
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
ResourcePackageBuilder builder;
|
||||||
|
|
||||||
|
// 添加文件
|
||||||
|
builder.AddFile("textures/player.png", "textures/player.png");
|
||||||
|
builder.AddFile("textures/terrain.png", "textures/terrain.png");
|
||||||
|
|
||||||
|
// 添加目录
|
||||||
|
builder.AddDirectory("shaders/", "shaders/");
|
||||||
|
|
||||||
|
// 设置输出
|
||||||
|
builder.SetOutputPath("data/resources.pkg");
|
||||||
|
|
||||||
|
// 构建
|
||||||
|
if (builder.Build()) {
|
||||||
|
printf("Package built successfully!\n");
|
||||||
|
} else {
|
||||||
|
printf("Build failed: %s\n", builder.GetError().CStr());
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ResourcePackage
|
||||||
|
|
||||||
|
资源包读取器，用于从已打包的文件中读取资源。
|
||||||
|
|
||||||
|
### 构造与析构
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `ResourcePackage()` | 默认构造 |
|
||||||
|
| `~ResourcePackage()` | 析构函数，自动关闭包 |
|
||||||
|
|
||||||
|
### 包操作
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool Open(const Containers::String& packagePath)` | 打开包文件 |
|
||||||
|
| `void Close()` | 关闭包文件 |
|
||||||
|
| `bool IsValid() const` | 检查包是否有效 |
|
||||||
|
|
||||||
|
### 文件操作
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool Exists(const Containers::String& relativePath) const` | 检查文件是否存在于包中 |
|
||||||
|
| `Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const` | 读取包内文件 |
|
||||||
|
| `size_t GetSize(const Containers::String& relativePath) const` | 获取包内文件大小 |
|
||||||
|
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举包内匹配的文件 |
|
||||||
|
|
||||||
|
### 包信息
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `const PackageInfo& GetInfo() const` | 获取包信息 |
|
||||||
|
|
||||||
|
### PackageInfo 结构体
|
||||||
|
|
||||||
|
| 成员 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| `path` | `Containers::String` | 包文件路径 |
|
||||||
|
| `version` | `Core::uint16` | 包格式版本 |
|
||||||
|
| `fileCount` | `size_t` | 文件数量 |
|
||||||
|
| `totalSize` | `size_t` | 总大小 |
|
||||||
|
|
||||||
|
## 使用示例（读取）
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
ResourcePackage package;
|
||||||
|
if (package.Open("data/resources.pkg")) {
|
||||||
|
// 检查文件
|
||||||
|
if (package.Exists("textures/player.png")) {
|
||||||
|
// 读取文件
|
||||||
|
auto data = package.Read("textures/player.png");
|
||||||
|
if (!data.Empty()) {
|
||||||
|
// 使用数据...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 获取文件大小
|
||||||
|
size_t size = package.GetSize("textures/player.png");
|
||||||
|
|
||||||
|
// 枚举文件
|
||||||
|
Containers::Array<Containers::String> files;
|
||||||
|
package.Enumerate("textures/*.png", files);
|
||||||
|
|
||||||
|
// 获取包信息
|
||||||
|
auto info = package.GetInfo();
|
||||||
|
printf("Package: %s, Files: %zu\n", info.path.CStr(), info.fileCount);
|
||||||
|
|
||||||
|
package.Close();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
|
||||||
|
- [Resources 总览](../resources.md) - 返回模块总览
|
||||||
87
docs/api/resources/resourcepath/resourcepath.md
Normal file
87
docs/api/resources/resourcepath/resourcepath.md
Normal file
@@ -0,0 +1,87 @@
|
|||||||
|
# ResourcePath
|
||||||
|
|
||||||
|
**命名空间**: `XCEngine::Resources`
|
||||||
|
|
||||||
|
**类型**: `class`
|
||||||
|
|
||||||
|
**描述**: 资源路径封装类，提供路径解析、转换和 GUID 生成功能。
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
`ResourcePath` 封装了资源路径字符串，提供了一系列便捷方法进行路径解析、扩展名检查和 GUID 转换。
|
||||||
|
|
||||||
|
## 头文件
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
#include <XCEngine/Resources/ResourcePath.h>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 公共方法
|
||||||
|
|
||||||
|
### 构造
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `ResourcePath() = default` | 默认构造空路径 |
|
||||||
|
| `ResourcePath(const char* path)` | 从 C 字符串构造 |
|
||||||
|
| `ResourcePath(const Containers::String& path)` | 从 String 构造 |
|
||||||
|
|
||||||
|
### 路径解析
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `Containers::String GetExtension() const` | 获取文件扩展名 |
|
||||||
|
| `Containers::String GetStem() const` | 获取文件名（不含扩展名） |
|
||||||
|
| `Containers::String GetFullPath() const` | 获取完整路径 |
|
||||||
|
| `Containers::String GetFileName() const` | 获取文件名（含扩展名） |
|
||||||
|
| `Containers::String GetDirectory() const` | 获取目录部分 |
|
||||||
|
| `Containers::String GetRelativePath() const` | 获取相对路径 |
|
||||||
|
|
||||||
|
### GUID 转换
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `ResourceGUID ToGUID() const` | 将路径转换为 GUID |
|
||||||
|
|
||||||
|
### 扩展名检查
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool HasExtension(const char* ext) const` | 检查是否具有指定扩展名 |
|
||||||
|
| `bool HasAnyExtension(const char* const* extensions, Core::uint32 count) const` | 检查是否具有任意指定扩展名 |
|
||||||
|
|
||||||
|
### 状态
|
||||||
|
|
||||||
|
| 方法 | 描述 |
|
||||||
|
|------|------|
|
||||||
|
| `bool IsValid() const` | 检查路径是否有效（非空） |
|
||||||
|
| `const Containers::String& GetPath() const` | 获取原始路径字符串 |
|
||||||
|
| `void SetPath(const Containers::String& path)` | 设置路径字符串 |
|
||||||
|
|
||||||
|
## 使用示例
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
ResourcePath path("textures/player.png");
|
||||||
|
|
||||||
|
// 路径解析
|
||||||
|
Containers::String ext = path.GetExtension(); // ".png"
|
||||||
|
Containers::String name = path.GetFileName(); // "player.png"
|
||||||
|
Containers::String dir = path.GetDirectory(); // "textures"
|
||||||
|
|
||||||
|
// 扩展名检查
|
||||||
|
if (path.HasExtension(".png") || path.HasExtension(".jpg")) {
|
||||||
|
// 是图像文件
|
||||||
|
}
|
||||||
|
|
||||||
|
// 转换为 GUID
|
||||||
|
ResourceGUID guid = path.ToGUID();
|
||||||
|
|
||||||
|
// 在 HashMap 中作为键使用
|
||||||
|
Containers::HashMap<ResourcePath, ResourceHandle<Texture>> textures;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 相关文档
|
||||||
|
|
||||||
|
- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义
|
||||||
|
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||||
|
- [Resources 总览](../resources.md) - 返回模块总览
|
||||||
@@ -24,6 +24,16 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步
|
|||||||
| [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
|
| [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
|
||||||
| [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 |
|
| [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 |
|
||||||
| [ResourceTypes](resourcetypes/resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 |
|
| [ResourceTypes](resourcetypes/resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 |
|
||||||
|
| [ResourcePath](resourcepath/resourcepath.md) | `ResourcePath.h` | 资源路径封装 |
|
||||||
|
| [ResourceFileSystem](filesystem/filesystem.md) | `ResourceFileSystem.h` | 虚拟文件系统 |
|
||||||
|
| [ImportSettings](importsettings/importsettings.md) | `ImportSettings.h` | 导入设置基类 |
|
||||||
|
|
||||||
|
### 文件与打包
|
||||||
|
|
||||||
|
| 组件 | 文件 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| [FileArchive](filearchive/filearchive.md) | `FileArchive.h` | 文件归档读取 |
|
||||||
|
| [ResourcePackage](resourcepackage/resourcepackage.md) | `ResourcePackage.h` | 资源包打包/读取 |
|
||||||
|
|
||||||
### 具体资源类型
|
### 具体资源类型
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user