ssdfasd
7e4c48d4f9
Fixed discrepancies between source code and documentation: - AsyncLoader: Document Initialize() ignores workerThreadCount, Submit() doesn't do actual async loading, Update() is stub - ResourceManager: Document UnloadUnused() and ReloadResource() are stubs - ResourceCache: Document OnZeroRefCount() and Flush() are stubs - ResourceDependencyGraph: Document TopologicalSort() returns empty (stub) - ResourceFileSystem: Document GetResourceInfo() doesn't fill modifiedTime, EnumerateResources() is stub - FileArchive: Document Enumerate() is stub - ResourcePackageBuilder: Document AddDirectory() is stub - ImportSettings: Document LoadFromJSON/SaveToJSON are stubs - TextureImportSettings/MeshImportSettings: Document JSON methods are stubs - TextureLoader/MeshLoader/MaterialLoader/ShaderLoader/AudioLoader: Document GetDefaultSettings() returns nullptr - AudioLoader: Document ParseWAVData() is stub, Load() doesn't parse WAV headers - ShaderLoader: Document DetectShaderType/ParseShaderSource are stubs - MaterialLoader: Document ParseMaterialData() is stub - Texture: Document Create() mipLevels=0 behavior, GenerateMipmaps() returns false - Mesh: Document MeshLoader::Load() is example only - IResourceLoader: Document GetDefaultSettings() returns nullptr for all loaders
162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 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 = "")` | 添加整个目录到包（当前为 stub，始终返回 true） |
|
||
| `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` | 获取错误信息 |
|
||
|
||
## 实现说明
|
||
|
||
**注意**: `ResourcePackageBuilder::AddDirectory()` 当前为 stub，始终返回 true。
|
||
|
||
## 使用示例（构建）
|
||
|
||
```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) - 返回模块总览
|