From 452ccd4f8f073f7b9a9406a188c760e1085b7e7a Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 19 Mar 2026 01:06:12 +0800 Subject: [PATCH] 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. --- docs/api/resources/filearchive/filearchive.md | 80 +++++++++ .../resourcepackage/resourcepackage.md | 157 ++++++++++++++++++ .../resources/resourcepath/resourcepath.md | 87 ++++++++++ docs/api/resources/resources.md | 10 ++ 4 files changed, 334 insertions(+) create mode 100644 docs/api/resources/filearchive/filearchive.md create mode 100644 docs/api/resources/resourcepackage/resourcepackage.md create mode 100644 docs/api/resources/resourcepath/resourcepath.md diff --git a/docs/api/resources/filearchive/filearchive.md b/docs/api/resources/filearchive/filearchive.md new file mode 100644 index 00000000..b72f9d43 --- /dev/null +++ b/docs/api/resources/filearchive/filearchive.md @@ -0,0 +1,80 @@ +# FileArchive + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` (extends IArchive) + +**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。 + +## 概述 + +`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。 + +## 头文件 + +```cpp +#include +``` + +## 继承关系 + +``` +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& 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 buffer(size); + archive.Read("textures/player.png", buffer.Data(), size, 0); + } + + // 枚举文件 + Containers::Array files; + archive.Enumerate("textures/*.png", files); + + archive.Close(); +} +``` + +## 相关文档 + +- [IArchive](../filesystem/filesystem.md) - 归档接口 +- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcepackage/resourcepackage.md b/docs/api/resources/resourcepackage/resourcepackage.md new file mode 100644 index 00000000..1a68463a --- /dev/null +++ b/docs/api/resources/resourcepackage/resourcepackage.md @@ -0,0 +1,157 @@ +# ResourcePackage + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**描述**: 资源包读写工具，支持打包多个资源文件到单个包文件中，以及从包中读取资源。 + +## 概述 + +`ResourcePackage` 提供了资源打包功能，可以将多个资源文件打包成单个包文件，方便分发和加载。包文件包含文件清单和数据区域。 + +## 头文件 + +```cpp +#include +``` + +--- + +## 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 Read(const Containers::String& relativePath) const` | 读取包内文件 | +| `size_t GetSize(const Containers::String& relativePath) const` | 获取包内文件大小 | +| `void Enumerate(const Containers::String& pattern, Containers::Array& 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 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) - 返回模块总览 diff --git a/docs/api/resources/resourcepath/resourcepath.md b/docs/api/resources/resourcepath/resourcepath.md new file mode 100644 index 00000000..daf71b09 --- /dev/null +++ b/docs/api/resources/resourcepath/resourcepath.md @@ -0,0 +1,87 @@ +# ResourcePath + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**描述**: 资源路径封装类，提供路径解析、转换和 GUID 生成功能。 + +## 概述 + +`ResourcePath` 封装了资源路径字符串，提供了一系列便捷方法进行路径解析、扩展名检查和 GUID 转换。 + +## 头文件 + +```cpp +#include +``` + +## 公共方法 + +### 构造 + +| 方法 | 描述 | +|------|------| +| `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> textures; +``` + +## 相关文档 + +- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resources.md b/docs/api/resources/resources.md index aa3f2a39..fc28c9c0 100644 --- a/docs/api/resources/resources.md +++ b/docs/api/resources/resources.md @@ -24,6 +24,16 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步 | [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 | | [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.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` | 资源包打包/读取 | ### 具体资源类型