docs: update resources API docs

2026-03-20 02:35:35 +08:00
parent fd792b7df1
commit ea756c0177
314 changed files with 9439 additions and 1360 deletions
--- a/docs/api/resources/resource-package/close.md
+++ b/docs/api/resources/resource-package/close.md
@@ -0,0 +1,42 @@
+# Close
+
+关闭资源包并释放相关资源。
+
+## 方法签名
+
+```cpp
+void Close();
+```
+
+## 详细描述
+
+关闭当前打开的资源包，重置所有内部状态并释放相关资源。调用此方法后，包将变为无效状态，任何尝试读取文件的行为都将失败。
+
+此方法在析构函数中会被自动调用，确保资源正确释放。
+
+## 参数
+
+无
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+ResourcePackage package;
+if (package.Open("assets/resources.xcp")) {
+    // 使用包...
+    
+    // 显式关闭
+    package.Close();
+}
+
+// 或者当 package 超出作用域时会自动关闭
+```
+
+## 相关方法
+
+- [Open](open.md) - 打开资源包
+- [IsValid](isvalid.md) - 检查包有效性
--- a/docs/api/resources/resource-package/enumerate.md
+++ b/docs/api/resources/resource-package/enumerate.md
@@ -0,0 +1,56 @@
+# Enumerate
+
+枚举资源包中匹配指定模式的文件。
+
+## 方法签名
+
+```cpp
+void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const;
+```
+
+## 详细描述
+
+枚举包内所有与给定模式匹配的文件路径，并将结果输出到 `outFiles` 数组中。当前实现会将 `outFiles` 清空后填入所有文件路径。
+
+**注意**：当前实现不支持真正的通配符匹配，会返回包内所有文件的完整路径列表。
+
+## 参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| `pattern` | `const Containers::String&` | 文件匹配模式（当前实现中未使用） |
+| `outFiles` | `Containers::Array<Containers::String>&` | 输出参数，用于存放匹配的文件路径列表 |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+ResourcePackage package;
+package.Open("assets/resources.xcp");
+
+Array<String> files;
+
+// 枚举所有文件
+package.Enumerate("*", files);
+printf("Total files: %zu\n", files.Size());
+
+for (const auto& file : files) {
+    printf("  - %s\n", file.CStr());
+}
+
+// 枚举特定类型的文件
+package.Enumerate("*.png", files);
+for (const auto& file : files) {
+    if (file.Find(".png") != String::InvalidPos) {
+        printf("Image: %s\n", file.CStr());
+    }
+}
+```
+
+## 相关方法
+
+- [Exists](exists.md) - 检查文件存在
+- [Read](read.md) - 读取文件内容
--- a/docs/api/resources/resource-package/exists.md
+++ b/docs/api/resources/resource-package/exists.md
@@ -0,0 +1,52 @@
+# Exists
+
+检查指定文件是否存在于资源包中。
+
+## 方法签名
+
+```cpp
+bool Exists(const Containers::String& relativePath) const;
+```
+
+## 详细描述
+
+检查资源包中是否存在指定相对路径的文件。使用斜杠 `/` 作为路径分隔符，支持带或不带文件扩展名的路径。
+
+## 参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| `relativePath` | `const Containers::String&` | 文件的相对路径，相对于包内根目录 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 文件存在返回 `true`，不存在返回 `false` |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+package.Open("assets/resources.xcp");
+
+// 检查不同类型的文件
+if (package.Exists("textures/player.png")) {
+    printf("Player texture exists\n");
+}
+
+if (package.Exists("audio/bgm_main.ogg")) {
+    printf("Background music exists\n");
+}
+
+// 使用通配符检查（当前实现会按字面量匹配）
+if (package.Exists("shaders/*")) {
+    // 注意：当前实现不支持真正的通配符匹配
+}
+```
+
+## 相关方法
+
+- [Read](read.md) - 读取文件内容
+- [GetSize](getsize.md) - 获取文件大小
+- [Enumerate](enumerate.md) - 枚举文件
--- a/docs/api/resources/resource-package/getinfo.md
+++ b/docs/api/resources/resource-package/getinfo.md
@@ -0,0 +1,50 @@
+# GetInfo
+
+获取资源包的元信息。
+
+## 方法签名
+
+```cpp
+const PackageInfo& GetInfo() const;
+```
+
+## 详细描述
+
+返回资源包的元信息结构体引用，包含包的路径、版本号、文件数量和总大小等基本信息。
+
+## 参数
+
+无
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `const PackageInfo&` | PackageInfo 结构体引用，包含包的元信息 |
+
+## PackageInfo 结构体
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `path` | `Containers::String` | 包文件的完整路径 |
+| `version` | `Core::uint16` | 包文件格式版本号 |
+| `fileCount` | `size_t` | 包内包含的文件数量 |
+| `totalSize` | `size_t` | 包文件的总大小（字节） |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+package.Open("assets/resources.xcp");
+
+const auto& info = package.GetInfo();
+printf("Package Path: %s\n", info.path.CStr());
+printf("Package Version: %u\n", info.version);
+printf("File Count: %zu\n", info.fileCount);
+printf("Total Size: %zu bytes\n", info.totalSize);
+```
+
+## 相关方法
+
+- [Open](open.md) - 打开资源包
+- [IsValid](isvalid.md) - 检查包有效性
--- a/docs/api/resources/resource-package/getsize.md
+++ b/docs/api/resources/resource-package/getsize.md
@@ -0,0 +1,45 @@
+# GetSize
+
+获取资源包中指定文件的原始大小。
+
+## 方法签名
+
+```cpp
+size_t GetSize(const Containers::String& relativePath) const;
+```
+
+## 详细描述
+
+返回指定文件压缩前的大小（字节数）。如果文件不存在于包中，返回 0。
+
+## 参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| `relativePath` | `const Containers::String&` | 文件的相对路径 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `size_t` | 文件大小（字节），文件不存在时返回 0 |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+package.Open("assets/resources.xcp");
+
+size_t size = package.GetSize("textures/player.png");
+if (size > 0) {
+    printf("Player texture size: %zu bytes\n", size);
+    
+    // 可以用来预分配缓冲区
+    Array<uint8> buffer(size);
+}
+```
+
+## 相关方法
+
+- [Read](read.md) - 读取文件内容
+- [Exists](exists.md) - 检查文件存在
--- a/docs/api/resources/resource-package/index.md
+++ b/docs/api/resources/resource-package/index.md
@@ -0,0 +1,95 @@
+# ResourcePackage 类
+
+## 命名空间
+
+`XCEngine::Resources`
+
+## 类型
+
+类 (Class)
+
+## 描述
+
+ResourcePackage 是 XCEngine 资源包的核心类，用于读取和管理 `.xcp` 格式的资源包文件。资源包是一种将多个资源文件打包成单一文件的格式，支持文件枚举、读取和校验。
+
+## 概述
+
+ResourcePackage 提供了一套完整的资源包读取接口，包括打开/关闭包、查询文件存在性、读取文件内容、获取文件大小以及枚举包内文件等功能。包文件格式采用二进制结构，包含文件头、清单和数据区域。
+
+包文件格式：
+- **文件头** (20 字节): 魔数 "XCRP" (4B) + 版本号 (2B) + 清单大小 (4B) + 文件数量 (4B) + 数据偏移 (8B)
+- **清单区域**: 存储文件元数据列表
+- **数据区域**: 存储实际文件数据
+
+## 公共方法表格
+
+| 方法 | 签名 | 描述 |
+|------|------|------|
+| [Open](open.md) | `bool Open(const Containers::String& packagePath)` | 打开资源包文件 |
+| [Close](close.md) | `void Close()` | 关闭资源包并释放资源 |
+| [IsValid](isvalid.md) | `bool IsValid() const` | 检查包是否有效 |
+| [Exists](exists.md) | `bool Exists(const Containers::String& relativePath) const` | 检查文件是否存在 |
+| [Read](read.md) | `Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const` | 读取文件内容 |
+| [GetSize](getsize.md) | `size_t GetSize(const Containers::String& relativePath) const` | 获取文件大小 |
+| [Enumerate](enumerate.md) | `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举匹配的文件 |
+| [GetInfo](getinfo.md) | `const PackageInfo& GetInfo() const` | 获取包信息 |
+
+## 嵌套类型
+
+### PackageInfo
+
+包文件的元信息结构体。
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `path` | `Containers::String` | 包文件路径 |
+| `version` | `Core::uint16` | 包文件版本号 |
+| `fileCount` | `size_t` | 包内文件数量 |
+| `totalSize` | `size_t` | 包文件总大小 |
+
+## 使用示例
+
+```cpp
+#include "Resources/ResourcePackage.h"
+
+using namespace XCEngine;
+using namespace XCEngine::Containers;
+using namespace XCEngine::Resources;
+
+// 打开资源包
+ResourcePackage package;
+if (!package.Open("assets/resources.xcp")) {
+    // 处理打开失败
+    return;
+}
+
+// 检查文件是否存在
+if (package.Exists("textures/player.png")) {
+    // 读取文件
+    Array<uint8> data = package.Read("textures/player.png");
+    // 处理数据...
+}
+
+// 获取文件大小
+size_t size = package.GetSize("textures/player.png");
+
+// 枚举所有文件
+Array<String> files;
+package.Enumerate("*", files);
+for (const auto& file : files) {
+    printf("Found file: %s\n", file.CStr());
+}
+
+// 获取包信息
+const auto& info = package.GetInfo();
+printf("Package: %s, Version: %u, Files: %zu\n", 
+       info.path.CStr(), info.version, info.fileCount);
+
+// 关闭资源包
+package.Close();
+```
+
+## 相关文档
+
+- [ResourcePackageBuilder](../audio-loader/index.md) - 资源包构建器
+- [ResourceTypes](../audio-loader/index.md) - 资源类型定义
--- a/docs/api/resources/resource-package/isvalid.md
+++ b/docs/api/resources/resource-package/isvalid.md
@@ -0,0 +1,53 @@
+# IsValid
+
+检查资源包当前是否有效。
+
+## 方法签名
+
+```cpp
+bool IsValid() const;
+```
+
+## 详细描述
+
+返回一个布尔值，表示资源包当前是否处于有效状态。当包成功打开且未被关闭时返回 `true`。
+
+## 参数
+
+无
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 包有效返回 `true`，无效返回 `false` |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+
+// 打开前
+if (!package.IsValid()) {
+    printf("Package is not valid yet\n");
+}
+
+package.Open("assets/resources.xcp");
+
+// 打开后
+if (package.IsValid()) {
+    printf("Package is valid and ready to use\n");
+}
+
+package.Close();
+
+// 关闭后
+if (!package.IsValid()) {
+    printf("Package has been closed\n");
+}
+```
+
+## 相关方法
+
+- [Open](open.md) - 打开资源包
+- [Close](close.md) - 关闭资源包
--- a/docs/api/resources/resource-package/open.md
+++ b/docs/api/resources/resource-package/open.md
@@ -0,0 +1,51 @@
+# Open
+
+打开资源包文件。
+
+## 方法签名
+
+```cpp
+bool Open(const Containers::String& packagePath);
+```
+
+## 详细描述
+
+尝试打开指定路径的资源包文件并解析其文件头和清单。如果文件不存在、格式无效或版本不匹配，方法将返回 `false`。
+
+包文件格式验证包括：
+1. 检查魔数是否为 "XCRP"
+2. 验证版本号是否为支持的版本
+3. 读取并解析文件清单
+
+## 参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| `packagePath` | `const Containers::String&` | 资源包文件的完整路径或相对路径 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `bool` | 成功打开返回 `true`，失败返回 `false` |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+
+// 使用相对路径打开
+if (package.Open("assets/resources.xcp")) {
+    // 包已成功打开
+}
+
+// 使用绝对路径打开
+if (package.Open("D:/Game/assets/resources.xcp")) {
+    // 包已成功打开
+}
+```
+
+## 相关方法
+
+- [Close](close.md) - 关闭资源包
+- [IsValid](isvalid.md) - 检查包有效性
--- a/docs/api/resources/resource-package/read.md
+++ b/docs/api/resources/resource-package/read.md
@@ -0,0 +1,55 @@
+# Read
+
+读取资源包中指定文件的内容。
+
+## 方法签名
+
+```cpp
+Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const;
+```
+
+## 详细描述
+
+从资源包中读取指定文件的完整内容并返回。如果文件不存在或读取失败，返回空的数组。
+
+文件内容以字节数组形式返回，适用于读取二进制资源如图像、音频、着色器等。
+
+## 参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| `relativePath` | `const Containers::String&` | 文件的相对路径 |
+
+## 返回值
+
+| 类型 | 描述 |
+|------|------|
+| `Containers::Array<Core::uint8>` | 文件内容的字节数组，失败时返回空数组 |
+
+## 示例
+
+```cpp
+ResourcePackage package;
+package.Open("assets/resources.xcp");
+
+// 读取图像文件
+Array<uint8> imageData = package.Read("textures/player.png");
+if (!imageData.Empty()) {
+    printf("Loaded image: %zu bytes\n", imageData.Size());
+}
+
+// 读取文本文件（需要额外处理 UTF-8 编码）
+Array<uint8> textData = package.Read("config/settings.txt");
+if (!textData.Empty()) {
+    // 转换为字符串
+    String text(reinterpret_cast<const char*>(textData.Data()), textData.Size());
+}
+
+// 读取着色器
+Array<uint8> shaderData = package.Read("shaders/pbr.glsl");
+```
+
+## 相关方法
+
+- [Exists](exists.md) - 检查文件存在
+- [GetSize](getsize.md) - 获取文件大小