diff --git a/docs/api/resources/asyncloader/asyncloader.md b/docs/api/resources/asyncloader/asyncloader.md index ed1955df..abb28caf 100644 --- a/docs/api/resources/asyncloader/asyncloader.md +++ b/docs/api/resources/asyncloader/asyncloader.md @@ -4,6 +4,8 @@ **类型**: `class` (singleton) +**头文件**: `XCEngine/Resources/AsyncLoader.h` + **描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。 ## 概述 @@ -59,13 +61,25 @@ | `void CancelAll()` | 取消所有待处理的加载请求 | | `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 | +### 方法详情 + +- [Initialize](initialize.md) - 初始化异步加载器 +- [Shutdown](shutdown.md) - 关闭异步加载器 +- [Submit](submit.md) - 提交异步加载请求 +- [Update](update.md) - 更新函数，处理完成的加载请求 +- [IsLoading](isloading.md) - 检查是否有正在加载的资源 +- [GetPendingCount](getpendingcount.md) - 获取待处理加载请求数量 +- [GetProgress](getprogress.md) - 获取整体加载进度 +- [CancelAll](cancelall.md) - 取消所有待处理的加载请求 +- [Cancel](cancel.md) - 取消指定 ID 的加载请求 + ## 实现说明 **注意**: 当前 `AsyncLoader` 的实现为部分完成状态（stub）： - `Initialize()` 工作线程数参数被忽略 - `Submit()` 仅将请求加入队列，不进行实际异步加载 - `Update()` 不执行实际加载，直接调用回调返回成功 -- `QueueCompleted()` 和 `Cancel()` 为空实现 +- `Cancel()` 为空实现 ## 使用示例 diff --git a/docs/api/resources/asyncloader/cancel.md b/docs/api/resources/asyncloader/cancel.md new file mode 100644 index 00000000..41c342f2 --- /dev/null +++ b/docs/api/resources/asyncloader/cancel.md @@ -0,0 +1,27 @@ +# AsyncLoader::Cancel + +```cpp +void Cancel(Core::uint64 requestId) +``` + +取消指定 ID 的加载请求。 + +**参数：** +- `requestId` - 要取消的请求 ID（由 `LoadRequest::requestId` 提供） + +**返回：** 无 + +**注意：** 当前实现未完成此功能。 + +**示例：** + +```cpp +LoadRequest req("textures/player.png", ResourceType::Texture, + [](LoadResult result) { /* ... */ }); + +AsyncLoader::Get().Cancel(req.requestId); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/asyncloader/getpendingcount.md b/docs/api/resources/asyncloader/getpendingcount.md new file mode 100644 index 00000000..126f9b60 --- /dev/null +++ b/docs/api/resources/asyncloader/getpendingcount.md @@ -0,0 +1,24 @@ +# AsyncLoader::GetPendingCount + +```cpp +Core::uint32 GetPendingCount() const +``` + +获取当前待处理的加载请求数量。 + +**参数：** 无 + +**返回：** 待处理加载请求数量 + +**复杂度：** O(1) + +**示例：** + +```cpp +Core::uint32 pending = AsyncLoader::Get().GetPendingCount(); +printf("Pending requests: %u\n", pending); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/asyncloader/initialize.md b/docs/api/resources/asyncloader/initialize.md new file mode 100644 index 00000000..66a3e9a6 --- /dev/null +++ b/docs/api/resources/asyncloader/initialize.md @@ -0,0 +1,24 @@ +# AsyncLoader::Initialize + +```cpp +void Initialize(Core::uint32 workerThreadCount = 2) +``` + +初始化异步加载器。根据 `workerThreadCount` 参数创建相应数量的工作线程用于后台资源加载。 + +**参数：** +- `workerThreadCount` - 工作线程数量，默认为 2 + +**返回：** 无 + +**复杂度：** O(n)，n 为创建的工作线程数 + +**示例：** + +```cpp +AsyncLoader::Get().Initialize(4); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/asyncloader/isloading.md b/docs/api/resources/asyncloader/isloading.md new file mode 100644 index 00000000..80a1c9bc --- /dev/null +++ b/docs/api/resources/asyncloader/isloading.md @@ -0,0 +1,25 @@ +# AsyncLoader::IsLoading + +```cpp +bool IsLoading() const +``` + +检查是否有正在加载的资源。 + +**参数：** 无 + +**返回：** 如果有待处理或完成的加载请求返回 `true`，否则返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +if (AsyncLoader::Get().IsLoading()) { + printf("Resources are still loading...\n"); +} +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/asyncloader/shutdown.md b/docs/api/resources/asyncloader/shutdown.md new file mode 100644 index 00000000..8243730f --- /dev/null +++ b/docs/api/resources/asyncloader/shutdown.md @@ -0,0 +1,23 @@ +# AsyncLoader::Shutdown + +```cpp +void Shutdown() +``` + +关闭异步加载器。取消所有待处理的加载请求并清理资源。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(n) + +**示例：** + +```cpp +AsyncLoader::Get().Shutdown(); +``` + +## 相关文档 + +- [AsyncLoader 总览](asyncloader.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/asyncloader/submit.md b/docs/api/resources/asyncloader/submit.md index e05f329a..b676f86d 100644 --- a/docs/api/resources/asyncloader/submit.md +++ b/docs/api/resources/asyncloader/submit.md @@ -33,3 +33,4 @@ AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture, ## 相关文档 - [AsyncLoader 总览](asyncloader.md) - 返回类总览 +- [Cancel](cancel.md) - 取消指定请求 diff --git a/docs/api/resources/audio-loader/canload.md b/docs/api/resources/audio-loader/canload.md new file mode 100644 index 00000000..b636c8ce --- /dev/null +++ b/docs/api/resources/audio-loader/canload.md @@ -0,0 +1,36 @@ +# AudioLoader::CanLoad + +## 方法签名 + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +## 详细描述 + +根据文件扩展名判断此加载器是否能处理指定路径的资源。检测时先提取路径扩展名（小写），再与支持列表逐一比对。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `path` | `const Containers::String&` | 资源文件的完整或相对路径 | + +## 返回值 + +`bool` - 如果扩展名在支持列表中返回 `true`，否则返回 `false`。 + +## 示例 + +```cpp +AudioLoader loader; + +// 正确识别支持的格式 +bool canLoad1 = loader.CanLoad("assets/audio/bgm.ogg"); // true +bool canLoad2 = loader.CanLoad("sound_effect.wav"); // true +bool canLoad3 = loader.CanLoad("music.mp3"); // true + +// 识别不支持的格式 +bool canLoad4 = loader.CanLoad("video.avi"); // false +bool canLoad5 = loader.CanLoad("document.pdf"); // false +``` diff --git a/docs/api/resources/audio-loader/getdefaultsettings.md b/docs/api/resources/audio-loader/getdefaultsettings.md new file mode 100644 index 00000000..ab40abd3 --- /dev/null +++ b/docs/api/resources/audio-loader/getdefaultsettings.md @@ -0,0 +1,27 @@ +# AudioLoader::GetDefaultSettings + +## 方法签名 + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +## 详细描述 + +返回音频资源的默认导入设置。当前版本音频加载器不使用导入设置，始终返回 `nullptr`。 + +## 返回值 + +`ImportSettings*` - 始终返回 `nullptr`。 + +## 示例 + +```cpp +AudioLoader loader; +ImportSettings* settings = loader.GetDefaultSettings(); + +// 始终为 nullptr +if (settings == nullptr) { + printf("No default settings for AudioLoader\n"); +} +``` diff --git a/docs/api/resources/audio-loader/getsupportedextensions.md b/docs/api/resources/audio-loader/getsupportedextensions.md new file mode 100644 index 00000000..48909a71 --- /dev/null +++ b/docs/api/resources/audio-loader/getsupportedextensions.md @@ -0,0 +1,38 @@ +# AudioLoader::GetSupportedExtensions + +## 方法签名 + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +## 详细描述 + +返回此加载器支持的所有音频文件扩展名。扩展名列表用于 `ResourceManager` 确定给定文件应由哪个加载器处理。 + +## 返回值 + +返回 `Containers::Array`，包含所有支持的扩展名小写形式。 + +**支持的格式：** + +| 扩展名 | 格式 | +|--------|------| +| `wav` | WAV (Waveform Audio File Format) | +| `ogg` | OGG (Ogg Vorbis) | +| `mp3` | MP3 (MPEG-1 Audio Layer III) | +| `flac` | FLAC (Free Lossless Audio Codec) | +| `aiff` | AIFF (Audio Interchange File Format) | +| `aif` | AIFF (旧版扩展名) | + +## 示例 + +```cpp +AudioLoader loader; +Array extensions = loader.GetSupportedExtensions(); + +for (const auto& ext : extensions) { + printf("Supported: %s\n", ext.CStr()); +} +// 输出: wav, ogg, mp3, flac, aiff, aif +``` diff --git a/docs/api/resources/audio-loader/index.md b/docs/api/resources/audio-loader/index.md new file mode 100644 index 00000000..5c92a232 --- /dev/null +++ b/docs/api/resources/audio-loader/index.md @@ -0,0 +1,56 @@ +# AudioLoader + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (Class) + +## 描述 + +音频资源加载器，负责从文件系统加载音频文件并转换为 `AudioClip` 资源。支持 WAV、OGG、MP3、FLAC、AIFF 等常见音频格式。 + +## 概述 + +`AudioLoader` 继承自 `IResourceLoader` 接口，实现音频资源的异步加载与格式解析。内部通过文件扩展名和文件头数据双重检测确定音频格式，确保加载结果的准确性。 + +## 公共方法表格 + +| 方法 | 返回值 | 描述 | +|------|--------|------| +| `AudioLoader()` | - | 构造函数 | +| `~AudioLoader()` | - | 析构函数 | +| `GetResourceType()` | `ResourceType` | 返回资源类型 `AudioClip` | +| `GetSupportedExtensions()` | `Array` | 获取支持的扩展名列表 | +| `CanLoad(path)` | `bool` | 检查是否能够加载指定路径的资源 | +| `Load(path, settings)` | `LoadResult` | 加载音频资源 | +| `GetDefaultSettings()` | `ImportSettings*` | 获取默认导入设置 | + +## 使用示例 + +```cpp +#include "Resources/AudioLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载音频 +ResourceGUID guid = ResourceGUID::Generate("assets/audio/bgm_music.ogg"); +LoadResult result = ResourceManager::Get().Load(guid, "assets/audio/bgm_music.ogg"); + +if (result.IsSuccess()) { + AudioClip* clip = result.GetResource(); + // 使用音频片段 +} +``` + +## 相关文档 + +- [GetSupportedExtensions](getsupportedextensions.md) - 获取支持的音频格式 +- [CanLoad](canload.md) - 检查资源可加载性 +- [Load](load.md) - 加载音频资源 +- [GetDefaultSettings](getdefaultsettings.md) - 获取默认导入设置 +- [IResourceLoader](../resource-loader/resource-loader.md) - 资源加载器基类 +- [AudioClip](../audioclip/audio-clip.md) - 音频资源类型 diff --git a/docs/api/resources/audio-loader/load.md b/docs/api/resources/audio-loader/load.md new file mode 100644 index 00000000..4edab0cb --- /dev/null +++ b/docs/api/resources/audio-loader/load.md @@ -0,0 +1,58 @@ +# AudioLoader::Load + +## 方法签名 + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +## 详细描述 + +从指定路径加载音频文件，读取文件数据后自动检测音频格式，并创建包含完整音频数据的 `AudioClip` 对象。 + +**加载流程：** + +1. 调用 `ReadFileData(path)` 读取文件数据 +2. 若读取失败，返回包含错误信息的 `LoadResult` +3. 调用 `DetectAudioFormat()` 检测音频格式 +4. 创建 `AudioClip` 对象并设置路径、名称、GUID +5. 调用 `SetAudioFormat()` 和 `SetAudioData()` 设置音频属性 +6. 计算内存占用并返回成功结果 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `path` | `const Containers::String&` | 音频文件的完整或相对路径 | +| `settings` | `const ImportSettings*` | 导入设置（当前版本未使用，始终为 `nullptr`） | + +## 返回值 + +`LoadResult` - 成功时包含 `AudioClip*` 指针，失败时包含错误信息字符串。 + +## 示例 + +```cpp +#include "Resources/AudioLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +AudioLoader loader; +LoadResult result = loader.Load("assets/audio/bgm_music.ogg"); + +if (result.IsSuccess()) { + AudioClip* audioClip = result.GetResource(); + + printf("Loaded: %s\n", audioClip->m_name.CStr()); + printf("Format: %d\n", static_cast(audioClip->GetAudioFormat())); + printf("Size: %zu bytes\n", audioClip->m_memorySize); +} else { + printf("Error: %s\n", result.GetError().CStr()); +} +``` + +## 注意事项 + +- 当前实现 `ParseWAVData()` 方法为空，WAV 格式解析逻辑尚未完成 +- `settings` 参数当前版本未使用，保留接口兼容性 diff --git a/docs/api/resources/audioclip/audio-clip.md b/docs/api/resources/audioclip/audio-clip.md new file mode 100644 index 00000000..e1de38c3 --- /dev/null +++ b/docs/api/resources/audioclip/audio-clip.md @@ -0,0 +1,89 @@ +# AudioClip + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。 + +## 概述 + +`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。AudioClip 支持 WAV、OGG、MP3、FLAC 等多种音频格式，可用于音效、音乐、语音和环境音等不同用途。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`AudioClip`](audio-clip.md) | 构造函数 | +| [`~AudioClip`](dtor.md) | 析构函数 | +| [`GetType`](get-type.md) | 获取资源类型 | +| [`GetName`](get-name.md) | 获取音频名称 | +| [`GetPath`](get-path.md) | 获取音频路径 | +| [`GetGUID`](get-guid.md) | 获取全局唯一标识符 | +| [`IsValid`](is-valid.md) | 检查音频是否有效 | +| [`GetMemorySize`](get-memory-size.md) | 获取内存大小 | +| [`Release`](release.md) | 释放音频资源 | +| [`SetAudioData`](setaudiodata.md) | 设置音频数据 | +| [`GetAudioData`](get-audio-data.md) | 获取音频数据 | +| [`SetSampleRate`](set-sample-rate.md) | 设置采样率 | +| [`GetSampleRate`](get-sample-rate.md) | 获取采样率 | +| [`SetChannels`](set-channels.md) | 设置通道数 | +| [`GetChannels`](get-channels.md) | 获取通道数 | +| [`SetBitsPerSample`](set-bits-per-sample.md) | 设置位深度 | +| [`GetBitsPerSample`](get-bits-per-sample.md) | 获取位深度 | +| [`SetDuration`](set-duration.md) | 设置时长 | +| [`GetDuration`](get-duration.md) | 获取时长 | +| [`SetAudioFormat`](set-audio-format.md) | 设置音频格式 | +| [`GetAudioFormat`](get-audio-format.md) | 获取音频格式 | +| [`SetAudioType`](set-audio-type.md) | 设置音频类型 | +| [`GetAudioType`](get-audio-type.md) | 获取音频类型 | +| [`SetIs3D`](set-is-3d.md) | 设置是否为 3D 音频 | +| [`Is3D`](is-3d.md) | 检查是否为 3D 音频 | +| [`SetLoop`](set-loop.md) | 设置是否循环播放 | +| [`IsLoop`](is-loop.md) | 检查是否循环播放 | +| [`GetRHIResource`](get-rhi-resource.md) | 获取 RHI 音频缓冲区 | +| [`SetRHIResource`](set-rhi-resource.md) | 设置 RHI 音频缓冲区 | + +## 使用示例 + +```cpp +#include "Resources/AudioClip.h" +#include "Resources/ResourceManager.h" +#include "Resources/ResourceFileSystem.h" + +using namespace XCEngine::Resources; + +AudioClip* CreateExplosionSound() { + AudioClip* clip = new AudioClip(); + + auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav"); + clip->SetAudioData(wavData); + clip->SetSampleRate(44100); + clip->SetChannels(2); + clip->SetBitsPerSample(16); + clip->SetDuration(1.5f); + clip->SetAudioFormat(AudioFormat::WAV); + clip->SetAudioType(AudioType::SoundEffect); + clip->SetLoop(false); + clip->SetIs3D(false); + + return clip; +} + +void PlaySoundEffect() { + ResourceHandle sfx = ResourceManager::Get().Load("sounds/explosion.wav"); + + if (sfx->IsValid()) { + uint32_t sampleRate = sfx->GetSampleRate(); + float duration = sfx->GetDuration(); + bool loop = sfx->IsLoop(); + AudioFormat format = sfx->GetAudioFormat(); + AudioType type = sfx->GetAudioType(); + } +} +``` + +## 相关文档 + +- [IResource](../iresource/iresource.md) - 资源基类 +- [Resources](../resources.md) - 资源模块总览 diff --git a/docs/api/resources/audioclip/audioclip.md b/docs/api/resources/audioclip/audioclip.md index ada1c2b9..e24ca8ef 100644 --- a/docs/api/resources/audioclip/audioclip.md +++ b/docs/api/resources/audioclip/audioclip.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/AudioClip.h` + **描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。 ## 概述 @@ -13,7 +15,7 @@ ## 头文件 ```cpp -#include +#include "Resources/AudioClip.h" ``` ## 枚举类型 @@ -59,7 +61,7 @@ | 方法 | 描述 | |------|------| -| `void SetAudioData(const Containers::Array& data)` | 设置音频数据（根据采样率、通道数、位深度自动计算时长） | +| `void SetAudioData(const Containers::Array& data)` | 设置音频数据（需先设置采样率、通道数、位深度，自动计算时长） | | `const Containers::Array& GetAudioData() const` | 获取音频数据指针 | ## 实现说明 diff --git a/docs/api/resources/audioclip/ctor.md b/docs/api/resources/audioclip/ctor.md new file mode 100644 index 00000000..3f0d631b --- /dev/null +++ b/docs/api/resources/audioclip/ctor.md @@ -0,0 +1,23 @@ +# AudioClip::AudioClip + +```cpp +AudioClip() +``` + +构造一个新的 `AudioClip` 实例。 + +**线程安全：** ✅ + +**示例：** + +```cpp +#include "Resources/AudioClip.h" + +using namespace XCEngine::Resources; + +AudioClip* clip = new AudioClip(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 diff --git a/docs/api/resources/audioclip/dtor.md b/docs/api/resources/audioclip/dtor.md new file mode 100644 index 00000000..d1aad6bf --- /dev/null +++ b/docs/api/resources/audioclip/dtor.md @@ -0,0 +1,26 @@ +# AudioClip::~AudioClip + +```cpp +virtual ~AudioClip() override +``` + +销毁 `AudioClip` 实例并释放相关资源。 + +**线程安全：** ❌ （不应在多线程中同时访问正在销毁的对象） + +**示例：** + +```cpp +#include "Resources/AudioClip.h" + +using namespace XCEngine::Resources; + +{ + AudioClip clip; + clip.SetAudioFormat(AudioFormat::WAV); +} +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 diff --git a/docs/api/resources/audioclip/get-audio-data.md b/docs/api/resources/audioclip/get-audio-data.md new file mode 100644 index 00000000..38b86f7e --- /dev/null +++ b/docs/api/resources/audioclip/get-audio-data.md @@ -0,0 +1,29 @@ +# AudioClip::GetAudioData + +```cpp +const Containers::Array& GetAudioData() const +``` + +获取音频的原始样本数据。 + +**返回：** 音频数据字节数组的常量引用 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav"); +clip.SetAudioData(wavData); + +const Containers::Array& data = clip.GetAudioData(); +size_t dataSize = data.Size(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetAudioData](setaudiodata.md) - 设置音频数据 diff --git a/docs/api/resources/audioclip/get-audio-format.md b/docs/api/resources/audioclip/get-audio-format.md new file mode 100644 index 00000000..e7b4a62f --- /dev/null +++ b/docs/api/resources/audioclip/get-audio-format.md @@ -0,0 +1,26 @@ +# AudioClip::GetAudioFormat + +```cpp +AudioFormat GetAudioFormat() const +``` + +获取音频的格式。 + +**返回：** `AudioFormat` 枚举值 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetAudioFormat(AudioFormat::OGG); +AudioFormat format = clip.GetAudioFormat(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetAudioFormat](set-audio-format.md) - 设置音频格式 diff --git a/docs/api/resources/audioclip/get-audio-type.md b/docs/api/resources/audioclip/get-audio-type.md new file mode 100644 index 00000000..28ef80e9 --- /dev/null +++ b/docs/api/resources/audioclip/get-audio-type.md @@ -0,0 +1,26 @@ +# AudioClip::GetAudioType + +```cpp +AudioType GetAudioType() const +``` + +获取音频的类型。 + +**返回：** `AudioType` 枚举值 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetAudioType(AudioType::Voice); +AudioType type = clip.GetAudioType(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetAudioType](set-audio-type.md) - 设置音频类型 diff --git a/docs/api/resources/audioclip/get-bits-per-sample.md b/docs/api/resources/audioclip/get-bits-per-sample.md new file mode 100644 index 00000000..445297f9 --- /dev/null +++ b/docs/api/resources/audioclip/get-bits-per-sample.md @@ -0,0 +1,26 @@ +# AudioClip::GetBitsPerSample + +```cpp +Core::uint32 GetBitsPerSample() const +``` + +获取音频的位深度。 + +**返回：** 位深度（8、16、24、32） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetBitsPerSample(16); +uint32_t bits = clip.GetBitsPerSample(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetBitsPerSample](set-bits-per-sample.md) - 设置位深度 diff --git a/docs/api/resources/audioclip/get-channels.md b/docs/api/resources/audioclip/get-channels.md new file mode 100644 index 00000000..21cdc7bb --- /dev/null +++ b/docs/api/resources/audioclip/get-channels.md @@ -0,0 +1,26 @@ +# AudioClip::GetChannels + +```cpp +Core::uint32 GetChannels() const +``` + +获取音频的通道数。 + +**返回：** 通道数（1=单声道，2=立体声） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetChannels(2); +uint32_t channels = clip.GetChannels(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetChannels](set-channels.md) - 设置通道数 diff --git a/docs/api/resources/audioclip/get-duration.md b/docs/api/resources/audioclip/get-duration.md new file mode 100644 index 00000000..ae364376 --- /dev/null +++ b/docs/api/resources/audioclip/get-duration.md @@ -0,0 +1,26 @@ +# AudioClip::GetDuration + +```cpp +float GetDuration() const +``` + +获取音频的时长。 + +**返回：** 时长（秒） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetDuration(3.0f); +float duration = clip.GetDuration(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetDuration](set-duration.md) - 设置时长 diff --git a/docs/api/resources/audioclip/get-guid.md b/docs/api/resources/audioclip/get-guid.md new file mode 100644 index 00000000..3bcddc07 --- /dev/null +++ b/docs/api/resources/audioclip/get-guid.md @@ -0,0 +1,25 @@ +# AudioClip::GetGUID + +```cpp +ResourceGUID GetGUID() const override +``` + +获取音频资源的全局唯一标识符。 + +**返回：** 资源 GUID + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +ResourceGUID guid = clip.GetGUID(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/get-memory-size.md b/docs/api/resources/audioclip/get-memory-size.md new file mode 100644 index 00000000..f4e442f7 --- /dev/null +++ b/docs/api/resources/audioclip/get-memory-size.md @@ -0,0 +1,25 @@ +# AudioClip::GetMemorySize + +```cpp +size_t GetMemorySize() const override +``` + +获取音频资源占用的内存大小。 + +**返回：** 内存大小（字节） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +size_t memSize = clip.GetMemorySize(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/get-name.md b/docs/api/resources/audioclip/get-name.md new file mode 100644 index 00000000..a670d989 --- /dev/null +++ b/docs/api/resources/audioclip/get-name.md @@ -0,0 +1,25 @@ +# AudioClip::GetName + +```cpp +const Containers::String& GetName() const override +``` + +获取音频资源的名称。 + +**返回：** 音频名称的常量引用 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +Containers::String name = clip.GetName(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/get-path.md b/docs/api/resources/audioclip/get-path.md new file mode 100644 index 00000000..78e0a142 --- /dev/null +++ b/docs/api/resources/audioclip/get-path.md @@ -0,0 +1,25 @@ +# AudioClip::GetPath + +```cpp +const Containers::String& GetPath() const override +``` + +获取音频资源的路径。 + +**返回：** 音频路径的常量引用 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +Containers::String path = clip.GetPath(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/get-rhi-resource.md b/docs/api/resources/audioclip/get-rhi-resource.md new file mode 100644 index 00000000..875922f4 --- /dev/null +++ b/docs/api/resources/audioclip/get-rhi-resource.md @@ -0,0 +1,27 @@ +# AudioClip::GetRHIResource + +```cpp +class IRHIAudioBuffer* GetRHIResource() const +``` + +获取 RHI 音频缓冲区资源指针。 + +**返回：** `IRHIAudioBuffer` 指针，如果未设置则返回 `nullptr` + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +IRHIAudioBuffer* rhi = clip.GetRHIResource(); +if (rhi != nullptr) { +} +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetRHIResource](set-rhi-resource.md) - 设置 RHI 音频缓冲区 diff --git a/docs/api/resources/audioclip/get-sample-rate.md b/docs/api/resources/audioclip/get-sample-rate.md new file mode 100644 index 00000000..e396f439 --- /dev/null +++ b/docs/api/resources/audioclip/get-sample-rate.md @@ -0,0 +1,26 @@ +# AudioClip::GetSampleRate + +```cpp +Core::uint32 GetSampleRate() const +``` + +获取音频的采样率。 + +**返回：** 采样率（Hz） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetSampleRate(48000); +uint32_t rate = clip.GetSampleRate(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetSampleRate](set-sample-rate.md) - 设置采样率 diff --git a/docs/api/resources/audioclip/get-type.md b/docs/api/resources/audioclip/get-type.md new file mode 100644 index 00000000..9f201fda --- /dev/null +++ b/docs/api/resources/audioclip/get-type.md @@ -0,0 +1,25 @@ +# AudioClip::GetType + +```cpp +ResourceType GetType() const override +``` + +返回资源的类型标识符。 + +**返回：** `ResourceType::AudioClip` + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +ResourceType type = clip.GetType(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/is-3d.md b/docs/api/resources/audioclip/is-3d.md new file mode 100644 index 00000000..d31a7d88 --- /dev/null +++ b/docs/api/resources/audioclip/is-3d.md @@ -0,0 +1,26 @@ +# AudioClip::Is3D + +```cpp +bool Is3D() const +``` + +检查音频是否为 3D 音频。 + +**返回：** 如果是 3D 音频返回 `true`，否则返回 `false` + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetIs3D(false); +bool is3D = clip.Is3D(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetIs3D](set-is-3d.md) - 设置是否为 3D 音频 diff --git a/docs/api/resources/audioclip/is-loop.md b/docs/api/resources/audioclip/is-loop.md new file mode 100644 index 00000000..0f71430b --- /dev/null +++ b/docs/api/resources/audioclip/is-loop.md @@ -0,0 +1,26 @@ +# AudioClip::IsLoop + +```cpp +bool IsLoop() const +``` + +检查音频是否循环播放。 + +**返回：** 如果循环播放返回 `true`，否则返回 `false` + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetLoop(false); +bool loop = clip.IsLoop(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [SetLoop](set-loop.md) - 设置是否循环播放 diff --git a/docs/api/resources/audioclip/is-valid.md b/docs/api/resources/audioclip/is-valid.md new file mode 100644 index 00000000..b49b5b85 --- /dev/null +++ b/docs/api/resources/audioclip/is-valid.md @@ -0,0 +1,25 @@ +# AudioClip::IsValid + +```cpp +bool IsValid() const override +``` + +检查音频资源是否有效。 + +**返回：** 如果资源有效返回 `true`，否则返回 `false` + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +bool valid = clip.IsValid(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/audioclip/release.md b/docs/api/resources/audioclip/release.md new file mode 100644 index 00000000..838d32c8 --- /dev/null +++ b/docs/api/resources/audioclip/release.md @@ -0,0 +1,36 @@ +# AudioClip::Release + +```cpp +void Release() +``` + +释放音频资源，释放存储的音频数据并清除 RHI 资源引用。 + +## 详细描述 + +调用此方法后： +1. 清除音频数据（调用 `m_audioData.Clear()`） +2. 将 RHI 资源引用置为 `nullptr` +3. 将 `m_isValid` 标记为 `false` + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +ResourceHandle sfx = ResourceManager::Get().Load("sounds/explosion.wav"); +sfx->Release(); +if (!sfx->IsValid()) { + // 音频已释放 +} +``` + +## 相关文档 + +- [AudioClip 总览](audioclip.md) - 返回类总览 diff --git a/docs/api/resources/audioclip/set-audio-format.md b/docs/api/resources/audioclip/set-audio-format.md new file mode 100644 index 00000000..3736ed7b --- /dev/null +++ b/docs/api/resources/audioclip/set-audio-format.md @@ -0,0 +1,27 @@ +# AudioClip::SetAudioFormat + +```cpp +void SetAudioFormat(AudioFormat format) +``` + +设置音频的格式。 + +**参数：** +- `format` - 音频格式（`AudioFormat::Unknown`、`AudioFormat::WAV`、`AudioFormat::OGG`、`AudioFormat::MP3`、`AudioFormat::FLAC`） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetAudioFormat(AudioFormat::WAV); +AudioFormat format = clip.GetAudioFormat(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetAudioFormat](get-audio-format.md) - 获取音频格式 diff --git a/docs/api/resources/audioclip/set-audio-type.md b/docs/api/resources/audioclip/set-audio-type.md new file mode 100644 index 00000000..751fe75c --- /dev/null +++ b/docs/api/resources/audioclip/set-audio-type.md @@ -0,0 +1,27 @@ +# AudioClip::SetAudioType + +```cpp +void SetAudioType(AudioType type) +``` + +设置音频的类型。 + +**参数：** +- `type` - 音频类型（`AudioType::SoundEffect`、`AudioType::Music`、`AudioType::Voice`、`AudioType::Ambient`） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetAudioType(AudioType::Music); +AudioType type = clip.GetAudioType(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetAudioType](get-audio-type.md) - 获取音频类型 diff --git a/docs/api/resources/audioclip/set-bits-per-sample.md b/docs/api/resources/audioclip/set-bits-per-sample.md new file mode 100644 index 00000000..cd18e58b --- /dev/null +++ b/docs/api/resources/audioclip/set-bits-per-sample.md @@ -0,0 +1,27 @@ +# AudioClip::SetBitsPerSample + +```cpp +void SetBitsPerSample(Core::uint32 bits) +``` + +设置音频的位深度。 + +**参数：** +- `bits` - 位深度（8、16、24、32） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetBitsPerSample(16); +uint32_t bits = clip.GetBitsPerSample(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetBitsPerSample](get-bits-per-sample.md) - 获取位深度 diff --git a/docs/api/resources/audioclip/set-channels.md b/docs/api/resources/audioclip/set-channels.md new file mode 100644 index 00000000..9035e43e --- /dev/null +++ b/docs/api/resources/audioclip/set-channels.md @@ -0,0 +1,27 @@ +# AudioClip::SetChannels + +```cpp +void SetChannels(Core::uint32 channels) +``` + +设置音频的通道数。 + +**参数：** +- `channels` - 通道数（1=单声道，2=立体声） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetChannels(2); +uint32_t channels = clip.GetChannels(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetChannels](get-channels.md) - 获取通道数 diff --git a/docs/api/resources/audioclip/set-duration.md b/docs/api/resources/audioclip/set-duration.md new file mode 100644 index 00000000..8940cc55 --- /dev/null +++ b/docs/api/resources/audioclip/set-duration.md @@ -0,0 +1,27 @@ +# AudioClip::SetDuration + +```cpp +void SetDuration(float seconds) +``` + +设置音频的时长。 + +**参数：** +- `seconds` - 时长（秒） + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetDuration(2.5f); +float duration = clip.GetDuration(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetDuration](get-duration.md) - 获取时长 diff --git a/docs/api/resources/audioclip/set-is-3d.md b/docs/api/resources/audioclip/set-is-3d.md new file mode 100644 index 00000000..d7b32e90 --- /dev/null +++ b/docs/api/resources/audioclip/set-is-3d.md @@ -0,0 +1,27 @@ +# AudioClip::SetIs3D + +```cpp +void SetIs3D(bool is3D) +``` + +设置音频是否为 3D 音频。 + +**参数：** +- `is3D` - 是否为 3D 音频 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetIs3D(true); +bool is3D = clip.Is3D(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [Is3D](is-3d.md) - 检查是否为 3D 音频 diff --git a/docs/api/resources/audioclip/set-loop.md b/docs/api/resources/audioclip/set-loop.md new file mode 100644 index 00000000..4d22bf5d --- /dev/null +++ b/docs/api/resources/audioclip/set-loop.md @@ -0,0 +1,27 @@ +# AudioClip::SetLoop + +```cpp +void SetLoop(bool loop) +``` + +设置音频是否循环播放。 + +**参数：** +- `loop` - 是否循环播放 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetLoop(true); +bool loop = clip.IsLoop(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [IsLoop](is-loop.md) - 检查是否循环播放 diff --git a/docs/api/resources/audioclip/set-rhi-resource.md b/docs/api/resources/audioclip/set-rhi-resource.md new file mode 100644 index 00000000..4fcc9311 --- /dev/null +++ b/docs/api/resources/audioclip/set-rhi-resource.md @@ -0,0 +1,28 @@ +# AudioClip::SetRHIResource + +```cpp +void SetRHIResource(class IRHIAudioBuffer* resource) +``` + +设置 RHI 音频缓冲区资源。 + +**参数：** +- `resource` - `IRHIAudioBuffer` 指针 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +IRHIAudioBuffer* rhiBuffer = CreateRHIBuffer(); +clip.SetRHIResource(rhiBuffer); +IRHIAudioBuffer* rhi = clip.GetRHIResource(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetRHIResource](get-rhi-resource.md) - 获取 RHI 音频缓冲区 diff --git a/docs/api/resources/audioclip/set-sample-rate.md b/docs/api/resources/audioclip/set-sample-rate.md new file mode 100644 index 00000000..d920a18d --- /dev/null +++ b/docs/api/resources/audioclip/set-sample-rate.md @@ -0,0 +1,27 @@ +# AudioClip::SetSampleRate + +```cpp +void SetSampleRate(Core::uint32 rate) +``` + +设置音频的采样率。 + +**参数：** +- `rate` - 采样率（Hz），常用值为 44100、48000 等 + +**线程安全：** ✅ + +**示例：** + +```cpp +using namespace XCEngine::Resources; + +AudioClip clip; +clip.SetSampleRate(44100); +uint32_t rate = clip.GetSampleRate(); +``` + +## 相关文档 + +- [AudioClip 总览](audio-clip.md) - 返回类总览 +- [GetSampleRate](get-sample-rate.md) - 获取采样率 diff --git a/docs/api/resources/dependencygraph/dependencygraph.md b/docs/api/resources/dependencygraph/dependencygraph.md index 932fbbf0..8bfcce8c 100644 --- a/docs/api/resources/dependencygraph/dependencygraph.md +++ b/docs/api/resources/dependencygraph/dependencygraph.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/DependencyGraph.h` + **描述**: 资源依赖图管理器，负责跟踪资源之间的依赖关系、引用计数和拓扑排序。 ## 概述 diff --git a/docs/api/resources/filearchive/close.md b/docs/api/resources/filearchive/close.md new file mode 100644 index 00000000..0d106047 --- /dev/null +++ b/docs/api/resources/filearchive/close.md @@ -0,0 +1,22 @@ +# FileArchive::Close + +关闭归档。 + +## 方法签名 + +```cpp +void Close() override; +``` + +## 详细描述 + +关闭归档并重置内部状态。清空归档路径并标记为无效状态。 + +## 示例 + +```cpp +FileArchive archive; +archive.Open("resources/textures/"); +// 使用归档... +archive.Close(); +``` diff --git a/docs/api/resources/filearchive/enumerate.md b/docs/api/resources/filearchive/enumerate.md new file mode 100644 index 00000000..70b0c185 --- /dev/null +++ b/docs/api/resources/filearchive/enumerate.md @@ -0,0 +1,31 @@ +# FileArchive::Enumerate + +枚举匹配的文件。 + +## 方法签名 + +```cpp +void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const override; +``` + +## 详细描述 + +枚举归档目录中与指定模式匹配的文件。当前实现为 stub，仅清空输出数组，未实现实际的模式匹配功能。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `pattern` | `const Containers::String&` | 文件匹配模式（如 `*.png`、`textures/*.jpg`） | +| `outFiles` | `Containers::Array&` | 输出容器，接收匹配的文件路径列表 | + +## 示例 + +```cpp +FileArchive archive; +archive.Open("resources/"); + +Containers::Array files; +archive.Enumerate("*.png", files); +// 注意：当前实现返回空数组 +``` diff --git a/docs/api/resources/filearchive/exists.md b/docs/api/resources/filearchive/exists.md new file mode 100644 index 00000000..75f06a43 --- /dev/null +++ b/docs/api/resources/filearchive/exists.md @@ -0,0 +1,36 @@ +# FileArchive::Exists + +检查文件是否存在。 + +## 方法签名 + +```cpp +bool Exists(const Containers::String& fileName) const override; +``` + +## 详细描述 + +检查归档内是否存在指定文件。文件路径是相对于归档目录的路径。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `fileName` | `const Containers::String&` | 要检查的文件名（相对于归档路径） | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | 文件存在返回 `true`，否则返回 `false` | + +## 示例 + +```cpp +FileArchive archive; +archive.Open("resources/"); + +if (archive.Exists("textures/player.png")) { + // 文件存在 +} +``` diff --git a/docs/api/resources/filearchive/filearchive.md b/docs/api/resources/filearchive/filearchive.md index 7138ebb5..ca7bf48f 100644 --- a/docs/api/resources/filearchive/filearchive.md +++ b/docs/api/resources/filearchive/filearchive.md @@ -2,19 +2,17 @@ **命名空间**: `XCEngine::Resources` -**类型**: `class` (extends IArchive) +**类型**: `class` -**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。 +**头文件**: `XCEngine/Resources/FileArchive.h` + +**继承自**: `IArchive` + +**描述**: 文件归档读取器，将文件系统目录作为虚拟归档进行访问。 ## 概述 -`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。 - -## 头文件 - -```cpp -#include -``` +`FileArchive` 实现了 `IArchive` 接口，用于将文件系统目录作为虚拟归档进行访问。它维护已打开目录的路径和有效性状态，支持读取文件、检查存在性、获取文件大小等操作。 ## 继承关系 @@ -25,60 +23,53 @@ IArchive ## 公共方法 -### 构造与析构 - | 方法 | 描述 | |------|------| -| `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` | 枚举归档内匹配的文件（当前为 stub） | -| `bool IsValid() const override` | 检查归档是否有效 | - -## 实现说明 - -**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。 - -### 访问器 - -| 方法 | 描述 | -|------|------| -| `const Containers::String& GetPath() const` | 获取归档文件路径 | +| [`FileArchive()`](filearchive.md) | 默认构造 | +| [`~FileArchive()`](filearchive.md) | 析构函数，自动关闭归档 | +| [`Open(...)`](open.md) | 打开归档目录 | +| [`Close()`](close.md) | 关闭归档 | +| [`Read(...)`](read.md) | 读取文件数据 | +| [`GetSize(...)`](getsize.md) | 获取文件大小 | +| [`Exists(...)`](exists.md) | 检查文件是否存在 | +| [`Enumerate(...)`](enumerate.md) | 枚举匹配的文件（暂未实现） | +| [`IsValid()`](filearchive.md) | 检查归档是否有效 | +| [`GetPath()`](filearchive.md) | 获取归档路径 | ## 使用示例 ```cpp +#include + +// 创建并打开归档 FileArchive archive; -if (archive.Open("data/resources.pak")) { +if (archive.Open("resources/textures/")) { // 检查文件是否存在 - if (archive.Exists("textures/player.png")) { + if (archive.Exists("player.png")) { // 获取文件大小 - size_t size = archive.GetSize("textures/player.png"); + size_t size = archive.GetSize("player.png"); // 读取文件内容 Containers::Array buffer(size); - archive.Read("textures/player.png", buffer.Data(), size, 0); + if (archive.Read("player.png", buffer.Data(), size, 0)) { + // 处理文件数据 + } } - // 枚举文件 + // 枚举匹配的文件 Containers::Array files; - archive.Enumerate("textures/*.png", files); + archive.Enumerate("*.png", files); archive.Close(); } ``` +## 实现说明 + +- `Enumerate()` 当前为 stub，仅清空输出数组，未实现模式匹配功能。 + ## 相关文档 -- [IArchive](../filesystem/filesystem.md) - 归档接口 -- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统 -- [Resources 总览](../resources.md) - 返回模块总览 +- [Resources 模块总览](../resources.md) - 返回模块总览 +- [IArchive](../resourcefilesystem/resourcefilesystem.md) - 归档接口定义 +- [ResourceFileSystem](../resourcefilesystem/resourcefilesystem.md) - 资源文件系统 diff --git a/docs/api/resources/filearchive/getsize.md b/docs/api/resources/filearchive/getsize.md new file mode 100644 index 00000000..3f42de9e --- /dev/null +++ b/docs/api/resources/filearchive/getsize.md @@ -0,0 +1,37 @@ +# FileArchive::GetSize + +获取文件大小。 + +## 方法签名 + +```cpp +size_t GetSize(const Containers::String& fileName) const override; +``` + +## 详细描述 + +获取归档内指定文件的字节大小。文件路径是相对于归档目录的路径。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `fileName` | `const Containers::String&` | 要查询的文件名（相对于归档路径） | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `size_t` | 文件字节大小，文件不存在或归档无效时返回 0 | + +## 示例 + +```cpp +FileArchive archive; +archive.Open("resources/"); + +size_t size = archive.GetSize("textures/player.png"); +if (size > 0) { + // 文件存在，准备读取 +} +``` diff --git a/docs/api/resources/filearchive/open.md b/docs/api/resources/filearchive/open.md new file mode 100644 index 00000000..5354a867 --- /dev/null +++ b/docs/api/resources/filearchive/open.md @@ -0,0 +1,34 @@ +# FileArchive::Open + +打开归档目录。 + +## 方法签名 + +```cpp +bool Open(const Containers::String& path) override; +``` + +## 详细描述 + +打开指定路径的目录作为归档。归档路径可以是绝对路径或相对路径。方法会设置内部路径并标记归档为有效状态。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `path` | `const Containers::String&` | 归档目录路径 | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | 始终返回 `true`。当前实现不验证路径是否真实存在。 | + +## 示例 + +```cpp +FileArchive archive; +if (archive.Open("resources/textures/")) { + // 归档已打开 +} +``` diff --git a/docs/api/resources/filearchive/read.md b/docs/api/resources/filearchive/read.md new file mode 100644 index 00000000..c27020bf --- /dev/null +++ b/docs/api/resources/filearchive/read.md @@ -0,0 +1,42 @@ +# FileArchive::Read + +读取文件数据。 + +## 方法签名 + +```cpp +bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override; +``` + +## 详细描述 + +从归档中读取指定文件的全部或部分内容。文件路径是相对于归档目录的路径。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `fileName` | `const Containers::String&` | 要读取的文件名（相对于归档路径） | +| `buffer` | `void*` | 读取数据的目标缓冲区 | +| `size` | `size_t` | 要读取的字节数 | +| `offset` | `size_t` | 文件内起始偏移位置 | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | 读取成功返回 `true`，失败返回 `false` | + +## 示例 + +```cpp +FileArchive archive; +archive.Open("resources/"); + +size_t fileSize = archive.GetSize("textures/player.png"); +Containers::Array buffer(fileSize); + +if (archive.Read("textures/player.png", buffer.Data(), fileSize, 0)) { + // 文件读取成功 +} +``` diff --git a/docs/api/resources/filesystem/filesystem.md b/docs/api/resources/filesystem/filesystem.md index 29208ad5..0692d409 100644 --- a/docs/api/resources/filesystem/filesystem.md +++ b/docs/api/resources/filesystem/filesystem.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/FileSystem.h` + **描述**: 资源文件系统，负责资源文件的查找、读取和虚拟文件系统（支持目录和归档包）管理。 ## 概述 @@ -46,16 +48,16 @@ | 方法 | 描述 | |------|------| -| `void Initialize(const Containers::String& rootPath)` | 初始化，设置资源根目录 | -| `void Shutdown()` | 关闭，释放所有归档 | -| `bool AddArchive(const Containers::String& archivePath)` | 添加归档包（优先查找） | -| `bool AddDirectory(const Containers::String& directoryPath)` | 添加资源目录 | -| `void RemoveArchive(const Containers::String& archivePath)` | 移除归档包 | -| `bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const` | 查找资源的绝对路径 | -| `bool Exists(const Containers::String& relativePath) const` | 检查资源是否存在 | -| `Containers::Array ReadResource(const Containers::String& relativePath) const` | 读取资源文件内容（字节数组） | -| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） | -| `void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） | +| `Initialize()` | 初始化，设置资源根目录 | +| `Shutdown()` | 关闭，释放所有归档 | +| [`AddArchive`](addarchive.md) | 添加归档包（优先查找） | +| [`AddDirectory`](adddirectory.md) | 添加资源目录 | +| [`RemoveArchive`](removearchive.md) | 移除归档包 | +| [`FindResource`](findresource.md) | 查找资源的绝对路径 | +| [`Exists`](exists.md) | 检查资源是否存在 | +| [`ReadResource`](readresource.md) | 读取资源文件内容（字节数组） | +| [`GetResourceInfo`](getresourceinfo.md) | 获取资源信息 | +| [`EnumerateResources`](enumerateresources.md) | 枚举匹配的资源 | ## 实现说明 diff --git a/docs/api/resources/iloader/getresourcetype.md b/docs/api/resources/iloader/getresourcetype.md new file mode 100644 index 00000000..9a7d8be0 --- /dev/null +++ b/docs/api/resources/iloader/getresourcetype.md @@ -0,0 +1,23 @@ +# IResourceLoader::GetResourceType + +```cpp +virtual ResourceType GetResourceType() const = 0 +``` + +获取此加载器所支持的资源类型。纯虚方法，子类必须实现。 + +**参数：** 无 + +**返回：** `ResourceType` 枚举值，标识资源类型（如 `ResourceType::Texture`、`ResourceType::Mesh` 等） + +**示例：** + +```cpp +ResourceType TextureLoader::GetResourceType() const { + return ResourceType::Texture; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](iloader.md) - 返回类总览 diff --git a/docs/api/resources/iloader/iloader.md b/docs/api/resources/iloader/iloader.md index f893c998..9f6f95c5 100644 --- a/docs/api/resources/iloader/iloader.md +++ b/docs/api/resources/iloader/iloader.md @@ -4,6 +4,8 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/Resources/ILoader.h` + **描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。 ## 概述 @@ -34,22 +36,22 @@ struct LoadResult { | 方法 | 描述 | |------|------| -| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 | -| `Containers::Array GetSupportedExtensions() const` | 获取支持的文件扩展名列表 | -| `bool CanLoad(const Containers::String& path) const` | 检查此加载器是否能加载指定路径 | -| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 | +| [`GetResourceType`](getresourcetype.md) | 获取此加载器支持的资源类型 | +| [`GetSupportedExtensions`](getsupportedextensions.md) | 获取支持的文件扩展名列表 | +| [`CanLoad`](canload.md) | 检查此加载器是否能加载指定路径 | +| [`GetDefaultSettings`](getdefaultsettings.md) | 获取默认导入设置 | ### 同步加载 | 方法 | 描述 | |------|------| -| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 同步加载资源 | +| [`Load`](load.md) | 同步加载资源 | ### 异步加载 | 方法 | 描述 | |------|------| -| `void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function callback)` | 异步加载资源（内部默认实现调用同步 Load） | +| [`LoadAsync`](loadasync.md) | 异步加载资源（带默认实现，子类可重写） | ### 辅助方法（受保护） diff --git a/docs/api/resources/iresource/getguid.md b/docs/api/resources/iresource/getguid.md new file mode 100644 index 00000000..da88fc0f --- /dev/null +++ b/docs/api/resources/iresource/getguid.md @@ -0,0 +1,29 @@ +# IResource::GetGUID + +```cpp +virtual ResourceGUID GetGUID() const = 0 +``` + +获取全局唯一标识符。纯虚方法，由具体资源类实现，返回资源的唯一 GUID。 + +**参数：** 无 + +**返回：** `ResourceGUID` - 资源的全局唯一标识符 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/player.mat"); +ResourceGUID guid = mat->GetGUID(); +// guid 是根据路径生成的唯一标识符 +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/iresource/getmemorysize.md b/docs/api/resources/iresource/getmemorysize.md new file mode 100644 index 00000000..3d97c734 --- /dev/null +++ b/docs/api/resources/iresource/getmemorysize.md @@ -0,0 +1,29 @@ +# IResource::GetMemorySize + +```cpp +virtual size_t GetMemorySize() const = 0 +``` + +获取资源占用的内存大小。纯虚方法，由具体资源类实现，返回资源在内存中的字节数。 + +**参数：** 无 + +**返回：** `size_t` - 资源占用的内存大小（字节） + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); +size_t size = mesh->GetMemorySize(); +// size == 内存占用字节数 +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/iresource/getname.md b/docs/api/resources/iresource/getname.md new file mode 100644 index 00000000..57b9fbb0 --- /dev/null +++ b/docs/api/resources/iresource/getname.md @@ -0,0 +1,29 @@ +# IResource::GetName + +```cpp +virtual const Containers::String& GetName() const = 0 +``` + +获取资源名称。纯虚方法，由具体资源类实现，返回资源的显示名称。 + +**参数：** 无 + +**返回：** `const Containers::String&` - 资源名称的常量引用 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); +const Containers::String& name = mesh->GetName(); +// name == "player" +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/iresource/getpath.md b/docs/api/resources/iresource/getpath.md new file mode 100644 index 00000000..ab697aca --- /dev/null +++ b/docs/api/resources/iresource/getpath.md @@ -0,0 +1,29 @@ +# IResource::GetPath + +```cpp +virtual const Containers::String& GetPath() const = 0 +``` + +获取资源路径。纯虚方法，由具体资源类实现，返回资源在文件系统中的相对路径。 + +**参数：** 无 + +**返回：** `const Containers::String&` - 资源路径的常量引用 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); +const Containers::String& path = tex->GetPath(); +// path == "textures/player.png" +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 \ No newline at end of file diff --git a/docs/api/resources/iresource/gettype.md b/docs/api/resources/iresource/gettype.md new file mode 100644 index 00000000..eded9782 --- /dev/null +++ b/docs/api/resources/iresource/gettype.md @@ -0,0 +1,30 @@ +# IResource::GetType + +```cpp +virtual ResourceType GetType() const = 0 +``` + +获取资源类型。纯虚方法，由具体资源类实现，返回该资源所属的类型枚举值。 + +**参数：** 无 + +**返回：** `ResourceType` - 资源类型枚举 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); +ResourceType type = tex->GetType(); +// type == ResourceType::Texture +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 +- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义 \ No newline at end of file diff --git a/docs/api/resources/iresource/initialize.md b/docs/api/resources/iresource/initialize.md index 641b9588..c5f8e825 100644 --- a/docs/api/resources/iresource/initialize.md +++ b/docs/api/resources/iresource/initialize.md @@ -11,6 +11,10 @@ void Initialize(const ConstructParams& params) **返回：** 无 +**异常：** 无 + +**线程安全：** ❌ + **复杂度：** O(1) **示例：** diff --git a/docs/api/resources/iresource/iresource.md b/docs/api/resources/iresource/iresource.md index 2ce20d72..784331e5 100644 --- a/docs/api/resources/iresource/iresource.md +++ b/docs/api/resources/iresource/iresource.md @@ -4,6 +4,8 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/Resources/IResource.h` + **描述**: 资源基类接口，所有具体资源类型（Texture、Mesh、Material 等）都必须继承自此类。 ## 概述 @@ -14,25 +16,24 @@ | 方法 | 描述 | |------|------| -| `ResourceType GetType() const` | 获取资源类型 | -| `const Containers::String& GetName() const` | 获取资源名称 | -| `const Containers::String& GetPath() const` | 获取资源路径 | -| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 | -| `bool IsValid() const` | 检查资源是否有效 | -| `size_t GetMemorySize() const` | 获取资源占用的内存大小（字节） | -| `void Release()` | 释放资源引用 | -| `void Initialize(const ConstructParams& params)` | 使用构造参数初始化资源 | -| `void SetInvalid()` | 将资源标记为无效 | +| [`GetType()`](gettype.md) | 获取资源类型 | +| [`GetName()`](getname.md) | 获取资源名称 | +| [`GetPath()`](getpath.md) | 获取资源路径 | +| [`GetGUID()`](getguid.md) | 获取全局唯一标识符 | +| [`IsValid()`](isvalid.md) | 检查资源是否有效 | +| [`GetMemorySize()`](getmemorysize.md) | 获取资源占用的内存大小（字节） | +| [`Release()`](release.md) | 释放资源引用 | +| [`Initialize()`](initialize.md) | 使用构造参数初始化资源 | +| [`SetInvalid()`](setinvalid.md) | 将资源标记为无效 | -### 构造参数 +### 构造参数结构体 `ConstructParams` | 成员 | 类型 | 描述 | |------|------|------| -| `m_name` | `Containers::String` | 资源名称 | -| `m_path` | `Containers::String` | 资源路径 | -| `m_guid` | `ResourceGUID` | 全局唯一标识符 | -| `m_isValid` | `bool` | 资源是否有效 | -| `m_memorySize` | `size_t` | 内存占用大小 | +| `name` | `Containers::String` | 资源名称 | +| `path` | `Containers::String` | 资源路径 | +| `guid` | `ResourceGUID` | 全局唯一标识符 | +| `memorySize` | `size_t` | 内存占用大小（字节），默认 0 | ## 使用示例 @@ -51,7 +52,4 @@ public: ## 相关文档 -- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 -- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义 - [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/iresource/isvalid.md b/docs/api/resources/iresource/isvalid.md new file mode 100644 index 00000000..c370149c --- /dev/null +++ b/docs/api/resources/iresource/isvalid.md @@ -0,0 +1,33 @@ +# IResource::IsValid + +```cpp +virtual bool IsValid() const = 0 +``` + +检查资源是否有效。纯虚方法，由具体资源类实现，返回资源当前的有效状态。 + +**参数：** 无 + +**返回：** `bool` - 资源有效返回 `true`，无效返回 `false` + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); +if (tex->IsValid()) { + // 资源加载成功，可以使用 +} else { + // 资源加载失败或已被释放 +} +``` + +## 相关文档 + +- [IResource 总览](iresource.md) - 返回类总览 +- [SetInvalid](setinvalid.md) - 将资源标记为无效 \ No newline at end of file diff --git a/docs/api/resources/iresource/release.md b/docs/api/resources/iresource/release.md index 2969aa27..8b90fcfd 100644 --- a/docs/api/resources/iresource/release.md +++ b/docs/api/resources/iresource/release.md @@ -10,6 +10,10 @@ virtual void Release() = 0 **返回：** 无 +**异常：** 无 + +**线程安全：** ❌ + **复杂度：** O(1) 或 O(n)，取决于具体实现 **示例：** diff --git a/docs/api/resources/iresource/setinvalid.md b/docs/api/resources/iresource/setinvalid.md index 4b0530e4..2316989b 100644 --- a/docs/api/resources/iresource/setinvalid.md +++ b/docs/api/resources/iresource/setinvalid.md @@ -10,6 +10,10 @@ void SetInvalid() **返回：** 无 +**异常：** 无 + +**线程安全：** ❌ + **复杂度：** O(1) **示例：** diff --git a/docs/api/resources/material-loader/index.md b/docs/api/resources/material-loader/index.md new file mode 100644 index 00000000..95f17c5e --- /dev/null +++ b/docs/api/resources/material-loader/index.md @@ -0,0 +1,59 @@ +# MaterialLoader + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (Class) + +## 描述 + +材质资源加载器，负责从磁盘加载 `.mat`、`.material` 和 `.json` 格式的材质资源文件。 + +## 概述 + +`MaterialLoader` 继承自 `IResourceLoader`，实现了材质资源的加载功能。它支持多种材质文件格式，能够解析材质文件中的 shader 引用并自动加载对应的 Shader 资源。加载过程中会提取材质的基本属性信息并创建 `Material` 对象。 + +## 公共方法 + +| 方法 | 签名 | 描述 | +|------|------|------| +| [MaterialLoader](methods/material-loader-constructor.md) | `MaterialLoader()` | 默认构造函数 | +| [~MaterialLoader](methods/material-loader-destructor.md) | `virtual ~MaterialLoader()` | 析构函数 | +| [GetResourceType](methods/get-resource-type.md) | `ResourceType GetResourceType() const` | 返回资源类型为 Material | +| [GetSupportedExtensions](methods/get-supported-extensions.md) | `Array GetSupportedExtensions() const` | 返回支持的扩展名列表 | +| [CanLoad](methods/can-load.md) | `bool CanLoad(const String& path) const` | 检查给定路径是否可被加载 | +| [Load](methods/load.md) | `LoadResult Load(const String& path, const ImportSettings* settings = nullptr)` | 加载指定路径的材质资源 | +| [GetDefaultSettings](methods/get-default-settings.md) | `ImportSettings* GetDefaultSettings() const` | 返回默认导入设置 | + +## 使用示例 + +```cpp +#include "Resources/MaterialLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载材质 +auto materialHandle = ResourceManager::Get().Load("assets/materials/wood.mat"); +if (materialHandle.IsValid()) { + Material* material = materialHandle.Get(); + // 使用材质... +} + +// 直接使用 MaterialLoader +MaterialLoader loader; +LoadResult result = loader.Load("assets/materials/wood.material"); +if (result.IsSuccess()) { + Material* material = static_cast(result.GetResource()); + // 使用材质... +} +``` + +## 相关文档 + +- [Material](../material/material.md) +- [IResourceLoader](../iloader/iloader.md) +- [ResourceManager](../resource-manager/resource-manager.md) diff --git a/docs/api/resources/material-loader/methods/can-load.md b/docs/api/resources/material-loader/methods/can-load.md new file mode 100644 index 00000000..d64c5c96 --- /dev/null +++ b/docs/api/resources/material-loader/methods/can-load.md @@ -0,0 +1,31 @@ +# MaterialLoader::CanLoad + +## 方法签名 + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +## 详细描述 + +检查给定路径的文件是否可以被该加载器加载。通过提取文件扩展名并与支持列表进行比较来判断。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| path | `const Containers::String&` | 待检查的文件路径 | + +## 返回值 + +`bool` - 如果文件扩展名在支持列表中返回 `true`，否则返回 `false` + +## 示例 + +```cpp +MaterialLoader loader; +bool canLoad1 = loader.CanLoad("assets/materials/wood.mat"); // true +bool canLoad2 = loader.CanLoad("assets/materials/wood.material"); // true +bool canLoad3 = loader.CanLoad("assets/materials/wood.json"); // true +bool canLoad4 = loader.CanLoad("assets/materials/wood.png"); // false +``` diff --git a/docs/api/resources/material-loader/methods/get-default-settings.md b/docs/api/resources/material-loader/methods/get-default-settings.md new file mode 100644 index 00000000..080e8266 --- /dev/null +++ b/docs/api/resources/material-loader/methods/get-default-settings.md @@ -0,0 +1,27 @@ +# MaterialLoader::GetDefaultSettings + +## 方法签名 + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +## 详细描述 + +返回材质加载器的默认导入设置。当前实现返回 `nullptr`，表示材质加载不使用特殊的导入设置。 + +## 参数 + +无 + +## 返回值 + +`ImportSettings*` - 始终返回 `nullptr` + +## 示例 + +```cpp +MaterialLoader loader; +ImportSettings* settings = loader.GetDefaultSettings(); +// settings == nullptr +``` diff --git a/docs/api/resources/material-loader/methods/get-resource-type.md b/docs/api/resources/material-loader/methods/get-resource-type.md new file mode 100644 index 00000000..fe0cb2c8 --- /dev/null +++ b/docs/api/resources/material-loader/methods/get-resource-type.md @@ -0,0 +1,27 @@ +# MaterialLoader::GetResourceType + +## 方法签名 + +```cpp +ResourceType GetResourceType() const override; +``` + +## 详细描述 + +返回该加载器管理的资源类型，固定为 `ResourceType::Material`。此方法继承自 `IResourceLoader` 接口，用于资源管理器识别加载器类型。 + +## 参数 + +无 + +## 返回值 + +`ResourceType` - 资源类型枚举值，始终返回 `ResourceType::Material` + +## 示例 + +```cpp +MaterialLoader loader; +ResourceType type = loader.GetResourceType(); +// type == ResourceType::Material +``` diff --git a/docs/api/resources/material-loader/methods/get-supported-extensions.md b/docs/api/resources/material-loader/methods/get-supported-extensions.md new file mode 100644 index 00000000..a06d4bfa --- /dev/null +++ b/docs/api/resources/material-loader/methods/get-supported-extensions.md @@ -0,0 +1,36 @@ +# MaterialLoader::GetSupportedExtensions + +## 方法签名 + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +## 详细描述 + +返回该加载器支持的文件扩展名列表。`MaterialLoader` 支持三种材质文件格式： +- `.mat` - 材质文件 +- `.material` - 材质文件（完整格式） +- `.json` - JSON 格式的材质描述文件 + +## 参数 + +无 + +## 返回值 + +`Containers::Array` - 支持的扩展名数组 + +## 示例 + +```cpp +MaterialLoader loader; +auto extensions = loader.GetSupportedExtensions(); +for (const auto& ext : extensions) { + printf("Supported extension: %s\n", ext.CStr()); +} +// Output: +// Supported extension: mat +// Supported extension: material +// Supported extension: json +``` diff --git a/docs/api/resources/material-loader/methods/load.md b/docs/api/resources/material-loader/methods/load.md new file mode 100644 index 00000000..08ba6449 --- /dev/null +++ b/docs/api/resources/material-loader/methods/load.md @@ -0,0 +1,62 @@ +# MaterialLoader::Load + +## 方法签名 + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +## 详细描述 + +加载指定路径的材质资源文件。加载过程包括： +1. 读取文件数据 +2. 创建 `Material` 对象并设置基本信息（路径、名称、GUID） +3. 解析 JSON 格式内容，提取 shader 路径 +4. 加载引用的 Shader 资源 +5. 设置材质的有效性标志和内存占用 + +当前实现仅支持解析 JSON 中的 `"shader"` 字段并加载对应的 Shader 资源。 + +## 参数 + +| 参数 | 类型 | 默认值 | 描述 | +|------|------|--------|------| +| path | `const Containers::String&` | - | 材质文件路径 | +| settings | `const ImportSettings*` | `nullptr` | 导入设置（当前未使用） | + +## 返回值 + +`LoadResult` - 加载结果对象，包含成功加载的 `Material` 指针或错误信息 + +## 示例 + +```cpp +#include "Resources/MaterialLoader.h" + +using namespace XCEngine::Resources; + +MaterialLoader loader; +LoadResult result = loader.Load("assets/materials/pbr.metallic"); + +if (result.IsSuccess()) { + Material* material = static_cast(result.GetResource()); + printf("Loaded material: %s, GUID: %s\n", + material->m_name.CStr(), + material->m_guid.ToString().CStr()); +} else { + printf("Failed to load material: %s\n", result.GetError().CStr()); +} +``` + +### JSON 材质文件格式 + +```json +{ + "shader": "shaders/pbr.glsl", + "properties": { + "albedo": [1.0, 1.0, 1.0, 1.0], + "metallic": 0.0, + "roughness": 0.5 + } +} +``` diff --git a/docs/api/resources/material-loader/methods/material-loader-constructor.md b/docs/api/resources/material-loader/methods/material-loader-constructor.md new file mode 100644 index 00000000..686fef9b --- /dev/null +++ b/docs/api/resources/material-loader/methods/material-loader-constructor.md @@ -0,0 +1,29 @@ +# MaterialLoader::MaterialLoader + +## 方法签名 + +```cpp +MaterialLoader(); +``` + +## 详细描述 + +`MaterialLoader` 类的默认构造函数，使用默认方式构造一个 `MaterialLoader` 实例。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +#include "Resources/MaterialLoader.h" + +using namespace XCEngine::Resources; + +MaterialLoader loader; +``` diff --git a/docs/api/resources/material-loader/methods/material-loader-destructor.md b/docs/api/resources/material-loader/methods/material-loader-destructor.md new file mode 100644 index 00000000..92529a04 --- /dev/null +++ b/docs/api/resources/material-loader/methods/material-loader-destructor.md @@ -0,0 +1,28 @@ +# MaterialLoader::~MaterialLoader + +## 方法签名 + +```cpp +virtual ~MaterialLoader() override; +``` + +## 详细描述 + +`MaterialLoader` 类的析构函数，用于清理 `MaterialLoader` 实例占用的资源。当前实现为默认析构函数。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +{ + MaterialLoader loader; + // 使用 loader... +} // loader 在此自动销毁 +``` diff --git a/docs/api/resources/material/clear-all-properties.md b/docs/api/resources/material/clear-all-properties.md new file mode 100644 index 00000000..9d130f7b --- /dev/null +++ b/docs/api/resources/material/clear-all-properties.md @@ -0,0 +1,21 @@ +# Material::ClearAllProperties + +```cpp +void ClearAllProperties(); +``` + +清空所有属性和纹理绑定。 + +**线程安全：** ❌ + +**复杂度：** O(n) + +**示例：** + +```cpp +mat->ClearAllProperties(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-bool.md b/docs/api/resources/material/get-bool.md new file mode 100644 index 00000000..22ced97d --- /dev/null +++ b/docs/api/resources/material/get-bool.md @@ -0,0 +1,26 @@ +# Material::GetBool + +```cpp +bool GetBool(const Containers::String& name) const; +``` + +获取布尔属性值。如果属性不存在则返回 false。 + +**参数：** +- `name` - 属性名称 + +**返回：** 布尔属性值，不存在则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +bool receiveShadow = mat->GetBool("receiveShadow"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-constant-buffer-data.md b/docs/api/resources/material/get-constant-buffer-data.md new file mode 100644 index 00000000..8126c749 --- /dev/null +++ b/docs/api/resources/material/get-constant-buffer-data.md @@ -0,0 +1,25 @@ +# Material::GetConstantBufferData + +```cpp +const Containers::Array& GetConstantBufferData() const; +``` + +获取常量缓冲区原始数据。数据由 UpdateConstantBuffer() 更新。 + +**返回：** 常量缓冲区数据数组的引用 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->UpdateConstantBuffer(); +const auto& cbData = mat->GetConstantBufferData(); +// 将 cbData 上传到 GPU +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-float.md b/docs/api/resources/material/get-float.md new file mode 100644 index 00000000..2aa9c5b0 --- /dev/null +++ b/docs/api/resources/material/get-float.md @@ -0,0 +1,26 @@ +# Material::GetFloat + +```cpp +float GetFloat(const Containers::String& name) const; +``` + +获取浮点属性值。如果属性不存在则返回 0.0f。 + +**参数：** +- `name` - 属性名称 + +**返回：** 浮点属性值，不存在则返回 0.0f + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +float roughness = mat->GetFloat("roughness"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-float2.md b/docs/api/resources/material/get-float2.md new file mode 100644 index 00000000..ba7583ae --- /dev/null +++ b/docs/api/resources/material/get-float2.md @@ -0,0 +1,26 @@ +# Material::GetFloat2 + +```cpp +Math::Vector2 GetFloat2(const Containers::String& name) const; +``` + +获取二维向量属性值。如果属性不存在则返回零向量。 + +**参数：** +- `name` - 属性名称 + +**返回：** 二维向量属性值 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Math::Vector2 uvScale = mat->GetFloat2("uvScale"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-float3.md b/docs/api/resources/material/get-float3.md new file mode 100644 index 00000000..8b77a940 --- /dev/null +++ b/docs/api/resources/material/get-float3.md @@ -0,0 +1,26 @@ +# Material::GetFloat3 + +```cpp +Math::Vector3 GetFloat3(const Containers::String& name) const; +``` + +获取三维向量属性值。如果属性不存在则返回零向量。 + +**参数：** +- `name` - 属性名称 + +**返回：** 三维向量属性值 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Math::Vector3 albedo = mat->GetFloat3("albedo"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-float4.md b/docs/api/resources/material/get-float4.md new file mode 100644 index 00000000..82516a51 --- /dev/null +++ b/docs/api/resources/material/get-float4.md @@ -0,0 +1,26 @@ +# Material::GetFloat4 + +```cpp +Math::Vector4 GetFloat4(const Containers::String& name) const; +``` + +获取四维向量属性值。如果属性不存在则返回零向量。 + +**参数：** +- `name` - 属性名称 + +**返回：** 四维向量属性值 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Math::Vector4 plane = mat->GetFloat4("planeEquation"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-guid.md b/docs/api/resources/material/get-guid.md new file mode 100644 index 00000000..3f74c948 --- /dev/null +++ b/docs/api/resources/material/get-guid.md @@ -0,0 +1,24 @@ +# Material::GetGUID + +```cpp +ResourceGUID GetGUID() const override; +``` + +获取材质的全局唯一标识符。 + +**返回：** 资源 GUID + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +ResourceGUID guid = mat->GetGUID(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-int.md b/docs/api/resources/material/get-int.md new file mode 100644 index 00000000..a0261b70 --- /dev/null +++ b/docs/api/resources/material/get-int.md @@ -0,0 +1,26 @@ +# Material::GetInt + +```cpp +Core::int32 GetInt(const Containers::String& name) const; +``` + +获取整数属性值。如果属性不存在则返回 0。 + +**参数：** +- `name` - 属性名称 + +**返回：** 整数属性值，不存在则返回 0 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +int32 normalScale = mat->GetInt("normalScale"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-memory-size.md b/docs/api/resources/material/get-memory-size.md new file mode 100644 index 00000000..89713754 --- /dev/null +++ b/docs/api/resources/material/get-memory-size.md @@ -0,0 +1,24 @@ +# Material::GetMemorySize + +```cpp +size_t GetMemorySize() const override; +``` + +获取材质占用的内存大小。 + +**返回：** 内存大小（字节） + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +size_t memSize = mat->GetMemorySize(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-name.md b/docs/api/resources/material/get-name.md new file mode 100644 index 00000000..c1150324 --- /dev/null +++ b/docs/api/resources/material/get-name.md @@ -0,0 +1,24 @@ +# Material::GetName + +```cpp +const Containers::String& GetName() const override; +``` + +获取材质的名称。 + +**返回：** 材质名称字符串的引用 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +const String& name = mat->GetName(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-path.md b/docs/api/resources/material/get-path.md new file mode 100644 index 00000000..7ac4662d --- /dev/null +++ b/docs/api/resources/material/get-path.md @@ -0,0 +1,24 @@ +# Material::GetPath + +```cpp +const Containers::String& GetPath() const override; +``` + +获取材质资源的路径。 + +**返回：** 资源路径字符串的引用 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +const String& path = mat->GetPath(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-shader.md b/docs/api/resources/material/get-shader.md new file mode 100644 index 00000000..bc0bb041 --- /dev/null +++ b/docs/api/resources/material/get-shader.md @@ -0,0 +1,26 @@ +# Material::GetShader + +```cpp +class Shader* GetShader() const; +``` + +获取材质关联的着色器指针。 + +**返回：** 着色器指针，如果未设置则返回 nullptr + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +Shader* shader = mat->GetShader(); +if (shader != nullptr) { + // 使用着色器 +} +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-texture.md b/docs/api/resources/material/get-texture.md new file mode 100644 index 00000000..19e15591 --- /dev/null +++ b/docs/api/resources/material/get-texture.md @@ -0,0 +1,26 @@ +# Material::GetTexture + +```cpp +ResourceHandle GetTexture(const Containers::String& name) const; +``` + +获取纹理属性句柄。 + +**参数：** +- `name` - 属性名称 + +**返回：** 纹理资源句柄 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle albedoMap = mat->GetTexture("albedoMap"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/get-type.md b/docs/api/resources/material/get-type.md new file mode 100644 index 00000000..eb245de3 --- /dev/null +++ b/docs/api/resources/material/get-type.md @@ -0,0 +1,26 @@ +# Material::GetType + +```cpp +ResourceType GetType() const override; +``` + +返回材质的资源类型，标识该资源为 Material 类型。 + +**返回：** `ResourceType::Material` + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +if (mat->GetType() == ResourceType::Material) { + // 这是一个材质资源 +} +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/has-property.md b/docs/api/resources/material/has-property.md new file mode 100644 index 00000000..ef85e482 --- /dev/null +++ b/docs/api/resources/material/has-property.md @@ -0,0 +1,28 @@ +# Material::HasProperty + +```cpp +bool HasProperty(const Containers::String& name) const; +``` + +检查指定属性是否存在。 + +**参数：** +- `name` - 属性名称 + +**返回：** 属性存在返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +if (mat->HasProperty("roughness")) { + float roughness = mat->GetFloat("roughness"); +} +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/is-valid.md b/docs/api/resources/material/is-valid.md new file mode 100644 index 00000000..26e6fd6d --- /dev/null +++ b/docs/api/resources/material/is-valid.md @@ -0,0 +1,26 @@ +# Material::IsValid + +```cpp +bool IsValid() const override; +``` + +检查材质是否有效且已正确加载。 + +**返回：** 材质有效返回 true，否则返回 false + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle mat = ResourceManager::Get().Load("materials/pbr.mat"); +if (mat->IsValid()) { + // 材质已成功加载 +} +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/material.md b/docs/api/resources/material/material.md index 343992ba..09d5f81d 100644 --- a/docs/api/resources/material/material.md +++ b/docs/api/resources/material/material.md @@ -4,11 +4,13 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/Material.h` + **描述**: 材质资源类，管理渲染所需的着色器和属性参数。 ## 概述 -`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、纹理等），并支持将属性数据打包到常量缓冲区。 +`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、整数、布尔值、纹理等），并支持将属性数据打包到常量缓冲区供 GPU 着色器使用。 ## 头文件 @@ -20,7 +22,7 @@ ### MaterialPropertyType -材质属性类型枚举。 +材质属性类型枚举，定义材质支持的属性数据类型。 | 值 | 描述 | |----|------| @@ -28,124 +30,135 @@ | `Float2` | 二维浮点向量 | | `Float3` | 三维浮点向量 | | `Float4` | 四维浮点向量 | -| `Int` | 整数 | +| `Int` | 32位整数 | | `Int2` | 二维整数向量 | | `Int3` | 三维整数向量 | | `Int4` | 四维整数向量 | | `Bool` | 布尔值 | -| `Texture` | 纹理资源 | +| `Texture` | 二维纹理资源 | | `Cubemap` | 立方体贴图资源 | ## 结构体 ### MaterialProperty -材质属性结构体。 +材质属性结构体，存储单个属性的名称、类型和值。 | 成员 | 类型 | 描述 | |------|------|------| -| `name` | `Containers::String` | 属性名称 | -| `type` | `MaterialPropertyType` | 属性类型 | -| `value` | `union` | 属性值（float/int/bool） | +| `name` | `Containers::String` | 属性名称标识符 | +| `type` | `MaterialPropertyType` | 属性数据类型 | +| `value` | `union Value` | 属性值联合体，支持 float[4]、int[4]、bool | | `refCount` | `Core::uint32` | 引用计数 | -## 公共方法 +## 公共方法表格 -### 基础属性 +### 资源基类方法 | 方法 | 描述 | |------|------| -| `ResourceType GetType() const` | 返回 `ResourceType::Material` | -| `const Containers::String& GetName() const` | 获取材质名称 | -| `const Containers::String& GetPath() const` | 获取材质路径 | -| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 | -| `bool IsValid() const` | 检查材质是否有效 | -| `size_t GetMemorySize() const` | 获取内存大小 | -| `void Release()` | 释放材质引用 | +| `GetType()` | 返回 `ResourceType::Material` | +| `GetName()` | 获取材质名称 | +| `GetPath()` | 获取材质资源路径 | +| `GetGUID()` | 获取全局唯一标识符 | +| `IsValid()` | 检查材质是否有效且已加载 | +| `GetMemorySize()` | 获取材质占用的内存大小 | +| `Release()` | 释放材质所有引用和资源 | ### 着色器管理 | 方法 | 描述 | |------|------| -| `void SetShader(const ResourceHandle& shader)` | 设置材质着色器 | -| `Shader* GetShader() const` | 获取材质着色器 | +| [`SetShader`](set-shader.md) | 设置材质使用的着色器 | +| [`GetShader`](get-shader.md) | 获取材质关联的着色器指针 | -### 属性设置 +### 属性设置方法 | 方法 | 描述 | |------|------| -| `void SetFloat(const Containers::String& name, float value)` | 设置浮点属性 | -| `void SetFloat2(const Containers::String& name, const Math::Vector2& value)` | 设置 Vector2 属性 | -| `void SetFloat3(const Containers::String& name, const Math::Vector3& value)` | 设置 Vector3 属性 | -| `void SetFloat4(const Containers::String& name, const Math::Vector4& value)` | 设置 Vector4 属性 | -| `void SetInt(const Containers::String& name, Core::int32 value)` | 设置整数属性 | -| `void SetBool(const Containers::String& name, bool value)` | 设置布尔属性 | -| `void SetTexture(const Containers::String& name, const ResourceHandle& texture)` | 设置纹理属性 | +| [`SetFloat`](set-float.md) | 设置浮点属性 | +| [`SetFloat2`](set-float2.md) | 设置二维向量属性 | +| [`SetFloat3`](set-float3.md) | 设置三维向量属性 | +| [`SetFloat4`](set-float4.md) | 设置四维向量属性 | +| [`SetInt`](set-int.md) | 设置整数属性 | +| [`SetBool`](set-bool.md) | 设置布尔属性 | +| [`SetTexture`](set-texture.md) | 设置纹理属性 | -### 属性获取 +### 属性获取方法 | 方法 | 描述 | |------|------| -| `float GetFloat(const Containers::String& name) const` | 获取浮点属性 | -| `Math::Vector2 GetFloat2(const Containers::String& name) const` | 获取 Vector2 属性 | -| `Math::Vector3 GetFloat3(const Containers::String& name) const` | 获取 Vector3 属性 | -| `Math::Vector4 GetFloat4(const Containers::String& name) const` | 获取 Vector4 属性 | -| `Core::int32 GetInt(const Containers::String& name) const` | 获取整数属性 | -| `bool GetBool(const Containers::String& name) const` | 获取布尔属性 | -| `ResourceHandle GetTexture(const Containers::String& name) const` | 获取纹理属性 | +| [`GetFloat`](get-float.md) | 获取浮点属性值，不存在返回 0.0f | +| [`GetFloat2`](get-float2.md) | 获取二维向量属性值 | +| [`GetFloat3`](get-float3.md) | 获取三维向量属性值 | +| [`GetFloat4`](get-float4.md) | 获取四维向量属性值 | +| [`GetInt`](get-int.md) | 获取整数属性值，不存在返回 0 | +| [`GetBool`](get-bool.md) | 获取布尔属性值，不存在返回 false | +| [`GetTexture`](get-texture.md) | 获取纹理属性句柄 | ### 常量缓冲区 | 方法 | 描述 | |------|------| -| `const Containers::Array& GetConstantBufferData() const` | 获取常量缓冲区数据 | -| `void UpdateConstantBuffer()` | 更新常量缓冲区数据 | +| [`GetConstantBufferData`](get-constant-buffer-data.md) | 获取常量缓冲区原始数据 | +| [`UpdateConstantBuffer`](update-constant-buffer.md) | 更新常量缓冲区数据 | -### 属性管理 +### 属性查询与管理 | 方法 | 描述 | |------|------| -| `bool HasProperty(const Containers::String& name) const` | 检查属性是否存在 | -| `void RemoveProperty(const Containers::String& name)` | 移除属性 | -| `void ClearAllProperties()` | 清空所有属性 | - -## 实现说明 - -**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。 +| [`HasProperty`](has-property.md) | 检查指定属性是否存在 | +| [`RemoveProperty`](remove-property.md) | 移除指定属性 | +| [`ClearAllProperties`](clear-all-properties.md) | 清空所有属性和纹理绑定 | ## 使用示例 ```cpp -// 加载材质 +// 通过资源管理器加载材质 ResourceHandle mat = ResourceManager::Get().Load("materials/player.mat"); // 设置着色器 -mat->SetShader(shaderHandle); +ResourceHandle shader = ResourceManager::Get().Load("shaders/pbr.shader"); +mat->SetShader(shader); -// 设置各种属性 +// 设置材质属性 mat->SetFloat("roughness", 0.5f); +mat->SetFloat("metallic", 0.0f); mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f)); +mat->SetFloat4("emission", Math::Vector4(1.0f, 0.5f, 0.2f, 2.0f)); +mat->SetInt("normalScale", 1); +mat->SetBool("receiveShadow", true); + +// 设置纹理 +ResourceHandle albedoTex = ResourceManager::Get().Load("textures/albedo.png"); +ResourceHandle normalTex = ResourceManager::Get().Load("textures/normal.png"); +ResourceHandle roughnessTex = ResourceManager::Get().Load("textures/roughness.png"); mat->SetTexture("albedoMap", albedoTex); mat->SetTexture("normalMap", normalTex); -mat->SetInt("normalScale", 1); +mat->SetTexture("roughnessMap", roughnessTex); // 获取属性 float roughness = mat->GetFloat("roughness"); Math::Vector3 albedo = mat->GetFloat3("albedo"); +Shader* shader = mat->GetShader(); -// 检查属性 +// 属性查询 if (mat->HasProperty("metallic")) { float metallic = mat->GetFloat("metallic"); } -// 更新常量缓冲区 +// 更新常量缓冲区供 GPU 使用 mat->UpdateConstantBuffer(); -auto cbData = mat->GetConstantBufferData(); +const auto& cbData = mat->GetConstantBufferData(); + +// 释放材质 +mat->Release(); ``` ## 相关文档 -- [IResource](../iresource/iresource.md) - 资源基类 +- [IResource](../iresource/iresource.md) - 资源基类接口 - [Shader](../shader/shader.md) - 着色器资源 - [Texture](../texture/texture.md) - 纹理资源 -- [Resources 总览](../resources.md) - 返回模块总览 +- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 +- [Resources 模块总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/material/release.md b/docs/api/resources/material/release.md new file mode 100644 index 00000000..220428f1 --- /dev/null +++ b/docs/api/resources/material/release.md @@ -0,0 +1,26 @@ +# Material::Release + +**方法签名**: +```cpp +void Release() override +``` + +**详细描述**: 释放材质的所有引用和资源。调用后着色器引用、属性映射、纹理绑定和常量缓冲区数据都将被清空，材质变为无效状态。 + +**参数**: 无 + +**返回值**: 无 + +**复杂度**: O(n)，n 为属性和纹理绑定数量 + +**示例**: + +```cpp +mat->Release(); +// 调用后 mat->IsValid() 返回 false +``` + +## 相关文档 + +- [Material 总览](material.md) - 返回类总览 +- [IResource::Release](../iresource/iresource.md) - 资源基类接口 diff --git a/docs/api/resources/material/remove-property.md b/docs/api/resources/material/remove-property.md new file mode 100644 index 00000000..4ba33607 --- /dev/null +++ b/docs/api/resources/material/remove-property.md @@ -0,0 +1,24 @@ +# Material::RemoveProperty + +```cpp +void RemoveProperty(const Containers::String& name); +``` + +移除指定属性。 + +**参数：** +- `name` - 属性名称 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->RemoveProperty("roughness"); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-bool.md b/docs/api/resources/material/set-bool.md new file mode 100644 index 00000000..9623de24 --- /dev/null +++ b/docs/api/resources/material/set-bool.md @@ -0,0 +1,26 @@ +# Material::SetBool + +```cpp +void SetBool(const Containers::String& name, bool value); +``` + +设置布尔属性值。 + +**参数：** +- `name` - 属性名称 +- `value` - 布尔值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetBool("receiveShadow", true); +mat->SetBool("castShadow", false); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-float.md b/docs/api/resources/material/set-float.md new file mode 100644 index 00000000..ae90ec4c --- /dev/null +++ b/docs/api/resources/material/set-float.md @@ -0,0 +1,26 @@ +# Material::SetFloat + +```cpp +void SetFloat(const Containers::String& name, float value); +``` + +设置浮点属性值。如果属性不存在则创建，存在则更新。 + +**参数：** +- `name` - 属性名称 +- `value` - 浮点数值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat("roughness", 0.5f); +mat->SetFloat("metallic", 0.8f); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-float2.md b/docs/api/resources/material/set-float2.md new file mode 100644 index 00000000..a9d5ed14 --- /dev/null +++ b/docs/api/resources/material/set-float2.md @@ -0,0 +1,25 @@ +# Material::SetFloat2 + +```cpp +void SetFloat2(const Containers::String& name, const Math::Vector2& value); +``` + +设置二维向量属性值。 + +**参数：** +- `name` - 属性名称 +- `value` - 二维向量值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat2("uvScale", Math::Vector2(2.0f, 2.0f)); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-float3.md b/docs/api/resources/material/set-float3.md new file mode 100644 index 00000000..3d56d266 --- /dev/null +++ b/docs/api/resources/material/set-float3.md @@ -0,0 +1,26 @@ +# Material::SetFloat3 + +```cpp +void SetFloat3(const Containers::String& name, const Math::Vector3& value); +``` + +设置三维向量属性值，常用于颜色、法线缩放等。 + +**参数：** +- `name` - 属性名称 +- `value` - 三维向量值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f)); +mat->SetFloat3("emission", Math::Vector3(0.5f, 0.5f, 0.5f)); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-float4.md b/docs/api/resources/material/set-float4.md new file mode 100644 index 00000000..d92c094c --- /dev/null +++ b/docs/api/resources/material/set-float4.md @@ -0,0 +1,25 @@ +# Material::SetFloat4 + +```cpp +void SetFloat4(const Containers::String& name, const Math::Vector4& value); +``` + +设置四维向量属性值。 + +**参数：** +- `name` - 属性名称 +- `value` - 四维向量值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat4("planeEquation", Math::Vector4(0.0f, 1.0f, 0.0f, 0.0f)); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-int.md b/docs/api/resources/material/set-int.md new file mode 100644 index 00000000..76b6f74e --- /dev/null +++ b/docs/api/resources/material/set-int.md @@ -0,0 +1,26 @@ +# Material::SetInt + +```cpp +void SetInt(const Containers::String& name, Core::int32 value); +``` + +设置整数属性值。 + +**参数：** +- `name` - 属性名称 +- `value` - 整数值 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetInt("normalScale", 1); +mat->SetInt("uSampleCount", 4); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/set-shader.md b/docs/api/resources/material/set-shader.md new file mode 100644 index 00000000..877607d4 --- /dev/null +++ b/docs/api/resources/material/set-shader.md @@ -0,0 +1,25 @@ +# Material::SetShader + +```cpp +void SetShader(const ResourceHandle& shader); +``` + +设置材质使用的着色器。 + +**参数：** +- `shader` - 着色器资源句柄 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/pbr.shader"); +mat->SetShader(shader); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/settexture.md b/docs/api/resources/material/set-texture.md similarity index 81% rename from docs/api/resources/material/settexture.md rename to docs/api/resources/material/set-texture.md index 02f169fd..7aa0e52a 100644 --- a/docs/api/resources/material/settexture.md +++ b/docs/api/resources/material/set-texture.md @@ -1,16 +1,16 @@ # Material::SetTexture ```cpp -void SetTexture(const Containers::String& name, const ResourceHandle& texture) +void SetTexture(const Containers::String& name, const ResourceHandle& texture); ``` -设置材质纹理属性。 +设置纹理属性。 **参数：** - `name` - 属性名称 - `texture` - 纹理资源句柄 -**返回：** 无 +**线程安全：** ❌ **复杂度：** O(1) @@ -25,4 +25,4 @@ mat->SetTexture("normalMap", normalTex); ## 相关文档 -- [Material 总览](material.md) - 返回类总览 +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/setfloat.md b/docs/api/resources/material/setfloat.md deleted file mode 100644 index a7bf8906..00000000 --- a/docs/api/resources/material/setfloat.md +++ /dev/null @@ -1,27 +0,0 @@ -# Material::SetFloat - -```cpp -void SetFloat(const Containers::String& name, float value) -``` - -设置材质浮点属性。 - -**参数：** -- `name` - 属性名称 -- `value` - 属性值 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -mat->SetFloat("roughness", 0.5f); -mat->SetFloat("metallic", 0.0f); -mat->SetFloat("emissionStrength", 2.0f); -``` - -## 相关文档 - -- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/material/setshader.md b/docs/api/resources/material/setshader.md deleted file mode 100644 index d3adf4dd..00000000 --- a/docs/api/resources/material/setshader.md +++ /dev/null @@ -1,26 +0,0 @@ -# Material::SetShader - -```cpp -void SetShader(const ResourceHandle& shader) -``` - -设置材质使用的着色器。 - -**参数：** -- `shader` - 着色器资源句柄 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle vs = ResourceManager::Get().Load("shaders/vertex.glsl"); -ResourceHandle fs = ResourceManager::Get().Load("shaders/fragment.glsl"); -mat->SetShader(vs); -``` - -## 相关文档 - -- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/material/update-constant-buffer.md b/docs/api/resources/material/update-constant-buffer.md new file mode 100644 index 00000000..ac7227ed --- /dev/null +++ b/docs/api/resources/material/update-constant-buffer.md @@ -0,0 +1,23 @@ +# Material::UpdateConstantBuffer + +```cpp +void UpdateConstantBuffer(); +``` + +更新常量缓冲区数据。清空当前常量缓冲区数据。 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +mat->SetFloat("roughness", 0.5f); +mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f)); +mat->UpdateConstantBuffer(); +``` + +## 相关文档 + +- [Material](material.md) - 返回类总览 diff --git a/docs/api/resources/material/updateconstantbuffer.md b/docs/api/resources/material/updateconstantbuffer.md deleted file mode 100644 index 5854f16f..00000000 --- a/docs/api/resources/material/updateconstantbuffer.md +++ /dev/null @@ -1,26 +0,0 @@ -# Material::UpdateConstantBuffer - -```cpp -void UpdateConstantBuffer() -``` - -更新材质常量缓冲区。将所有属性值打包到常量缓冲区的二进制数据中，供 GPU 着色器使用。 - -**参数：** 无 - -**返回：** 无 - -**复杂度：** O(n)，n 为属性数量 - -**示例：** - -```cpp -mat->SetFloat("roughness", 0.5f); -mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f)); -mat->UpdateConstantBuffer(); -auto cbData = mat->GetConstantBufferData(); -``` - -## 相关文档 - -- [Material 总览](material.md) - 返回类总览 diff --git a/docs/api/resources/mesh-import-settings/mesh-import-settings.md b/docs/api/resources/mesh-import-settings/mesh-import-settings.md new file mode 100644 index 00000000..8e28aa34 --- /dev/null +++ b/docs/api/resources/mesh-import-settings/mesh-import-settings.md @@ -0,0 +1,101 @@ +# MeshImportSettings + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**继承**: `ImportSettings` + +**头文件**: `XCEngine/Resources/MeshImportSettings.h` + +**描述**: 网格资源导入设置类，定义从外部模型文件导入网格时的配置选项。 + +--- + +## 概述 + +`MeshImportSettings` 继承自 `ImportSettings`，提供网格导入时的完整配置能力。支持导入标志位操作、缩放、偏移、轴转换、网格合并等选项。`LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。 + +--- + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| `MeshImportSettings()` | 构造函数 | +| `virtual ~MeshImportSettings() override` | 析构函数 | +| `Core::UniqueRef Clone() const override` | 克隆设置对象 | +| `bool LoadFromJSON(const Containers::String& json) override` | 从 JSON 加载设置（stub） | +| `Containers::String SaveToJSON() const override` | 保存为 JSON（stub） | +| `void SetImportFlags(MeshImportFlags flags)` | 设置导入标志 | +| `MeshImportFlags GetImportFlags() const` | 获取导入标志 | +| `void AddImportFlag(MeshImportFlags flag)` | 添加导入标志 | +| `void RemoveImportFlag(MeshImportFlags flag)` | 移除导入标志 | +| `bool HasImportFlag(MeshImportFlags flag) const` | 检查是否包含标志 | +| `void SetScale(float scale)` | 设置缩放 | +| `float GetScale() const` | 获取缩放 | +| `void SetOffset(const Math::Vector3& offset)` | 设置偏移 | +| `const Math::Vector3& GetOffset() const` | 获取偏移 | +| `void SetAxisConversion(bool convert)` | 设置轴转换 | +| `bool GetAxisConversion() const` | 获取轴转换设置 | +| `void SetMergeMeshes(bool merge)` | 设置是否合并网格 | +| `bool GetMergeMeshes() const` | 获取合并网格设置 | +| `void SetOptimizeThreshold(float threshold)` | 设置优化阈值 | +| `float GetOptimizeThreshold() const` | 获取优化阈值 | +| `void SetImportScale(float scale)` | 设置导入缩放 | +| `float GetImportScale() const` | 获取导入缩放 | +| `void SetThreshold(float threshold)` | 设置阈值 | +| `float GetThreshold() const` | 获取阈值 | + +--- + +## MeshImportFlags 枚举 + +| 标志 | 值 | 描述 | +|------|------|------| +| `None` | `0` | 无特殊标志 | +| `FlipUVs` | `1 << 0` | 翻转 UV 坐标 | +| `FlipWindingOrder` | `1 << 1` | 翻转顶点绕序 | +| `GenerateNormals` | `1 << 2` | 生成法线 | +| `GenerateTangents` | `1 << 3` | 生成切线 | +| `OptimizeMesh` | `1 << 4` | 优化网格 | +| `ImportSkinning` | `1 << 5` | 导入骨骼蒙皮数据 | +| `ImportAnimations` | `1 << 6` | 导入动画数据 | +| `ImportMaterials` | `1 << 7` | 导入材质 | +| `ImportCameras` | `1 << 8` | 导入相机 | +| `ImportLights` | `1 << 9` | 导入灯光 | + +支持位运算组合：`operator|`、`operator&`、`operator~`。 + +--- + +## 使用示例 + +```cpp +#include +#include + +// 创建导入设置 +MeshImportSettings settings; +settings.SetImportFlags(MeshImportFlags::FlipUVs | MeshImportFlags::GenerateNormals | MeshImportFlags::OptimizeMesh); +settings.SetScale(1.0f); +settings.SetOffset(Math::Vector3::Zero()); +settings.SetAxisConversion(true); +settings.SetMergeMeshes(false); +settings.SetOptimizeThreshold(0.3f); + +// 克隆设置 +auto cloned = settings.Clone(); + +// 加载网格资源 +ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx", &settings); +``` + +--- + +## 相关文档 + +- [ImportSettings](../importsettings/importsettings.md) - 导入设置基类 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 资源模块总览 diff --git a/docs/api/resources/mesh-loader/index.md b/docs/api/resources/mesh-loader/index.md new file mode 100644 index 00000000..27db3caf --- /dev/null +++ b/docs/api/resources/mesh-loader/index.md @@ -0,0 +1,59 @@ +# MeshLoader + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (Class) + +## 描述 + +网格资源加载器，负责从磁盘加载 `.fbx`、`.obj`、`.gltf`、`.glb`、`.dae` 和 `.stl` 格式的网格资源文件。 + +## 概述 + +`MeshLoader` 继承自 `IResourceLoader`，实现了网格资源的加载功能。它支持多种主流 3D 模型文件格式，能够读取文件数据并创建 `Mesh` 对象。加载过程中会提取资源的基本信息（路径、名称、GUID）并设置内存占用。当前实现专注于文件读取和基础资源创建，具体网格数据解析由 `Mesh` 类完成。 + +## 公共方法 + +| 方法 | 签名 | 描述 | +|------|------|------| +| [MeshLoader](methods/constructor.md) | `MeshLoader()` | 默认构造函数 | +| [~MeshLoader](methods/destructor.md) | `virtual ~MeshLoader()` | 析构函数 | +| [GetResourceType](methods/get-resource-type.md) | `ResourceType GetResourceType() const` | 返回资源类型为 Mesh | +| [GetSupportedExtensions](methods/get-supported-extensions.md) | `Array GetSupportedExtensions() const` | 返回支持的扩展名列表 | +| [CanLoad](methods/can-load.md) | `bool CanLoad(const String& path) const` | 检查给定路径是否可被加载 | +| [Load](methods/load.md) | `LoadResult Load(const String& path, const ImportSettings* settings = nullptr)` | 加载指定路径的网格资源 | +| [GetDefaultSettings](methods/get-default-settings.md) | `ImportSettings* GetDefaultSettings() const` | 返回默认导入设置 | + +## 使用示例 + +```cpp +#include "Resources/MeshLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载网格 +auto meshHandle = ResourceManager::Get().Load("assets/models/player.fbx"); +if (meshHandle.IsValid()) { + Mesh* mesh = meshHandle.Get(); + // 使用网格... +} + +// 直接使用 MeshLoader +MeshLoader loader; +LoadResult result = loader.Load("assets/models/player.obj"); +if (result.IsSuccess()) { + Mesh* mesh = static_cast(result.GetResource()); + // 使用网格... +} +``` + +## 相关文档 + +- [Mesh](../mesh/mesh.md) +- [IResourceLoader](../iloader/iloader.md) +- [ResourceManager](../resourcemanager/resourcemanager.md) diff --git a/docs/api/resources/mesh-loader/methods/can-load.md b/docs/api/resources/mesh-loader/methods/can-load.md new file mode 100644 index 00000000..65b2d7a2 --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/can-load.md @@ -0,0 +1,36 @@ +# MeshLoader::CanLoad + +## 方法签名 + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +## 详细描述 + +检查给定路径的文件是否可以被该加载器加载。方法通过提取文件扩展名并转换为小写后进行匹配判断。支持的文件格式包括：fbx、obj、gltf、glb、dae、stl。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| path | `const Containers::String&` | 文件路径 | + +## 返回值 + +`bool` - 如果文件扩展名在支持列表中返回 `true`，否则返回 `false` + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; + +bool canLoadFbx = loader.CanLoad("assets/models/player.fbx"); // true +bool canLoadObj = loader.CanLoad("assets/models/cube.obj"); // true +bool canLoadPng = loader.CanLoad("assets/textures/wood.png"); // false +bool canLoadUnknown = loader.CanLoad("assets/data/model.xyz"); // false +``` diff --git a/docs/api/resources/mesh-loader/methods/constructor.md b/docs/api/resources/mesh-loader/methods/constructor.md new file mode 100644 index 00000000..1e0d67a9 --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/constructor.md @@ -0,0 +1,29 @@ +# MeshLoader::MeshLoader + +## 方法签名 + +```cpp +MeshLoader(); +``` + +## 详细描述 + +默认构造函数，使用默认行为构造 `MeshLoader` 对象。该构造函数不执行任何特殊初始化操作。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; +``` diff --git a/docs/api/resources/mesh-loader/methods/destructor.md b/docs/api/resources/mesh-loader/methods/destructor.md new file mode 100644 index 00000000..5f072c2f --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/destructor.md @@ -0,0 +1,29 @@ +# MeshLoader::~MeshLoader + +## 方法签名 + +```cpp +virtual ~MeshLoader() override; +``` + +## 详细描述 + +析构函数，用于销毁 `MeshLoader` 对象。该析构函数不执行任何特殊清理操作。 + +## 参数 + +无 + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +{ + MeshLoader loader; + // 使用 loader... +} +// loader 在此自动销毁 +``` diff --git a/docs/api/resources/mesh-loader/methods/get-default-settings.md b/docs/api/resources/mesh-loader/methods/get-default-settings.md new file mode 100644 index 00000000..3f7edfab --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/get-default-settings.md @@ -0,0 +1,31 @@ +# MeshLoader::GetDefaultSettings + +## 方法签名 + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +## 详细描述 + +返回网格资源的默认导入设置。当前实现返回 `nullptr`，表示 `MeshLoader` 不使用导入设置。 + +## 参数 + +无 + +## 返回值 + +`ImportSettings*` - 返回 `nullptr` + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; +ImportSettings* settings = loader.GetDefaultSettings(); +// settings == nullptr +``` diff --git a/docs/api/resources/mesh-loader/methods/get-resource-type.md b/docs/api/resources/mesh-loader/methods/get-resource-type.md new file mode 100644 index 00000000..1ccf53f0 --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/get-resource-type.md @@ -0,0 +1,31 @@ +# MeshLoader::GetResourceType + +## 方法签名 + +```cpp +ResourceType GetResourceType() const override; +``` + +## 详细描述 + +返回该加载器处理的资源类型。此方法标识 `MeshLoader` 负责加载 `Mesh` 类型的资源。 + +## 参数 + +无 + +## 返回值 + +`ResourceType` - 返回 `ResourceType::Mesh`，表示该加载器用于加载网格资源 + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; +ResourceType type = loader.GetResourceType(); +// type == ResourceType::Mesh +``` diff --git a/docs/api/resources/mesh-loader/methods/get-supported-extensions.md b/docs/api/resources/mesh-loader/methods/get-supported-extensions.md new file mode 100644 index 00000000..a25ed944 --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/get-supported-extensions.md @@ -0,0 +1,46 @@ +# MeshLoader::GetSupportedExtensions + +## 方法签名 + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +## 详细描述 + +返回该加载器支持的文件扩展名列表。`MeshLoader` 支持六种主流 3D 模型文件格式： +- `.fbx` - Autodesk FBX 格式 +- `.obj` - Wavefront OBJ 格式 +- `.gltf` - GL Transmission Format +- `.glb` - GL Binary 格式 +- `.dae` - COLLADA 格式 +- `.stl` - STereoLithography 格式 + +## 参数 + +无 + +## 返回值 + +`Containers::Array` - 支持的扩展名数组 + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; +auto extensions = loader.GetSupportedExtensions(); +for (const auto& ext : extensions) { + printf("Supported extension: %s\n", ext.CStr()); +} +// Output: +// Supported extension: fbx +// Supported extension: obj +// Supported extension: gltf +// Supported extension: glb +// Supported extension: dae +// Supported extension: stl +``` diff --git a/docs/api/resources/mesh-loader/methods/load.md b/docs/api/resources/mesh-loader/methods/load.md new file mode 100644 index 00000000..f6eeafed --- /dev/null +++ b/docs/api/resources/mesh-loader/methods/load.md @@ -0,0 +1,55 @@ +# MeshLoader::Load + +## 方法签名 + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +## 详细描述 + +加载指定路径的网格资源文件。加载过程包括： +1. 提取文件扩展名并转换为小写 +2. 验证文件格式是否支持 +3. 读取文件数据到内存 +4. 创建 `Mesh` 对象并设置基本信息（路径、名称、GUID） +5. 设置内存占用大小 + +当前实现专注于文件读取和基础资源创建框架，具体网格顶点数据、索引数据的解析由 `Mesh` 类在后续流程中完成。`settings` 参数当前未使用。 + +## 参数 + +| 参数 | 类型 | 默认值 | 描述 | +|------|------|--------|------| +| path | `const Containers::String&` | - | 网格文件路径 | +| settings | `const ImportSettings*` | `nullptr` | 导入设置（当前未使用） | + +## 返回值 + +`LoadResult` - 加载结果对象，包含成功加载的 `Mesh` 指针或错误信息 + +## 示例 + +```cpp +#include "Resources/MeshLoader.h" + +using namespace XCEngine::Resources; + +MeshLoader loader; +LoadResult result = loader.Load("assets/models/player.fbx"); + +if (result.IsSuccess()) { + Mesh* mesh = static_cast(result.GetResource()); + printf("Loaded mesh: %s, GUID: %s, Size: %zu bytes\n", + mesh->m_name.CStr(), + mesh->m_guid.ToString().CStr(), + mesh->m_memorySize); +} else { + printf("Failed to load mesh: %s\n", result.GetError().CStr()); +} +``` + +### 错误情况 + +- 不支持的文件格式：返回 `"Unsupported mesh format: "` +- 文件读取失败：返回 `"Failed to read file: "` diff --git a/docs/api/resources/mesh/add-section.md b/docs/api/resources/mesh/add-section.md new file mode 100644 index 00000000..2f26aaad --- /dev/null +++ b/docs/api/resources/mesh/add-section.md @@ -0,0 +1,52 @@ +# Mesh::AddSection + +```cpp +void AddSection(const MeshSection& section); +``` + +添加一个网格分段（Submesh）。网格分段用于将一个网格分割成多个部分，每个部分可以有不同的材质。 + +**参数：** +- `section` - 网格分段结构，包含顶点和索引范围以及材质 ID + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) 均摊 + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); +mesh.SetIndexData(...); + +// 添加第一个分段（使用材质 0） +MeshSection section1; +section1.baseVertex = 0; +section1.vertexCount = 4; +section1.startIndex = 0; +section1.indexCount = 6; +section1.materialID = 0; +mesh.AddSection(section1); + +// 添加第二个分段（使用材质 1） +MeshSection section2; +section2.baseVertex = 4; +section2.vertexCount = 4; +section2.startIndex = 6; +section2.indexCount = 6; +section2.materialID = 1; +mesh.AddSection(section2); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/addsection.md b/docs/api/resources/mesh/addsection.md deleted file mode 100644 index f7dc0440..00000000 --- a/docs/api/resources/mesh/addsection.md +++ /dev/null @@ -1,30 +0,0 @@ -# Mesh::AddSection - -```cpp -void AddSection(const MeshSection& section) -``` - -添加网格分段（Submesh）。一个 Mesh 可以包含多个分段，每个分段对应一组索引和不同的材质。 - -**参数：** -- `section` - 网格分段描述结构体 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -MeshSection section; -section.baseVertex = 0; -section.vertexCount = 1000; -section.startIndex = 0; -section.indexCount = 3000; -section.materialID = 0; -mesh->AddSection(section); -``` - -## 相关文档 - -- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/constructor.md b/docs/api/resources/mesh/constructor.md new file mode 100644 index 00000000..40160d90 --- /dev/null +++ b/docs/api/resources/mesh/constructor.md @@ -0,0 +1,31 @@ +# Mesh::Mesh + +```cpp +Mesh(); +``` + +构造一个新的 Mesh 实例。初始化所有成员变量为默认值，顶点计数、索引计数均为 0，不持有任何数据。 + +**参数：** 无 + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/destructor.md b/docs/api/resources/mesh/destructor.md new file mode 100644 index 00000000..19376aa0 --- /dev/null +++ b/docs/api/resources/mesh/destructor.md @@ -0,0 +1,35 @@ +# Mesh::~Mesh + +```cpp +virtual ~Mesh() override; +``` + +销毁 Mesh 实例。如果资源已加载，会释放所有持有的顶点数据、索引数据和网格分段信息。 + +**参数：** 无 + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +{ + Mesh mesh; + // 使用 mesh... +} +// mesh 在此处自动销毁 +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-guid.md b/docs/api/resources/mesh/get-guid.md new file mode 100644 index 00000000..82fc12f8 --- /dev/null +++ b/docs/api/resources/mesh/get-guid.md @@ -0,0 +1,41 @@ +# Mesh::GetGUID + +```cpp +ResourceGUID GetGUID() const override; +``` + +返回网格资源的全局唯一标识符（GUID）。GUID 在资源创建时分配，用于资源系统的唯一标识和查找。 + +**参数：** 无 + +**返回：** `ResourceGUID` - 资源的全局唯一标识符 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +IResource::ConstructParams params; +params.name = "Character_Hero"; +params.path = "assets/meshes/hero.mesh"; +params.guid = ResourceGUID::Generate(params.path); +mesh.Initialize(params); + +ResourceGUID guid = mesh.GetGUID(); +if (guid.IsValid()) { + // GUID 有效 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-index-count.md b/docs/api/resources/mesh/get-index-count.md new file mode 100644 index 00000000..7a095494 --- /dev/null +++ b/docs/api/resources/mesh/get-index-count.md @@ -0,0 +1,34 @@ +# Mesh::GetIndexCount + +```cpp +Core::uint32 GetIndexCount() const; +``` + +获取网格的索引数量。 + +**参数：** 无 + +**返回：** `Core::uint32` - 索引数量 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetIndexData(...); + +uint32_t indexCount = mesh.GetIndexCount(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-index-data-size.md b/docs/api/resources/mesh/get-index-data-size.md new file mode 100644 index 00000000..0ef79cd7 --- /dev/null +++ b/docs/api/resources/mesh/get-index-data-size.md @@ -0,0 +1,34 @@ +# Mesh::GetIndexDataSize + +```cpp +size_t GetIndexDataSize() const; +``` + +获取网格索引数据的总字节数。 + +**参数：** 无 + +**返回：** `size_t` - 索引数据字节数 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetIndexData(...); + +size_t dataSize = mesh.GetIndexDataSize(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-index-data.md b/docs/api/resources/mesh/get-index-data.md new file mode 100644 index 00000000..d9d6ce54 --- /dev/null +++ b/docs/api/resources/mesh/get-index-data.md @@ -0,0 +1,37 @@ +# Mesh::GetIndexData + +```cpp +const void* GetIndexData() const; +``` + +获取网格索引数据的只读指针。 + +**参数：** 无 + +**返回：** `const void*` - 索引数据指针，如果没有设置则返回 nullptr + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetIndexData(...); + +const void* indexData = mesh.GetIndexData(); +if (indexData != nullptr) { + // 安全访问索引数据 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-memory-size.md b/docs/api/resources/mesh/get-memory-size.md new file mode 100644 index 00000000..534aeabe --- /dev/null +++ b/docs/api/resources/mesh/get-memory-size.md @@ -0,0 +1,33 @@ +# Mesh::GetMemorySize + +```cpp +size_t GetMemorySize() const override; +``` + +返回网格资源占用的内存大小。包含顶点数据和索引数据的总字节数。 + +**参数：** 无 + +**返回：** `size_t` - 内存大小（字节） + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +// 设置数据... +size_t memSize = mesh.GetMemorySize(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-name.md b/docs/api/resources/mesh/get-name.md new file mode 100644 index 00000000..969410d6 --- /dev/null +++ b/docs/api/resources/mesh/get-name.md @@ -0,0 +1,38 @@ +# Mesh::GetName + +```cpp +const Containers::String& GetName() const override; +``` + +返回网格资源的名称。名称在资源创建时通过 `IResource::Initialize` 方法设置。 + +**参数：** 无 + +**返回：** `const Containers::String&` - 资源名称的引用 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +IResource::ConstructParams params; +params.name = "Character_Hero"; +params.path = "assets/meshes/hero.mesh"; +params.guid = ResourceGUID::Generate(params.path); +mesh.Initialize(params); + +const String& name = mesh.GetName(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-path.md b/docs/api/resources/mesh/get-path.md new file mode 100644 index 00000000..1a0652ae --- /dev/null +++ b/docs/api/resources/mesh/get-path.md @@ -0,0 +1,38 @@ +# Mesh::GetPath + +```cpp +const Containers::String& GetPath() const override; +``` + +返回网格资源的路径。路径用于资源定位和唯一标识。 + +**参数：** 无 + +**返回：** `const Containers::String&` - 资源路径的引用 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +IResource::ConstructParams params; +params.name = "Character_Hero"; +params.path = "assets/meshes/hero.mesh"; +params.guid = ResourceGUID::Generate(params.path); +mesh.Initialize(params); + +const String& path = mesh.GetPath(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-sections.md b/docs/api/resources/mesh/get-sections.md new file mode 100644 index 00000000..57b5c0a4 --- /dev/null +++ b/docs/api/resources/mesh/get-sections.md @@ -0,0 +1,40 @@ +# Mesh::GetSections + +```cpp +const Containers::Array& GetSections() const; +``` + +获取网格的所有分段信息。 + +**参数：** 无 + +**返回：** `const Containers::Array&` - 分段数组的只读引用 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); +mesh.SetIndexData(...); +mesh.AddSection(...); + +const auto& sections = mesh.GetSections(); +for (size_t i = 0; i < sections.Size(); ++i) { + const MeshSection& section = sections[i]; + // 处理每个分段 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-type.md b/docs/api/resources/mesh/get-type.md new file mode 100644 index 00000000..e9531edd --- /dev/null +++ b/docs/api/resources/mesh/get-type.md @@ -0,0 +1,34 @@ +# Mesh::GetType + +```cpp +ResourceType GetType() const override; +``` + +返回资源的类型标识符。对于 Mesh 类，返回值为 `ResourceType::Mesh`。 + +**参数：** 无 + +**返回：** `ResourceType` - 资源类型，恒定为 `ResourceType::Mesh` + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +if (mesh.GetType() == ResourceType::Mesh) { + // 这是一个网格资源 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-vertex-attributes.md b/docs/api/resources/mesh/get-vertex-attributes.md new file mode 100644 index 00000000..1409a0a8 --- /dev/null +++ b/docs/api/resources/mesh/get-vertex-attributes.md @@ -0,0 +1,43 @@ +# Mesh::GetVertexAttributes + +```cpp +VertexAttribute GetVertexAttributes() const; +``` + +获取网格的顶点属性标志，表示网格包含哪些顶点数据通道。 + +**参数：** 无 + +**返回：** `VertexAttribute` - 顶点属性标志，可通过按位与检查特定属性 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData( + ..., + VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0 +); + +VertexAttribute attrs = mesh.GetVertexAttributes(); +if (attrs & VertexAttribute::Normal) { + // 网格包含法线数据 +} +if (attrs & VertexAttribute::UV0) { + // 网格包含第一组 UV 坐标 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-vertex-count.md b/docs/api/resources/mesh/get-vertex-count.md new file mode 100644 index 00000000..85eee763 --- /dev/null +++ b/docs/api/resources/mesh/get-vertex-count.md @@ -0,0 +1,34 @@ +# Mesh::GetVertexCount + +```cpp +Core::uint32 GetVertexCount() const; +``` + +获取网格的顶点数量。 + +**参数：** 无 + +**返回：** `Core::uint32` - 顶点数量 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); + +uint32_t vertexCount = mesh.GetVertexCount(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-vertex-data-size.md b/docs/api/resources/mesh/get-vertex-data-size.md new file mode 100644 index 00000000..9a2ad102 --- /dev/null +++ b/docs/api/resources/mesh/get-vertex-data-size.md @@ -0,0 +1,34 @@ +# Mesh::GetVertexDataSize + +```cpp +size_t GetVertexDataSize() const; +``` + +获取网格顶点数据的总字节数。 + +**参数：** 无 + +**返回：** `size_t` - 顶点数据字节数 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); + +size_t dataSize = mesh.GetVertexDataSize(); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-vertex-data.md b/docs/api/resources/mesh/get-vertex-data.md new file mode 100644 index 00000000..6fb37123 --- /dev/null +++ b/docs/api/resources/mesh/get-vertex-data.md @@ -0,0 +1,37 @@ +# Mesh::GetVertexData + +```cpp +const void* GetVertexData() const; +``` + +获取网格顶点数据的只读指针。 + +**参数：** 无 + +**返回：** `const void*` - 顶点数据指针，如果没有设置则返回 nullptr + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); + +const void* vertexData = mesh.GetVertexData(); +if (vertexData != nullptr) { + // 安全访问顶点数据 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/get-vertex-stride.md b/docs/api/resources/mesh/get-vertex-stride.md new file mode 100644 index 00000000..9c5807c9 --- /dev/null +++ b/docs/api/resources/mesh/get-vertex-stride.md @@ -0,0 +1,41 @@ +# Mesh::GetVertexStride + +```cpp +Core::uint32 GetVertexStride() const; +``` + +获取单个顶点的字节大小（步长）。 + +**参数：** 无 + +**返回：** `Core::uint32` - 顶点步长（字节） + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +struct Vertex { + float position[3]; + float normal[3]; + float uv[2]; +}; + +Mesh mesh; +mesh.SetVertexData(..., sizeof(Vertex), ...); + +uint32_t stride = mesh.GetVertexStride(); +// stride == sizeof(Vertex) +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/is-use-32bit-index.md b/docs/api/resources/mesh/is-use-32bit-index.md new file mode 100644 index 00000000..d38a7995 --- /dev/null +++ b/docs/api/resources/mesh/is-use-32bit-index.md @@ -0,0 +1,40 @@ +# Mesh::IsUse32BitIndex + +```cpp +bool IsUse32BitIndex() const; +``` + +检查网格是否使用 32 位索引格式。如果返回 false，则表示使用 16 位索引格式。 + +**参数：** 无 + +**返回：** `bool` - true 表示使用 32 位索引，false 表示使用 16 位索引 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetIndexData(..., 6, true); // 32 位索引 + +if (mesh.IsUse32BitIndex()) { + // 使用 32 位索引访问 + const uint32_t* indices = static_cast(mesh.GetIndexData()); +} else { + // 使用 16 位索引访问 + const uint16_t* indices = static_cast(mesh.GetIndexData()); +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/is-valid.md b/docs/api/resources/mesh/is-valid.md new file mode 100644 index 00000000..79512e4f --- /dev/null +++ b/docs/api/resources/mesh/is-valid.md @@ -0,0 +1,44 @@ +# Mesh::IsValid + +```cpp +bool IsValid() const override; +``` + +检查网格资源是否有效。资源在调用 `Initialize` 后变为有效，调用 `SetInvalid` 或 `Release` 后变为无效。 + +**参数：** 无 + +**返回：** `bool` - 资源是否有效 + +**异常：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +if (!mesh.IsValid()) { + // 资源尚未初始化 +} + +IResource::ConstructParams params; +params.name = "Cube"; +params.path = "assets/meshes/cube.mesh"; +params.guid = ResourceGUID::Generate(params.path); +mesh.Initialize(params); + +if (mesh.IsValid()) { + // 资源已初始化 +} +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/mesh.md b/docs/api/resources/mesh/mesh.md index 388275c6..a3600dec 100644 --- a/docs/api/resources/mesh/mesh.md +++ b/docs/api/resources/mesh/mesh.md @@ -2,149 +2,120 @@ **命名空间**: `XCEngine::Resources` -**类型**: `class` +**类型**: `class` (inherits from `IResource`) -**描述**: 网格资源类，管理 3D 模型的顶点数据、索引数据和网格分段信息。 +**头文件**: `XCEngine/Resources/Mesh.h` + +**描述**: 网格资源类，用于存储和管理 3D 网格数据，包括顶点数据、索引数据和网格分段信息 ## 概述 -`Mesh` 是 XCEngine 中的网格资源类，继承自 `IResource`。它管理网格的顶点数据（位置、法线、UV、切线、颜色、骨骼权重等）、索引数据和网格分段（submesh）。 - -## 头文件 - -```cpp -#include -``` - -## 枚举类型 - -### VertexAttribute - -顶点属性标志枚举（可组合）。 - -| 值 | 描述 | -|----|------| -| `Position` | 位置坐标 | -| `Normal` | 法线 | -| `Tangent` | 切线 | -| `Color` | 顶点颜色 | -| `UV0` | 第一组纹理坐标 | -| `UV1` | 第二组纹理坐标 | -| `UV2` | 第三组纹理坐标 | -| `UV3` | 第四组纹理坐标 | -| `BoneWeights` | 骨骼权重 | -| `BoneIndices` | 骨骼索引 | - -## MeshSection 结构体 - -网格分段（Submesh）描述。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `baseVertex` | `Core::uint32` | 基础顶点索引 | -| `vertexCount` | `Core::uint32` | 顶点数量 | -| `startIndex` | `Core::uint32` | 起始索引 | -| `indexCount` | `Core::uint32` | 索引数量 | -| `materialID` | `Core::uint32` | 对应材质 ID | +Mesh 类是 XCEngine 引擎中的核心资源类型之一，负责管理 3D 模型的网格数据。它存储顶点属性（位置、法线、切线、UV 坐标、骨骼权重等）、索引数据以及网格分段（MeshSection）信息。Mesh 资源通常由资源加载器从外部文件（如 .obj、.fbx 等格式）加载，或通过程序化方式生成。 ## 公共方法 -### 基础属性 - | 方法 | 描述 | |------|------| -| `ResourceType GetType() const` | 返回 `ResourceType::Mesh` | -| `const Containers::String& GetName() const` | 获取网格名称 | -| `const Containers::String& GetPath() const` | 获取网格路径 | -| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 | -| `bool IsValid() const` | 检查网格是否有效 | -| `size_t GetMemorySize() const` | 获取内存大小 | -| `void Release()` | 释放网格引用 | +| [`Mesh`](constructor.md) | 构造函数 | +| [`~Mesh`](destructor.md) | 析构函数 | +| [`GetType`](get-type.md) | 获取资源类型 | +| [`GetName`](get-name.md) | 获取资源名称 | +| [`GetPath`](get-path.md) | 获取资源路径 | +| [`GetGUID`](get-guid.md) | 获取资源全局唯一标识符 | +| [`IsValid`](is-valid.md) | 检查资源是否有效 | +| [`GetMemorySize`](get-memory-size.md) | 获取资源内存大小 | +| [`Release`](release.md) | 释放资源 | +| [`SetVertexData`](set-vertex-data.md) | 设置顶点数据 | +| [`GetVertexData`](get-vertex-data.md) | 获取顶点数据指针 | +| [`GetVertexDataSize`](get-vertex-data-size.md) | 获取顶点数据大小 | +| [`GetVertexCount`](get-vertex-count.md) | 获取顶点数量 | +| [`GetVertexStride`](get-vertex-stride.md) | 获取顶点步长 | +| [`GetVertexAttributes`](get-vertex-attributes.md) | 获取顶点属性 | +| [`SetIndexData`](set-index-data.md) | 设置索引数据 | +| [`GetIndexData`](get-index-data.md) | 获取索引数据指针 | +| [`GetIndexDataSize`](get-index-data-size.md) | 获取索引数据大小 | +| [`GetIndexCount`](get-index-count.md) | 获取索引数量 | +| [`IsUse32BitIndex`](is-use-32bit-index.md) | 是否使用 32 位索引 | +| [`AddSection`](add-section.md) | 添加网格分段 | +| [`GetSections`](get-sections.md) | 获取所有网格分段 | -### 顶点数据 +## 相关类型 -| 方法 | 描述 | -|------|------| -| `void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, Core::uint32 vertexStride, VertexAttribute attributes)` | 设置顶点数据 | -| `const void* GetVertexData() const` | 获取顶点数据指针 | -| `size_t GetVertexDataSize() const` | 获取顶点数据大小 | -| `Core::uint32 GetVertexCount() const` | 获取顶点数量 | -| `Core::uint32 GetVertexStride() const` | 获取顶点结构体大小（字节） | -| `VertexAttribute GetVertexAttributes() const` | 获取顶点属性标志 | +### VertexAttribute -### 索引数据 +```cpp +enum class VertexAttribute : Core::uint32 { + Position = 1 << 0, + Normal = 1 << 1, + Tangent = 1 << 2, + Color = 1 << 3, + UV0 = 1 << 4, + UV1 = 1 << 5, + UV2 = 1 << 6, + UV3 = 1 << 7, + BoneWeights = 1 << 8, + BoneIndices = 1 << 9 +}; +``` -| 方法 | 描述 | -|------|------| -| `void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit)` | 设置索引数据 | -| `const void* GetIndexData() const` | 获取索引数据指针 | -| `size_t GetIndexDataSize() const` | 获取索引数据大小 | -| `Core::uint32 GetIndexCount() const` | 获取索引数量 | -| `bool IsUse32BitIndex() const` | 是否使用 32 位索引 | +顶点属性枚举，用于指定网格包含哪些顶点数据通道。多个属性可以通过按位或组合使用。 -### 网格分段 +### MeshSection -| 方法 | 描述 | -|------|------| -| `void AddSection(const MeshSection& section)` | 添加网格分段 | -| `const Containers::Array& GetSections() const` | 获取所有分段 | +```cpp +struct MeshSection { + Core::uint32 baseVertex; + Core::uint32 vertexCount; + Core::uint32 startIndex; + Core::uint32 indexCount; + Core::uint32 materialID; +}; +``` + +网格分段结构，描述网格中某个子网格的区域信息，包括顶点范围、索引范围和材质 ID。 ## 使用示例 ```cpp -// 加载网格 -ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); +#include "XCEngine/Resources/Mesh.h" +#include "XCEngine/Containers/Array.h" -// 手动设置顶点数据 -struct Vertex { - float position[3]; - float normal[3]; - float uv[2]; -}; +using namespace XCEngine; +using namespace Resources; -Containers::Array vertices; -vertices.Resize(vertexCount); -// ... 填充顶点数据 ... +void CreateQuadMesh(Mesh* outMesh) { + struct Vertex { + float position[3]; + float normal[3]; + float uv[2]; + }; -mesh->SetVertexData( - vertices.Data(), - vertices.Size() * sizeof(Vertex), - vertexCount, - sizeof(Vertex), - VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0 -); + Vertex vertices[4] = { + {{-0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 0.0f}}, + {{ 0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 0.0f}}, + {{ 0.5f, 0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 1.0f}}, + {{-0.5f, 0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 1.0f}} + }; -// 设置索引数据 -Containers::Array indices; -indices.Resize(indexCount); -// ... 填充索引数据 ... + uint32_t indices[6] = {0, 1, 2, 0, 2, 3}; -mesh->SetIndexData( - indices.Data(), - indices.Size() * sizeof(uint32_t), - indexCount, - true // 32 位索引 -); + VertexAttribute attributes = VertexAttribute::Position | + VertexAttribute::Normal | + VertexAttribute::UV0; -// 添加分段（一个网格可能有多个材质） -MeshSection section; -section.baseVertex = 0; -section.vertexCount = vertexCount; -section.startIndex = 0; -section.indexCount = indexCount; -section.materialID = 0; -mesh->AddSection(section); + outMesh->SetVertexData(vertices, sizeof(vertices), 4, sizeof(Vertex), attributes); + outMesh->SetIndexData(indices, sizeof(indices), 6, false); -// 访问数据 -uint32_t vCount = mesh->GetVertexCount(); -uint32_t iCount = mesh->GetIndexCount(); -auto sections = mesh->GetSections(); + MeshSection section; + section.baseVertex = 0; + section.vertexCount = 4; + section.startIndex = 0; + section.indexCount = 6; + section.materialID = 0; + outMesh->AddSection(section); +} ``` ## 相关文档 - [IResource](../iresource/iresource.md) - 资源基类 -- [Material](../material/material.md) - 材质资源 -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 -- [Resources 总览](../resources.md) - 返回模块总览 -- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据 diff --git a/docs/api/resources/mesh/meshsection.md b/docs/api/resources/mesh/meshsection.md new file mode 100644 index 00000000..73bd0c32 --- /dev/null +++ b/docs/api/resources/mesh/meshsection.md @@ -0,0 +1,38 @@ +# MeshSection + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**描述**: 网格分段结构体，用于描述网格的一部分，支持多材质渲染。 + +## 概述 + +MeshSection 定义了网格的一个连续区域，每个区域可以有不同的材质。网格分段包含顶点和索引范围信息，以及关联的材质 ID。 + +## 成员变量 + +| 变量 | 类型 | 描述 | +|------|------|------| +| `baseVertex` | `Core::uint32` | 基准顶点偏移 | +| `vertexCount` | `Core::uint32` | 顶点数量 | +| `startIndex` | `Core::uint32` | 起始索引 | +| `indexCount` | `Core::uint32` | 索引数量 | +| `materialID` | `Core::uint32` | 材质 ID | + +## 使用示例 + +```cpp +MeshSection section; +section.baseVertex = 0; +section.vertexCount = 4; +section.startIndex = 0; +section.indexCount = 6; +section.materialID = 0; +mesh.AddSection(section); +``` + +## 相关文档 + +- [Mesh 类总览](mesh.md) - 返回类总览 +- [AddSection](./addsection.md) - 添加网格分段 diff --git a/docs/api/resources/mesh/release.md b/docs/api/resources/mesh/release.md new file mode 100644 index 00000000..86260f5f --- /dev/null +++ b/docs/api/resources/mesh/release.md @@ -0,0 +1,41 @@ +# Mesh::Release + +```cpp +void Release() override; +``` + +释放网格资源持有的所有数据。将清空顶点数据、索引数据和所有网格分段信息，并将相关计数重置为 0。 + +**参数：** 无 + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n) - n 为数据大小 + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); +mesh.SetIndexData(...); +mesh.AddSection(...); + +// 使用完毕，释放数据 +mesh.Release(); + +// 释放后所有数据清空 +assert(mesh.GetVertexCount() == 0); +assert(mesh.GetIndexCount() == 0); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/set-index-data.md b/docs/api/resources/mesh/set-index-data.md new file mode 100644 index 00000000..a17e7572 --- /dev/null +++ b/docs/api/resources/mesh/set-index-data.md @@ -0,0 +1,44 @@ +# Mesh::SetIndexData + +```cpp +void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit); +``` + +设置网格的索引数据。此方法会复制传入的数据到内部缓冲区。 + +**参数：** +- `data` - 索引数据指针，不能为 nullptr +- `size` - 索引数据总字节数 +- `indexCount` - 索引数量 +- `use32Bit` - 是否使用 32 位索引，false 则使用 16 位索引 + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n) - n 为索引数据大小 + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +Mesh mesh; +mesh.SetVertexData(...); + +// 使用 16 位索引（最多 65536 个顶点） +uint16_t indices16[6] = {0, 1, 2, 0, 2, 3}; +mesh.SetIndexData(indices16, sizeof(indices16), 6, false); + +// 或使用 32 位索引 +uint32_t indices32[6] = {0, 1, 2, 0, 2, 3}; +mesh.SetIndexData(indices32, sizeof(indices32), 6, true); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/set-vertex-data.md b/docs/api/resources/mesh/set-vertex-data.md new file mode 100644 index 00000000..e237b717 --- /dev/null +++ b/docs/api/resources/mesh/set-vertex-data.md @@ -0,0 +1,57 @@ +# Mesh::SetVertexData + +```cpp +void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, + Core::uint32 vertexStride, VertexAttribute attributes); +``` + +设置网格的顶点数据。此方法会复制传入的数据到内部缓冲区。 + +**参数：** +- `data` - 顶点数据指针，不能为 nullptr +- `size` - 顶点数据总字节数 +- `vertexCount` - 顶点数量 +- `vertexStride` - 单个顶点的字节大小 +- `attributes` - 顶点属性标志，指定数据包含哪些顶点通道 + +**返回：** 无 + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n) - n 为顶点数据大小 + +**示例：** + +```cpp +#include "XCEngine/Resources/Mesh.h" + +using namespace XCEngine::Resources; + +struct Vertex { + float position[3]; + float normal[3]; + float uv[2]; +}; + +Vertex vertices[4] = { + {{-0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 0.0f}}, + {{ 0.5f, -0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 0.0f}}, + {{ 0.5f, 0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {1.0f, 1.0f}}, + {{-0.5f, 0.5f, 0.0f}, {0.0f, 0.0f, 1.0f}, {0.0f, 1.0f}} +}; + +Mesh mesh; +mesh.SetVertexData( + vertices, + sizeof(vertices), + 4, + sizeof(Vertex), + VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0 +); +``` + +## 相关文档 + +- [类总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/setindexdata.md b/docs/api/resources/mesh/setindexdata.md deleted file mode 100644 index 06fd6153..00000000 --- a/docs/api/resources/mesh/setindexdata.md +++ /dev/null @@ -1,30 +0,0 @@ -# Mesh::SetIndexData - -```cpp -void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit) -``` - -设置网格索引数据。复制索引缓冲数据到内部存储。 - -**参数：** -- `data` - 索引数据指针 -- `size` - 数据大小（字节） -- `indexCount` - 索引数量 -- `use32Bit` - 是否使用 32 位索引（否则使用 16 位） - -**返回：** 无 - -**复杂度：** O(n)，n 为索引数据大小 - -**示例：** - -```cpp -Containers::Array indices; -// ... 填充索引数据 ... -mesh->SetIndexData(indices.Data(), indices.Size() * sizeof(uint32_t), - indices.Size(), true); -``` - -## 相关文档 - -- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/setvertexdata.md b/docs/api/resources/mesh/setvertexdata.md deleted file mode 100644 index 38c5754d..00000000 --- a/docs/api/resources/mesh/setvertexdata.md +++ /dev/null @@ -1,37 +0,0 @@ -# Mesh::SetVertexData - -```cpp -void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, - Core::uint32 vertexStride, VertexAttribute attributes) -``` - -设置网格顶点数据。复制顶点缓冲数据到内部存储。 - -**参数：** -- `data` - 顶点数据指针 -- `size` - 数据大小（字节） -- `vertexCount` - 顶点数量 -- `vertexStride` - 单个顶点结构体大小（字节） -- `attributes` - 顶点属性标志组合 - -**返回：** 无 - -**复杂度：** O(n)，n 为顶点数据大小 - -**示例：** - -```cpp -struct Vertex { - float position[3]; - float normal[3]; - float uv[2]; -}; - -mesh->SetVertexData(vertices.Data(), vertices.Size() * sizeof(Vertex), - vertexCount, sizeof(Vertex), - VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0); -``` - -## 相关文档 - -- [Mesh 总览](mesh.md) - 返回类总览 diff --git a/docs/api/resources/mesh/vertexattribute.md b/docs/api/resources/mesh/vertexattribute.md new file mode 100644 index 00000000..39429d44 --- /dev/null +++ b/docs/api/resources/mesh/vertexattribute.md @@ -0,0 +1,37 @@ +# VertexAttribute + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**描述**: 顶点属性标志枚举，用于指定网格顶点包含哪些属性。 + +## 概述 + +VertexAttribute 是位标志枚举，用于描述顶点缓冲中包含的顶点属性类型。每种属性对应一个比特位，可以组合使用。 + +## 枚举值 + +| 值 | 描述 | +|----|------| +| `Position` | 顶点位置 (x, y, z) | +| `Normal` | 法线向量 (x, y, z) | +| `Tangent` | 切线向量 (x, y, z) | +| `Color` | 顶点颜色 (r, g, b, a) | +| `UV0` | 第一组 UV 坐标 | +| `UV1` | 第二组 UV 坐标 | +| `UV2` | 第三组 UV 坐标 | +| `UV3` | 第四组 UV 坐标 | +| `BoneWeights` | 骨骼权重 | +| `BoneIndices` | 骨骼索引 | + +## 使用示例 + +```cpp +VertexAttribute attributes = VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0; +``` + +## 相关文档 + +- [Mesh 类总览](mesh.md) - 返回类总览 +- [SetVertexData](./setvertexdata.md) - 设置顶点数据 diff --git a/docs/api/resources/resource-dependency-graph/add-dependency.md b/docs/api/resources/resource-dependency-graph/add-dependency.md new file mode 100644 index 00000000..c9c04aa4 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/add-dependency.md @@ -0,0 +1,36 @@ +# AddDependency + +添加资源之间的依赖关系。 + +## 方法签名 + +```cpp +void AddDependency(ResourceGUID owner, ResourceGUID dependency); +``` + +## 详细描述 + +在两个已存在的节点之间建立依赖关系。`owner` 节点依赖于 `dependency` 节点，即 `dependency` 会被 `owner` 使用。该方法会同时更新两个节点的关联数组： +- 将 `dependency` 添加到 `owner` 的 `dependencies` 列表 +- 将 `owner` 添加到 `dependency` 的 `dependents` 列表 + +如果任一节点不存在或依赖关系已存在，则不做任何操作。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `owner` | `ResourceGUID` | 依赖方（被依赖项的使用者）的全局唯一标识符 | +| `dependency` | `ResourceGUID` | 被依赖项（owner 所依赖的资源）的全局唯一标识符 | + +## 返回值 + +无 + +## 示例 + +```cpp +graph.AddNode("material"_guid, ResourceType::Material); +graph.AddNode("texture"_guid, ResourceType::Texture); +graph.AddDependency("material"_guid, "texture"_guid); // material 依赖 texture +``` diff --git a/docs/api/resources/resource-dependency-graph/add-node.md b/docs/api/resources/resource-dependency-graph/add-node.md new file mode 100644 index 00000000..1a2e0422 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/add-node.md @@ -0,0 +1,32 @@ +# AddNode + +添加资源节点到依赖图中。 + +## 方法签名 + +```cpp +void AddNode(ResourceGUID guid, ResourceType type); +``` + +## 详细描述 + +将指定资源添加为依赖图中的新节点。如果节点已存在，则不做任何操作。该方法会创建一个带有空依赖关系和被依赖关系列表的新节点，初始引用计数为 0。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要添加的资源的全局唯一标识符 | +| `type` | `ResourceType` | 资源类型 | + +## 返回值 + +无 + +## 示例 + +```cpp +ResourceDependencyGraph graph; +graph.AddNode("texture_albedo"_guid, ResourceType::Texture); +graph.AddNode("material_standard"_guid, ResourceType::Material); +``` diff --git a/docs/api/resources/resource-dependency-graph/clear.md b/docs/api/resources/resource-dependency-graph/clear.md new file mode 100644 index 00000000..5d4e22da --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/clear.md @@ -0,0 +1,30 @@ +# Clear + +清空整个依赖图。 + +## 方法签名 + +```cpp +void Clear(); +``` + +## 详细描述 + +移除所有节点并清空内部数据结构。调用此方法后，依赖图将处于空状态，所有之前添加的节点和依赖关系都将被销毁。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +graph.AddNode("A"_guid, ResourceType::Texture); +graph.AddNode("B"_guid, ResourceType::Material); +graph.Clear(); +// 现在依赖图为空 +``` diff --git a/docs/api/resources/resource-dependency-graph/decrement-ref-count.md b/docs/api/resources/resource-dependency-graph/decrement-ref-count.md new file mode 100644 index 00000000..177d9da9 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/decrement-ref-count.md @@ -0,0 +1,32 @@ +# DecrementRefCount + +减少资源的引用计数。 + +## 方法签名 + +```cpp +void DecrementRefCount(ResourceGUID guid); +``` + +## 详细描述 + +原子地减少指定资源的引用计数。引用计数不会减少到 0 以下。如果节点不存在或引用计数已为 0，则不做任何操作。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 | + +## 返回值 + +无 + +## 示例 + +```cpp +graph.IncrementRefCount("texture"_guid); +graph.IncrementRefCount("texture"_guid); +graph.DecrementRefCount("texture"_guid); // refCount 现在为 1 +graph.DecrementRefCount("texture"_guid); // refCount 现在为 0 +``` diff --git a/docs/api/resources/resource-dependency-graph/get-all-dependencies.md b/docs/api/resources/resource-dependency-graph/get-all-dependencies.md new file mode 100644 index 00000000..941320c6 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/get-all-dependencies.md @@ -0,0 +1,41 @@ +# GetAllDependencies + +获取资源的完整依赖链（递归）。 + +## 方法签名 + +```cpp +Containers::Array GetAllDependencies(ResourceGUID guid) const; +``` + +## 详细描述 + +使用深度优先搜索递归获取指定资源的所有传递依赖项，返回完整的依赖链。返回结果不包括 `guid` 自身，且每个资源 GUID 只出现一次（即使有多个路径依赖该资源）。 + +搜索算法使用栈实现 DFS，遍历所有依赖项及其子依赖项。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 | + +## 返回值 + +`Containers::Array` - 完整依赖链的 GUID 数组 + +## 示例 + +```cpp +// 假设依赖关系: A -> B -> C -> D +graph.AddNode("A"_guid, ResourceType::Material); +graph.AddNode("B"_guid, ResourceType::Texture); +graph.AddNode("C"_guid, ResourceType::Image); +graph.AddNode("D"_guid, ResourceType::File); +graph.AddDependency("A"_guid, "B"_guid); +graph.AddDependency("B"_guid, "C"_guid); +graph.AddDependency("C"_guid, "D"_guid); + +auto allDeps = graph.GetAllDependencies("A"_guid); +// allDeps 包含 ["B", "C", "D"]（顺序可能因实现而异） +``` diff --git a/docs/api/resources/resource-dependency-graph/get-dependencies.md b/docs/api/resources/resource-dependency-graph/get-dependencies.md new file mode 100644 index 00000000..605ef49c --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/get-dependencies.md @@ -0,0 +1,38 @@ +# GetDependencies + +获取资源的直接依赖项列表。 + +## 方法签名 + +```cpp +Containers::Array GetDependencies(ResourceGUID guid) const; +``` + +## 详细描述 + +返回指定资源直接依赖的所有资源 GUID 数组。这些是 `guid` 节点在 `dependencies` 数组中存储的资源，仅包含一层依赖关系，不包括传递依赖。 + +如果指定节点不存在，返回空数组。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 | + +## 返回值 + +`Containers::Array` - 直接依赖项的 GUID 数组 + +## 示例 + +```cpp +graph.AddNode("material"_guid, ResourceType::Material); +graph.AddNode("texture1"_guid, ResourceType::Texture); +graph.AddNode("texture2"_guid, ResourceType::Texture); +graph.AddDependency("material"_guid, "texture1"_guid); +graph.AddDependency("material"_guid, "texture2"_guid); + +auto deps = graph.GetDependencies("material"_guid); +// deps 包含 ["texture1", "texture2"] +``` diff --git a/docs/api/resources/resource-dependency-graph/get-dependents.md b/docs/api/resources/resource-dependency-graph/get-dependents.md new file mode 100644 index 00000000..d83d68bc --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/get-dependents.md @@ -0,0 +1,38 @@ +# GetDependents + +获取资源的直接被依赖项列表。 + +## 方法签名 + +```cpp +Containers::Array GetDependents(ResourceGUID guid) const; +``` + +## 详细描述 + +返回直接依赖指定资源的所有资源 GUID 数组。这些是 `guid` 节点在 `dependents` 数组中存储的资源，仅包含一层被依赖关系，不包括传递被依赖项。 + +如果指定节点不存在，返回空数组。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要查询的资源的全局唯一标识符 | + +## 返回值 + +`Containers::Array` - 直接被依赖项的 GUID 数组 + +## 示例 + +```cpp +graph.AddNode("texture"_guid, ResourceType::Texture); +graph.AddNode("material1"_guid, ResourceType::Material); +graph.AddNode("material2"_guid, ResourceType::Material); +graph.AddDependency("material1"_guid, "texture"_guid); +graph.AddDependency("material2"_guid, "texture"_guid); + +auto deps = graph.GetDependents("texture"_guid); +// deps 包含 ["material1", "material2"] +``` diff --git a/docs/api/resources/resource-dependency-graph/get-ref-count.md b/docs/api/resources/resource-dependency-graph/get-ref-count.md new file mode 100644 index 00000000..f912eb24 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/get-ref-count.md @@ -0,0 +1,31 @@ +# GetRefCount + +获取资源的引用计数。 + +## 方法签名 + +```cpp +Core::uint32 GetRefCount(ResourceGUID guid) const; +``` + +## 详细描述 + +返回指定资源的当前引用计数。如果节点不存在，返回 0。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 | + +## 返回值 + +`Core::uint32` - 当前引用计数，如果节点不存在则返回 0 + +## 示例 + +```cpp +graph.IncrementRefCount("texture"_guid); +graph.IncrementRefCount("texture"_guid); +uint32 count = graph.GetRefCount("texture"_guid); // 返回 2 +``` diff --git a/docs/api/resources/resource-dependency-graph/has-circular-dependency.md b/docs/api/resources/resource-dependency-graph/has-circular-dependency.md new file mode 100644 index 00000000..fcdbbf3c --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/has-circular-dependency.md @@ -0,0 +1,36 @@ +# HasCircularDependency + +检测资源是否存在循环依赖。 + +## 方法签名 + +```cpp +bool HasCircularDependency(ResourceGUID guid, Containers::Array& outCycle) const; +``` + +## 详细描述 + +检测从指定资源出发是否存在循环依赖关系。算法使用深度优先搜索遍历依赖图，如果发现在同一条路径上访问同一个节点两次，则说明存在循环依赖。 + +当检测到循环时，`outCycle` 参数将被填充为从起点到循环点的路径（包含循环点）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 起始资源的全局唯一标识符 | +| `outCycle` | `Containers::Array&` | 输出参数，接收检测到的循环路径 | + +## 返回值 + +`bool` - 如果存在循环依赖返回 `true`，否则返回 `false` + +## 示例 + +```cpp +// 假设存在循环: A -> B -> C -> A +Containers::Array cycle; +if (graph.HasCircularDependency("A"_guid, cycle)) { + // cycle 包含类似 ["A", "B", "C", "A"] 的路径 +} +``` diff --git a/docs/api/resources/resource-dependency-graph/has-node.md b/docs/api/resources/resource-dependency-graph/has-node.md new file mode 100644 index 00000000..9c03aaa1 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/has-node.md @@ -0,0 +1,31 @@ +# HasNode + +检查节点是否存在。 + +## 方法签名 + +```cpp +bool HasNode(ResourceGUID guid) const; +``` + +## 详细描述 + +检查指定资源节点是否存在于依赖图中。这是在添加依赖关系前验证节点是否存在的常用方法。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要检查的资源的全局唯一标识符 | + +## 返回值 + +`bool` - 如果节点存在返回 `true`，否则返回 `false` + +## 示例 + +```cpp +graph.AddNode("texture"_guid, ResourceType::Texture); +bool exists = graph.HasNode("texture"_guid); // 返回 true +bool notExists = graph.HasNode("unknown"_guid); // 返回 false +``` diff --git a/docs/api/resources/resource-dependency-graph/increment-ref-count.md b/docs/api/resources/resource-dependency-graph/increment-ref-count.md new file mode 100644 index 00000000..466054fe --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/increment-ref-count.md @@ -0,0 +1,32 @@ +# IncrementRefCount + +增加资源的引用计数。 + +## 方法签名 + +```cpp +void IncrementRefCount(ResourceGUID guid); +``` + +## 详细描述 + +原子地增加指定资源的引用计数。引用计数用于追踪资源被多少其他资源或系统引用。当引用计数大于 0 时，资源不能被卸载。 + +如果节点不存在，则不做任何操作。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 | + +## 返回值 + +无 + +## 示例 + +```cpp +graph.IncrementRefCount("texture"_guid); +graph.IncrementRefCount("texture"_guid); // refCount 现在为 2 +``` diff --git a/docs/api/resources/resource-dependency-graph/index.md b/docs/api/resources/resource-dependency-graph/index.md new file mode 100644 index 00000000..bb5cee84 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/index.md @@ -0,0 +1,94 @@ +# ResourceDependencyGraph + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (`class`) + +## 描述 + +资源依赖图管理器，用于跟踪和管理资源之间的依赖关系。该类维护一个双向依赖图，支持添加/移除节点和依赖关系、查询依赖链、循环依赖检测、引用计数管理以及拓扑排序。 + +## 概述 + +`ResourceDependencyGraph` 提供了一套完整的资源依赖关系管理机制。每个资源被表示为一个节点，节点之间通过有向边建立依赖关系。类内部维护两个方向的关系： +- **依赖项** (dependencies): 当前资源直接依赖的资源 +- **被依赖项** (dependents): 直接依赖当前资源的资源 + +该图结构支持： +- 双向依赖查询 +- 递归获取完整依赖链 +- 循环依赖检测 +- 引用计数追踪 +- 拓扑排序以确定资源加载/卸载顺序 + +## 公共方法表格 + +| 方法 | 描述 | +|------|------| +| `AddNode(ResourceGUID guid, ResourceType type)` | 添加资源节点到依赖图 | +| `RemoveNode(ResourceGUID guid)` | 从依赖图中移除资源节点 | +| `AddDependency(ResourceGUID owner, ResourceGUID dependency)` | 添加依赖关系 | +| `RemoveDependency(ResourceGUID owner, ResourceGUID dependency)` | 移除依赖关系 | +| `GetDependencies(ResourceGUID guid)` | 获取资源的直接依赖项 | +| `GetDependents(ResourceGUID guid)` | 获取资源的直接被依赖项 | +| `GetAllDependencies(ResourceGUID guid)` | 获取资源的完整依赖链（递归） | +| `IncrementRefCount(ResourceGUID guid)` | 增加资源引用计数 | +| `DecrementRefCount(ResourceGUID guid)` | 减少资源引用计数 | +| `GetRefCount(ResourceGUID guid)` | 获取资源引用计数 | +| `HasCircularDependency(ResourceGUID guid, Containers::Array& outCycle)` | 检测是否存在循环依赖 | +| `TopologicalSort()` | 对所有资源节点进行拓扑排序 | +| `Unload(ResourceGUID guid)` | 检查资源是否可以卸载 | +| `Clear()` | 清空整个依赖图 | +| `HasNode(ResourceGUID guid)` | 检查节点是否存在 | + +## 使用示例 + +```cpp +#include "Resources/ResourceDependencyGraph.h" + +using namespace XCEngine; +using namespace Resources; + +void Example() { + ResourceDependencyGraph graph; + + // 添加资源节点 + graph.AddNode("texture_albedo"_guid, ResourceType::Texture); + graph.AddNode("material_standard"_guid, ResourceType::Material); + graph.AddNode("mesh_cube"_guid, ResourceType::Mesh); + + // 建立依赖关系 + graph.AddDependency("material_standard"_guid, "texture_albedo"_guid); + graph.AddDependency("mesh_cube"_guid, "material_standard"_guid); + + // 查询依赖 + auto deps = graph.GetDependencies("material_standard"_guid); // 返回 ["texture_albedo"] + auto allDeps = graph.GetAllDependencies("mesh_cube"_guid); // 返回 ["material_standard", "texture_albedo"] + + // 引用计数管理 + graph.IncrementRefCount("texture_albedo"_guid); + graph.IncrementRefCount("texture_albedo"_guid); + uint32 count = graph.GetRefCount("texture_albedo"_guid); // 返回 2 + + // 检测循环依赖 + Containers::Array cycle; + if (graph.HasCircularDependency("mesh_cube"_guid, cycle)) { + // 处理循环依赖 + } + + // 检查是否可以卸载 + if (graph.Unload("texture_albedo"_guid)) { + // 可以卸载 + } +} +``` + +## 相关文档 + +- [ResourceTypes](./resource-types.md) +- [ResourceManager](../resource-manager/resource-manager.md) +- [ResourcePool](./resource-pool.md) diff --git a/docs/api/resources/resource-dependency-graph/remove-dependency.md b/docs/api/resources/resource-dependency-graph/remove-dependency.md new file mode 100644 index 00000000..e7be87ea --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/remove-dependency.md @@ -0,0 +1,34 @@ +# RemoveDependency + +移除资源之间的依赖关系。 + +## 方法签名 + +```cpp +void RemoveDependency(ResourceGUID owner, ResourceGUID dependency); +``` + +## 详细描述 + +移除两个节点之间的依赖关系。该方法会同时更新两个节点的关联数组： +- 从 `owner` 的 `dependencies` 列表中移除 `dependency` +- 从 `dependency` 的 `dependents` 列表中移除 `owner` + +如果任一节点不存在或依赖关系不存在，则不做任何操作。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `owner` | `ResourceGUID` | 依赖方的全局唯一标识符 | +| `dependency` | `ResourceGUID` | 被依赖项的全局唯一标识符 | + +## 返回值 + +无 + +## 示例 + +```cpp +graph.RemoveDependency("material"_guid, "texture"_guid); +``` diff --git a/docs/api/resources/resource-dependency-graph/remove-node.md b/docs/api/resources/resource-dependency-graph/remove-node.md new file mode 100644 index 00000000..077dd359 --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/remove-node.md @@ -0,0 +1,33 @@ +# RemoveNode + +从依赖图中移除资源节点。 + +## 方法签名 + +```cpp +void RemoveNode(ResourceGUID guid); +``` + +## 详细描述 + +从依赖图中移除指定节点。此操作不会自动移除与其他节点之间的依赖关系，这些关系需要在调用此方法前手动清除。该方法直接从内部哈希表中删除节点。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 要移除的资源的全局唯一标识符 | + +## 返回值 + +无 + +## 示例 + +```cpp +graph.RemoveNode("texture_albedo"_guid); +``` + +## 注意 + +移除节点前，建议先使用 `RemoveDependency` 清除该节点的所有依赖关系，以保持依赖图的一致性。 diff --git a/docs/api/resources/resource-dependency-graph/topological-sort.md b/docs/api/resources/resource-dependency-graph/topological-sort.md new file mode 100644 index 00000000..14db7fae --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/topological-sort.md @@ -0,0 +1,28 @@ +# TopologicalSort + +对所有资源节点进行拓扑排序。 + +## 方法签名 + +```cpp +Containers::Array TopologicalSort() const; +``` + +## 详细描述 + +返回所有资源节点的一种拓扑排序顺序，确保每个资源的所有依赖项都出现在该资源之前。该方法可用于确定资源的加载顺序。 + +## 参数 + +无 + +## 返回值 + +`Containers::Array` - 按拓扑顺序排列的资源 GUID 数组 + +## 示例 + +```cpp +auto sorted = graph.TopologicalSort(); +// 返回资源加载顺序 +``` diff --git a/docs/api/resources/resource-dependency-graph/unload.md b/docs/api/resources/resource-dependency-graph/unload.md new file mode 100644 index 00000000..c63a6e5e --- /dev/null +++ b/docs/api/resources/resource-dependency-graph/unload.md @@ -0,0 +1,39 @@ +# Unload + +检查资源是否可以卸载。 + +## 方法签名 + +```cpp +bool Unload(ResourceGUID guid); +``` + +## 详细描述 + +检查指定资源是否满足卸载条件。资源可以卸载当且仅当满足以下条件： +1. 节点存在于依赖图中 +2. 资源的引用计数为 0 +3. 所有直接依赖该资源的资源的引用计数也都为 0 + +该方法是一个检查函数，不会实际执行卸载操作。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `guid` | `ResourceGUID` | 目标资源的全局唯一标识符 | + +## 返回值 + +`bool` - 如果可以卸载返回 `true`，否则返回 `false` + +## 示例 + +```cpp +graph.IncrementRefCount("texture"_guid); +if (graph.Unload("texture"_guid)) { + // 不能卸载，因为引用计数 > 0 +} else { + // 检查失败 +} +``` diff --git a/docs/api/resources/resource-file-system/add-archive.md b/docs/api/resources/resource-file-system/add-archive.md new file mode 100644 index 00000000..ed87e7b8 --- /dev/null +++ b/docs/api/resources/resource-file-system/add-archive.md @@ -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` 被搜索 diff --git a/docs/api/resources/resource-file-system/add-directory.md b/docs/api/resources/resource-file-system/add-directory.md new file mode 100644 index 00000000..b0b38f62 --- /dev/null +++ b/docs/api/resources/resource-file-system/add-directory.md @@ -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"); +``` + +## 注意事项 + +- 目录搜索优先级：根路径 > 先添加的目录 +- 路径末尾的斜杠会自动处理 diff --git a/docs/api/resources/resource-file-system/enumerate-resources.md b/docs/api/resources/resource-file-system/enumerate-resources.md new file mode 100644 index 00000000..a0ce905a --- /dev/null +++ b/docs/api/resources/resource-file-system/enumerate-resources.md @@ -0,0 +1,63 @@ +# ResourceFileSystem::EnumerateResources + +## 方法签名 + +```cpp +void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const; +``` + +## 所属类 + +`XCEngine::Resources::ResourceFileSystem` + +## 描述 + +枚举所有匹配指定模式的资源。模式支持通配符（如 `*.png`、`textures/**` 等）。 + +此方法线程安全。 + +## 参数 + +| 参数名 | 类型 | 描述 | +|--------|------|------| +| `pattern` | `const Containers::String&` | 文件名匹配模式 | +| `outResources` | `Containers::Array&` | 输出容器，接收匹配的资源信息列表 | + +## 返回值 + +无 + +## 示例 + +```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 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); +``` + +## 注意事项 + +- 当前实现尚未完成，输出容器可能为空 +- 模式语法的具体支持情况待实现 diff --git a/docs/api/resources/resource-file-system/exists.md b/docs/api/resources/resource-file-system/exists.md new file mode 100644 index 00000000..aa096feb --- /dev/null +++ b/docs/api/resources/resource-file-system/exists.md @@ -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` 实现 +- 档案中的资源同样可以被检查 diff --git a/docs/api/resources/resource-file-system/find-resource.md b/docs/api/resources/resource-file-system/find-resource.md new file mode 100644 index 00000000..d9b08d05 --- /dev/null +++ b/docs/api/resources/resource-file-system/find-resource.md @@ -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` diff --git a/docs/api/resources/resource-file-system/get-resource-info.md b/docs/api/resources/resource-file-system/get-resource-info.md new file mode 100644 index 00000000..8617e790 --- /dev/null +++ b/docs/api/resources/resource-file-system/get-resource-info.md @@ -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 支持 diff --git a/docs/api/resources/resource-file-system/get.md b/docs/api/resources/resource-file-system/get.md new file mode 100644 index 00000000..3343133b --- /dev/null +++ b/docs/api/resources/resource-file-system/get.md @@ -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(); +``` + +## 注意事项 + +- 内部使用局部静态变量实现单例 +- 第一次调用时自动构造实例 +- 线程安全（局部静态变量初始化线程安全） diff --git a/docs/api/resources/resource-file-system/iarchive.md b/docs/api/resources/resource-file-system/iarchive.md new file mode 100644 index 00000000..0c0aec5f --- /dev/null +++ b/docs/api/resources/resource-file-system/iarchive.md @@ -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& outFiles) const = 0; +``` + +枚举档案内匹配指定模式的文件。 + +**参数：** +- `pattern` - 文件名匹配模式（支持通配符） +- `outFiles` - 输出容器，接收匹配的文件名列表 + +--- + +### IsValid + +```cpp +virtual bool IsValid() const = 0; +``` + +检查档案是否已正确打开且有效。 + +**返回值：** +- `bool` - 有效返回 `true`，无效返回 `false` diff --git a/docs/api/resources/resource-file-system/index.md b/docs/api/resources/resource-file-system/index.md new file mode 100644 index 00000000..83ebbbc4 --- /dev/null +++ b/docs/api/resources/resource-file-system/index.md @@ -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 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& 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 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 resources; +fs.EnumerateResources("textures/**/*.png", resources); +``` + +## 相关文档 + +- [IArchive 接口](iarchive.md) +- [ResourceInfo 结构](resource-info.md) diff --git a/docs/api/resources/resource-file-system/initialize.md b/docs/api/resources/resource-file-system/initialize.md new file mode 100644 index 00000000..a5482305 --- /dev/null +++ b/docs/api/resources/resource-file-system/initialize.md @@ -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()` 会重置根路径设置 diff --git a/docs/api/resources/resource-file-system/read-resource.md b/docs/api/resources/resource-file-system/read-resource.md new file mode 100644 index 00000000..e7db463f --- /dev/null +++ b/docs/api/resources/resource-file-system/read-resource.md @@ -0,0 +1,66 @@ +# ResourceFileSystem::ReadResource + +## 方法签名 + +```cpp +Containers::Array ReadResource(const Containers::String& relativePath) const; +``` + +## 所属类 + +`XCEngine::Resources::ResourceFileSystem` + +## 描述 + +读取指定相对路径的资源内容，以字节数组形式返回。该方法会首先查找资源的绝对路径，然后从文件系统读取数据。 + +此方法线程安全。 + +## 参数 + +| 参数名 | 类型 | 描述 | +|--------|------|------| +| `relativePath` | `const Containers::String&` | 资源的相对路径 | + +## 返回值 + +- `Containers::Array` - 资源数据的字节数组。如果读取失败或资源不存在，返回空数组。 + +## 示例 + +```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(pixels); +} + +// 读取不存在的资源 +auto invalidData = fs.ReadResource("nonexistent/file.txt"); +if (invalidData.Empty()) { + printf("Resource not found or read error\n"); +} +``` + +## 注意事项 + +- 返回的数组直接包含文件的原始字节数据 +- 当前实现仅支持从文件系统读取，档案读取待实现 +- 读取失败时返回空数组，可通过 `Empty()` 方法检查 diff --git a/docs/api/resources/resource-file-system/remove-archive.md b/docs/api/resources/resource-file-system/remove-archive.md new file mode 100644 index 00000000..13df0c16 --- /dev/null +++ b/docs/api/resources/resource-file-system/remove-archive.md @@ -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 资源无法访问 +``` + +## 注意事项 + +- 如果档案不存在，则此方法不做任何操作 +- 当前实现从目录列表中移除匹配路径（档案与目录共用存储） diff --git a/docs/api/resources/resource-file-system/resource-info.md b/docs/api/resources/resource-file-system/resource-info.md new file mode 100644 index 00000000..f68c4c14 --- /dev/null +++ b/docs/api/resources/resource-file-system/resource-info.md @@ -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()); + } +} +``` diff --git a/docs/api/resources/resource-file-system/shutdown.md b/docs/api/resources/resource-file-system/shutdown.md new file mode 100644 index 00000000..217c91a8 --- /dev/null +++ b/docs/api/resources/resource-file-system/shutdown.md @@ -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()` 才能使用 +- 已打开的档案会被自动关闭 diff --git a/docs/api/resources/resource-loader/canload.md b/docs/api/resources/resource-loader/canload.md new file mode 100644 index 00000000..47036920 --- /dev/null +++ b/docs/api/resources/resource-loader/canload.md @@ -0,0 +1,31 @@ +# IResourceLoader::CanLoad + +```cpp +virtual bool CanLoad(const Containers::String& path) const = 0 +``` + +纯虚方法，检查此加载器是否能加载指定路径的资源。通过比对路径扩展名与支持列表判断。 + +**参数：** +- `path` - 资源路径 + +**返回：** 如果扩展名在支持列表中则返回 true + +**复杂度：** O(k)，k 为扩展名数量 + +**示例：** + +```cpp +bool TextureLoader::CanLoad(const Containers::String& path) const { + Containers::String ext = GetExtension(path); + auto supported = GetSupportedExtensions(); + for (const auto& s : supported) { + if (ext == s) return true; + } + return false; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/getdefaultsettings.md b/docs/api/resources/resource-loader/getdefaultsettings.md new file mode 100644 index 00000000..ae7e9456 --- /dev/null +++ b/docs/api/resources/resource-loader/getdefaultsettings.md @@ -0,0 +1,25 @@ +# IResourceLoader::GetDefaultSettings + +```cpp +virtual ImportSettings* GetDefaultSettings() const = 0 +``` + +纯虚方法，返回此加载器使用的默认导入设置。每个加载器可提供针对其资源类型的默认导入参数。 + +**返回：** `ImportSettings*` 默认导入设置指针 + +**实现注意：** 当前各加载器实现返回 `nullptr`，未返回实际的默认设置对象。 + +**线程安全：** ✅ + +**示例：** + +```cpp +ImportSettings* TextureLoader::GetDefaultSettings() const { + return new TextureImportSettings(); +} +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/getresourcetype.md b/docs/api/resources/resource-loader/getresourcetype.md new file mode 100644 index 00000000..3b1a6ec3 --- /dev/null +++ b/docs/api/resources/resource-loader/getresourcetype.md @@ -0,0 +1,27 @@ +# IResourceLoader::GetResourceType + +```cpp +virtual ResourceType GetResourceType() const = 0 +``` + +纯虚方法，返回此加载器所处理的资源类型。每个加载器必须声明自己处理的资源类型（如 Texture、Mesh、Audio 等）。 + +**返回：** `ResourceType` 枚举值，表示支持的资源类型 + +**线程安全：** ✅ + +**示例：** + +```cpp +class TextureLoader : public IResourceLoader { +public: + ResourceType GetResourceType() const override { + return ResourceType::Texture; + } + // ... +}; +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/getsupportedextensions.md b/docs/api/resources/resource-loader/getsupportedextensions.md new file mode 100644 index 00000000..aa46d152 --- /dev/null +++ b/docs/api/resources/resource-loader/getsupportedextensions.md @@ -0,0 +1,23 @@ +# IResourceLoader::GetSupportedExtensions + +```cpp +virtual Containers::Array GetSupportedExtensions() const = 0 +``` + +纯虚方法，返回此加载器支持的文件扩展名列表。例如纹理加载器可能返回 `{".png", ".jpg", ".jpeg", ".bmp", ".tga"}`。 + +**返回：** `Containers::Array` 支持的扩展名列表（包含点号） + +**线程安全：** ✅ + +**示例：** + +```cpp +Containers::Array TextureLoader::GetSupportedExtensions() const { + return {".png", ".jpg", ".jpeg", ".bmp", ".tga"}; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/load.md b/docs/api/resources/resource-loader/load.md new file mode 100644 index 00000000..8fac4561 --- /dev/null +++ b/docs/api/resources/resource-loader/load.md @@ -0,0 +1,42 @@ +# IResourceLoader::Load + +```cpp +virtual LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) = 0 +``` + +同步加载资源。纯虚方法，由具体加载器实现。从指定路径读取文件数据，解析为对应类型的资源对象。 + +**参数：** +- `path` - 资源文件路径 +- `settings` - 可选的导入设置，用于自定义加载行为 + +**返回：** `LoadResult`，包含加载结果（资源指针、是否成功、错误信息等） + +**复杂度：** O(n)，取决于文件大小 + +**示例：** + +```cpp +LoadResult TextureLoader::Load(const Containers::String& path, + const ImportSettings* settings) { + LoadResult result; + auto data = ReadFileData(path); + if (data.Empty()) { + result.errorMessage = "Failed to read file: " + path; + return result; + } + Texture* tex = new Texture(); + if (!tex->LoadFromData(data.Data(), data.Size(), settings)) { + delete tex; + result.errorMessage = "Failed to parse texture data"; + return result; + } + result.resource = tex; + result.success = true; + return result; +} +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/loadasync.md b/docs/api/resources/resource-loader/loadasync.md new file mode 100644 index 00000000..b77fedc7 --- /dev/null +++ b/docs/api/resources/resource-loader/loadasync.md @@ -0,0 +1,45 @@ +# IResourceLoader::LoadAsync + +```cpp +virtual void LoadAsync(const Containers::String& path, + const ImportSettings* settings, + std::function callback) +``` + +异步加载资源。虚方法，提供默认实现（直接在调用线程执行 Load 然后调用回调）。子类可重写以提供真正的异步实现。 + +**参数：** +- `path` - 资源文件路径 +- `settings` - 导入设置 +- `callback` - 加载完成后的回调函数，接收 `LoadResult` 参数 + +**线程安全：** ❌（默认实现同步执行，子类重写时需确保线程安全） + +**示例：** + +```cpp +// 使用默认实现的异步加载 +ResourceManager::Get().LoadAsync("textures/player.png", + nullptr, [](LoadResult result) { + if (result.success) { + Texture* tex = static_cast(result.resource); + // 使用纹理 + } + }); + +// 子类重写提供真正的异步实现 +class AsyncTextureLoader : public IResourceLoader { + void LoadAsync(const Containers::String& path, + const ImportSettings* settings, + std::function callback) override { + std::thread([this, path, settings, callback]() { + LoadResult result = Load(path, settings); + callback(result); + }).detach(); + } +}; +``` + +## 相关文档 + +- [IResourceLoader 总览](resource-loader.md) - 返回类总览 diff --git a/docs/api/resources/resource-loader/resource-loader.md b/docs/api/resources/resource-loader/resource-loader.md new file mode 100644 index 00000000..c6f15bfe --- /dev/null +++ b/docs/api/resources/resource-loader/resource-loader.md @@ -0,0 +1,119 @@ +# IResourceLoader + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` (抽象基类) + +**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。 + +## 概述 + +`IResourceLoader` 是资源加载系统的核心抽象接口。它定义了同步和异步加载资源的方法，以及资源类型的查询。`ResourceManager` 通过注册加载器来支持不同类型资源的加载。 + +## LoadResult 结构体 + +加载操作的返回值结构体。 + +```cpp +struct LoadResult { + IResource* resource = nullptr; + bool success = false; + Containers::String errorMessage; + LoadResult() = default; + explicit LoadResult(IResource* res) : resource(res), success(res != nullptr) {} + explicit LoadResult(const Containers::String& error) : success(false), errorMessage(error) {} + explicit LoadResult(bool inSuccess, const Containers::String& error = "") + : success(inSuccess), errorMessage(error) {} + operator bool() const { return success && resource != nullptr; } +}; +``` + +## 公共方法 + +### 资源信息 + +| 方法 | 描述 | +|------|------| +| [`GetResourceType`](getresourcetype.md) | 获取此加载器支持的资源类型 | +| [`GetSupportedExtensions`](getsupportedextensions.md) | 获取支持的文件扩展名列表 | +| [`CanLoad`](canload.md) | 检查此加载器是否能加载指定路径 | +| [`GetDefaultSettings`](getdefaultsettings.md) | 获取默认导入设置 | + +### 同步加载 + +| 方法 | 描述 | +|------|------| +| [`Load`](load.md) | 同步加载资源 | + +### 异步加载 + +| 方法 | 描述 | +|------|------| +| [`LoadAsync`](loadasync.md) | 异步加载资源（带默认实现，子类可重写） | + +### 辅助方法（受保护） + +| 方法 | 描述 | +|------|------| +| `static Containers::Array ReadFileData(const Containers::String& path)` | 读取文件数据 | +| `static Containers::String GetExtension(const Containers::String& path)` | 获取文件扩展名 | + +## 实现说明 + +**注意**: 各资源加载器的 `GetDefaultSettings()` 当前返回 `nullptr`，未返回实际的默认设置对象。 + +## 宏 + +### REGISTER_RESOURCE_LOADER + +自动注册加载器到 ResourceManager 的宏。 + +```cpp +REGISTER_RESOURCE_LOADER(TextureLoader) +``` + +## 使用示例 + +```cpp +class TextureLoader : public IResourceLoader { +public: + ResourceType GetResourceType() const override { + return ResourceType::Texture; + } + + Containers::Array GetSupportedExtensions() const override { + return {".png", ".jpg", ".jpeg", ".bmp", ".tga"}; + } + + bool CanLoad(const Containers::String& path) const override { + Containers::String ext = GetExtension(path); + return ext == ".png" || ext == ".jpg" || ext == ".bmp"; + } + + ImportSettings* GetDefaultSettings() const override { + return new TextureImportSettings(); + } + + LoadResult Load(const Containers::String& path, + const ImportSettings* settings = nullptr) override { + LoadResult result; + auto data = ReadFileData(path); + if (data.Empty()) { + return LoadResult("Failed to read file: " + path); + } + result.resource = new Texture(); + result.success = true; + return result; + } +}; + +// 注册加载器 +ResourceManager::Get().RegisterLoader(new TextureLoader()); +``` + +## 相关文档 + +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器 +- [ImportSettings](../importsettings/importsettings.md) - 导入设置 +- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resource-package/close.md b/docs/api/resources/resource-package/close.md new file mode 100644 index 00000000..b75ef344 --- /dev/null +++ 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) - 检查包有效性 diff --git a/docs/api/resources/resource-package/enumerate.md b/docs/api/resources/resource-package/enumerate.md new file mode 100644 index 00000000..53ca5488 --- /dev/null +++ b/docs/api/resources/resource-package/enumerate.md @@ -0,0 +1,56 @@ +# Enumerate + +枚举资源包中匹配指定模式的文件。 + +## 方法签名 + +```cpp +void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const; +``` + +## 详细描述 + +枚举包内所有与给定模式匹配的文件路径，并将结果输出到 `outFiles` 数组中。当前实现会将 `outFiles` 清空后填入所有文件路径。 + +**注意**：当前实现不支持真正的通配符匹配，会返回包内所有文件的完整路径列表。 + +## 参数 + +| 参数名 | 类型 | 描述 | +|--------|------|------| +| `pattern` | `const Containers::String&` | 文件匹配模式（当前实现中未使用） | +| `outFiles` | `Containers::Array&` | 输出参数，用于存放匹配的文件路径列表 | + +## 返回值 + +无 + +## 示例 + +```cpp +ResourcePackage package; +package.Open("assets/resources.xcp"); + +Array 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) - 读取文件内容 diff --git a/docs/api/resources/resource-package/exists.md b/docs/api/resources/resource-package/exists.md new file mode 100644 index 00000000..0b38020b --- /dev/null +++ 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) - 枚举文件 diff --git a/docs/api/resources/resource-package/getinfo.md b/docs/api/resources/resource-package/getinfo.md new file mode 100644 index 00000000..89d8fd32 --- /dev/null +++ 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) - 检查包有效性 diff --git a/docs/api/resources/resource-package/getsize.md b/docs/api/resources/resource-package/getsize.md new file mode 100644 index 00000000..478e7347 --- /dev/null +++ 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 buffer(size); +} +``` + +## 相关方法 + +- [Read](read.md) - 读取文件内容 +- [Exists](exists.md) - 检查文件存在 diff --git a/docs/api/resources/resource-package/index.md b/docs/api/resources/resource-package/index.md new file mode 100644 index 00000000..a8887e60 --- /dev/null +++ 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 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& 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 data = package.Read("textures/player.png"); + // 处理数据... +} + +// 获取文件大小 +size_t size = package.GetSize("textures/player.png"); + +// 枚举所有文件 +Array 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) - 资源类型定义 diff --git a/docs/api/resources/resource-package/isvalid.md b/docs/api/resources/resource-package/isvalid.md new file mode 100644 index 00000000..d12065c3 --- /dev/null +++ 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) - 关闭资源包 diff --git a/docs/api/resources/resource-package/open.md b/docs/api/resources/resource-package/open.md new file mode 100644 index 00000000..f2cccbd1 --- /dev/null +++ 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) - 检查包有效性 diff --git a/docs/api/resources/resource-package/read.md b/docs/api/resources/resource-package/read.md new file mode 100644 index 00000000..124d2364 --- /dev/null +++ b/docs/api/resources/resource-package/read.md @@ -0,0 +1,55 @@ +# Read + +读取资源包中指定文件的内容。 + +## 方法签名 + +```cpp +Containers::Array Read(const Containers::String& relativePath) const; +``` + +## 详细描述 + +从资源包中读取指定文件的完整内容并返回。如果文件不存在或读取失败，返回空的数组。 + +文件内容以字节数组形式返回，适用于读取二进制资源如图像、音频、着色器等。 + +## 参数 + +| 参数名 | 类型 | 描述 | +|--------|------|------| +| `relativePath` | `const Containers::String&` | 文件的相对路径 | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `Containers::Array` | 文件内容的字节数组，失败时返回空数组 | + +## 示例 + +```cpp +ResourcePackage package; +package.Open("assets/resources.xcp"); + +// 读取图像文件 +Array imageData = package.Read("textures/player.png"); +if (!imageData.Empty()) { + printf("Loaded image: %zu bytes\n", imageData.Size()); +} + +// 读取文本文件（需要额外处理 UTF-8 编码） +Array textData = package.Read("config/settings.txt"); +if (!textData.Empty()) { + // 转换为字符串 + String text(reinterpret_cast(textData.Data()), textData.Size()); +} + +// 读取着色器 +Array shaderData = package.Read("shaders/pbr.glsl"); +``` + +## 相关方法 + +- [Exists](exists.md) - 检查文件存在 +- [GetSize](getsize.md) - 获取文件大小 diff --git a/docs/api/resources/resourcecache/add.md b/docs/api/resources/resourcecache/add.md deleted file mode 100644 index 2d7ee72e..00000000 --- a/docs/api/resources/resourcecache/add.md +++ /dev/null @@ -1,25 +0,0 @@ -# ResourceCache::Add - -```cpp -void Add(ResourceGUID guid, IResource* resource) -``` - -添加资源到缓存。将资源和 GUID 关联并记录内存大小、访问时间。线程安全。 - -**参数：** -- `guid` - 资源全局唯一标识符 -- `resource` - 资源指针 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -cache.Add(guid, resource); -``` - -## 相关文档 - -- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/flush.md b/docs/api/resources/resourcecache/flush.md deleted file mode 100644 index 5b83ee7f..00000000 --- a/docs/api/resources/resourcecache/flush.md +++ /dev/null @@ -1,23 +0,0 @@ -# ResourceCache::Flush - -```cpp -void Flush() -``` - -清空缓存，释放所有资源。将所有缓存条目标记为待释放状态，调用每个资源的 `Release()` 方法。 - -**参数：** 无 - -**返回：** 无 - -**复杂度：** O(n) - -**示例：** - -```cpp -cache.Flush(); -``` - -## 相关文档 - -- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/getlrulist.md b/docs/api/resources/resourcecache/getlrulist.md deleted file mode 100644 index 6e850f9d..00000000 --- a/docs/api/resources/resourcecache/getlrulist.md +++ /dev/null @@ -1,27 +0,0 @@ -# ResourceCache::GetLRUList - -```cpp -Containers::Array GetLRUList(size_t count) const -``` - -获取最近最少使用的 GUID 列表。按 LRU 顺序返回前 `count` 个资源 GUID。 - -**参数：** -- `count` - 要获取的 GUID 数量 - -**返回：** 最近最少使用的 GUID 数组 - -**复杂度：** O(n) - -**示例：** - -```cpp -auto lruList = cache.GetLRUList(10); -for (const auto& guid : lruList) { - // 标记或处理这些资源... -} -``` - -## 相关文档 - -- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/onmemorypressure.md b/docs/api/resources/resourcecache/onmemorypressure.md deleted file mode 100644 index 5b6efa22..00000000 --- a/docs/api/resources/resourcecache/onmemorypressure.md +++ /dev/null @@ -1,25 +0,0 @@ -# ResourceCache::OnMemoryPressure - -```cpp -void OnMemoryPressure(size_t requiredBytes) -``` - -内存压力回调。当系统内存紧张时调用此方法，从 LRU 列表头部开始驱逐资源，直到释放足够空间。 - -**参数：** -- `requiredBytes` - 需要释放的字节数 - -**返回：** 无 - -**复杂度：** O(n) - -**示例：** - -```cpp -// 需要 100MB 空间 -cache.OnMemoryPressure(100 * 1024 * 1024); -``` - -## 相关文档 - -- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcecache/resourcecache.md b/docs/api/resources/resourcecache/resourcecache.md deleted file mode 100644 index aea2d6e5..00000000 --- a/docs/api/resources/resourcecache/resourcecache.md +++ /dev/null @@ -1,79 +0,0 @@ -# ResourceCache - -**命名空间**: `XCEngine::Resources` - -**类型**: `class` - -**描述**: 资源缓存管理类，使用 LRU（最近最少使用）策略管理内存压力下的资源驱逐。 - -## 概述 - -`ResourceCache` 实现了资源的内存缓存管理。它跟踪每个资源的访问时间和访问次数，在内存压力下自动驱逐最近最少使用的资源，确保内存使用不超过预算。 - -## CacheEntry 结构体 - -缓存条目结构体。 - -| 成员 | 类型 | 描述 | -|------|------|------| -| `resource` | `IResource*` | 资源指针 | -| `guid` | `ResourceGUID` | 全局唯一标识符 | -| `memorySize` | `size_t` | 内存大小 | -| `lastAccessTime` | `Core::uint64` | 上次访问时间戳 | -| `accessCount` | `Core::uint32` | 访问次数 | - -### 构造与静态方法 - -| 方法 | 描述 | -|------|------| -| `CacheEntry()` | 默认构造 | -| `CacheEntry(IResource* res, size_t size)` | 从资源和大小构造 | -| `static Core::uint64 GetCurrentTick()` | 获取当前时间戳 | - -## 公共方法 - -| 方法 | 描述 | -|------|------| -| `ResourceCache()` | 默认构造函数 | -| `~ResourceCache()` | 析构函数 | -| `void Add(ResourceGUID guid, IResource* resource)` | 添加资源到缓存 | -| `void Remove(ResourceGUID guid)` | 从缓存中移除资源 | -| `IResource* Find(ResourceGUID guid) const` | 查找资源 | -| `void Touch(ResourceGUID guid)` | 更新资源的访问时间（LRU） | -| `size_t GetSize() const` | 获取缓存中资源数量 | -| `size_t GetMemoryUsage() const` | 获取缓存内存使用量（字节） | -| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 | -| `size_t GetMemoryBudget() const` | 获取内存预算 | -| `void OnMemoryPressure(size_t requiredBytes)` | 内存压力回调，驱逐资源以释放空间 | -| `void OnZeroRefCount(ResourceGUID guid)` | 当引用计数为零时的回调（当前为空实现） | -| `void Flush()` | 清空缓存，释放所有资源（当前为部分实现） | -| `void Clear()` | 清空缓存但不释放资源 | -| `Containers::Array GetLRUList(size_t count) const` | 获取最近最少使用的 GUID 列表 | - -## 使用示例 - -```cpp -ResourceCache cache; -cache.SetMemoryBudget(512 * 1024 * 1024); // 512MB 预算 - -// 添加资源 -cache.Add(guid, resource); - -// 访问资源（更新 LRU） -cache.Touch(guid); - -// 查找资源 -IResource* res = cache.Find(guid); - -// 内存压力时自动驱逐 -cache.OnMemoryPressure(100 * 1024 * 1024); // 需要 100MB - -// 获取最少使用的资源 -auto lruList = cache.GetLRUList(10); -``` - -## 相关文档 - -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 -- [IResource](../iresource/iresource.md) - 资源基类 -- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcecache/touch.md b/docs/api/resources/resourcecache/touch.md deleted file mode 100644 index 138d7b7a..00000000 --- a/docs/api/resources/resourcecache/touch.md +++ /dev/null @@ -1,27 +0,0 @@ -# ResourceCache::Touch - -```cpp -void Touch(ResourceGUID guid) -``` - -更新资源的最近访问时间。当缓存条目被命中时调用，用于 LRU 驱逐算法判断资源的访问热度。 - -**参数：** -- `guid` - 资源全局唯一标识符 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -IResource* res = cache.Find(guid); -if (res) { - cache.Touch(guid); // 更新 LRU -} -``` - -## 相关文档 - -- [ResourceCache 总览](resourcecache.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/get.md b/docs/api/resources/resourcehandle/get.md deleted file mode 100644 index bf010d3c..00000000 --- a/docs/api/resources/resourcehandle/get.md +++ /dev/null @@ -1,27 +0,0 @@ -# ResourceHandle::Get - -```cpp -T* Get() const -``` - -获取资源裸指针。返回句柄内部持有的资源指针，不进行任何引用计数操作。 - -**参数：** 无 - -**返回：** 资源裸指针，可能为 `nullptr`（当句柄为空时） - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle tex = ResourceManager::Get().Load("tex.png"); -Texture* raw = tex.Get(); -if (raw != nullptr) { - uint32_t w = raw->GetWidth(); -} -``` - -## 相关文档 - -- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/getguid.md b/docs/api/resources/resourcehandle/getguid.md deleted file mode 100644 index 8dd379b6..00000000 --- a/docs/api/resources/resourcehandle/getguid.md +++ /dev/null @@ -1,27 +0,0 @@ -# ResourceHandle::GetGUID - -```cpp -ResourceGUID GetGUID() const -``` - -获取资源的全局唯一标识符。如果内部指针为空，则返回一个值为 0 的空 GUID。 - -**参数：** 无 - -**返回：** 资源的 `ResourceGUID`，如果句柄为空则返回 `ResourceGUID(0)` - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle tex = ResourceManager::Get().Load("tex.png"); -ResourceGUID guid = tex.GetGUID(); -if (guid.IsValid()) { - printf("GUID: %s\n", guid.ToString().CStr()); -} -``` - -## 相关文档 - -- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/isvalid.md b/docs/api/resources/resourcehandle/isvalid.md deleted file mode 100644 index 0b2c1d29..00000000 --- a/docs/api/resources/resourcehandle/isvalid.md +++ /dev/null @@ -1,29 +0,0 @@ -# ResourceHandle::IsValid - -```cpp -bool IsValid() const -``` - -检查句柄是否持有有效资源。判断条件为：内部指针非空且资源的 `IsValid()` 返回 true。 - -**参数：** 无 - -**返回：** 如果持有有效资源则返回 true，否则返回 false - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle tex = ResourceManager::Get().Load("tex.png"); -if (tex.IsValid()) { - // 安全访问资源 - tex->GenerateMipmaps(); -} else { - printf("Texture load failed!\n"); -} -``` - -## 相关文档 - -- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/reset.md b/docs/api/resources/resourcehandle/reset.md deleted file mode 100644 index 74f4484a..00000000 --- a/docs/api/resources/resourcehandle/reset.md +++ /dev/null @@ -1,31 +0,0 @@ -# ResourceHandle::Reset - -```cpp -void Reset() -``` - -释放当前持有的资源引用。如果内部持有的资源指针非空，则调用 `ResourceManager::Release()` 减少引用计数，并将内部指针置为 `nullptr`。析构函数会自动调用此方法。 - -**参数：** 无 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle tex = ResourceManager::Get().Load("tex.png"); -// 使用纹理... -tex.Reset(); // 释放引用，引用计数 -1 - -// 或者让句柄离开作用域自动释放 -{ - ResourceHandle mesh = ResourceManager::Get().Load("model.fbx"); - // 使用网格... -} // mesh 自动 Reset() -``` - -## 相关文档 - -- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcehandle/resourcehandle.md b/docs/api/resources/resourcehandle/resourcehandle.md deleted file mode 100644 index 7a59b2cb..00000000 --- a/docs/api/resources/resourcehandle/resourcehandle.md +++ /dev/null @@ -1,74 +0,0 @@ -# ResourceHandle - -**命名空间**: `XCEngine::Resources` - -**类型**: `class` (template) - -**描述**: 模板资源句柄类，提供资源的引用计数式安全访问，自动管理资源的加载和释放。 - -## 概述 - -`ResourceHandle` 是一个模板句柄类，用于安全地持有对资源的引用。它通过 `ResourceManager` 自动管理引用计数：当句柄被创建时引用计数增加，当句柄被销毁或调用 `Reset()` 时引用计数减少。这确保了资源在其仍被使用时不会被卸载。 - -## 模板参数 - -| 参数 | 约束 | 描述 | -|------|------|------| -| `T` | 必须派生自 `IResource` | 资源类型 | - -## 公共方法 - -| 方法 | 描述 | -|------|------| -| `ResourceHandle() = default` | 默认构造空句柄 | -| `explicit ResourceHandle(T* resource)` | 从裸指针构造（自动增加引用） | -| `ResourceHandle(const ResourceHandle& other)` | 拷贝构造（自动增加引用） | -| `ResourceHandle(ResourceHandle&& other) noexcept` | 移动构造 | -| `~ResourceHandle()` | 析构函数（自动调用 Reset） | -| `ResourceHandle& operator=(const ResourceHandle& other)` | 拷贝赋值（自动管理引用） | -| `ResourceHandle& operator=(ResourceHandle&& other) noexcept` | 移动赋值 | -| `T* Get() const` | 获取裸指针 | -| `T* operator->() const` | 通过指针访问资源成员 | -| `T& operator*() const` | 解引用获取资源引用 | -| `bool IsValid() const` | 检查句柄是否持有有效资源 | -| `explicit operator bool() const` | 隐式布尔转换 | -| `ResourceGUID GetGUID() const` | 获取资源的全局唯一标识符 | -| `ResourceType GetResourceType() const` | 获取资源类型 | -| `void Reset()` | 释放当前资源引用 | -| `void Swap(ResourceHandle& other)` | 交换两个句柄的内容 | - -## 比较运算 - -| 运算符 | 描述 | -|------|------| -| `operator==(ResourceHandle, ResourceHandle)` | 比较 GUID 是否相等 | -| `operator!=(ResourceHandle, ResourceHandle)` | 比较 GUID 是否不等 | - -## 使用示例 - -```cpp -// 加载资源（引用计数 +1） -ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); - -// 检查有效性 -if (tex.IsValid()) { - // 安全访问资源 - uint32_t width = tex->GetWidth(); -} - -// 拷贝句柄（引用计数 +1） -ResourceHandle tex2 = tex; - -// 移动句柄 -ResourceHandle tex3 = std::move(tex2); - -// 句柄离开作用域时自动释放（引用计数 -1） -tex.Reset(); // 手动释放 -``` - -## 相关文档 - -- [IResource](../iresource/iresource.md) - 资源基类 -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 -- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存 -- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcehandle/swap.md b/docs/api/resources/resourcehandle/swap.md deleted file mode 100644 index f41d7725..00000000 --- a/docs/api/resources/resourcehandle/swap.md +++ /dev/null @@ -1,30 +0,0 @@ -# ResourceHandle::Swap - -```cpp -void Swap(ResourceHandle& other) -``` - -交换两个句柄持有的资源指针。使用 `std::swap` 交换内部指针，不会改变任何引用计数。此操作常用于在不影响引用计数的情况下安全地交换两个句柄的内容。 - -**参数：** -- `other` - 要交换的另一个 ResourceHandle 引用 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceHandle tex1 = ResourceManager::Get().Load("a.png"); -ResourceHandle tex2 = ResourceManager::Get().Load("b.png"); - -// 交换后 tex1 持有 b.png，tex2 持有 a.png -tex1.Swap(tex2); - -// 引用计数不变 -``` - -## 相关文档 - -- [ResourceHandle 总览](resourcehandle.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/exists.md b/docs/api/resources/resourcemanager/exists.md deleted file mode 100644 index 13e00903..00000000 --- a/docs/api/resources/resourcemanager/exists.md +++ /dev/null @@ -1,28 +0,0 @@ -# ResourceManager::Exists - -```cpp -bool Exists(const Containers::String& path) const -bool Exists(ResourceGUID guid) const -``` - -检查资源是否已加载。 - -**参数：** -- `path` - 资源路径 -- `guid` - 资源全局唯一标识符 - -**返回：** 如果资源在缓存中则返回 true - -**复杂度：** O(1) - -**示例：** - -```cpp -if (ResourceManager::Get().Exists("textures/player.png")) { - auto tex = ResourceManager::Get().Load("textures/player.png"); -} -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/find.md b/docs/api/resources/resourcemanager/find.md deleted file mode 100644 index 469f994b..00000000 --- a/docs/api/resources/resourcemanager/find.md +++ /dev/null @@ -1,29 +0,0 @@ -# ResourceManager::Find - -```cpp -IResource* Find(const Containers::String& path) -IResource* Find(ResourceGUID guid) -``` - -在资源缓存中查找资源。返回裸指针，不增加引用计数。 - -**参数：** -- `path` - 资源路径 -- `guid` - 资源全局唯一标识符 - -**返回：** 找到则返回资源指针，否则返回 `nullptr` - -**复杂度：** O(1) - -**示例：** - -```cpp -IResource* res = ResourceManager::Get().Find("textures/player.png"); -if (res && res->IsValid()) { - Texture* tex = static_cast(res); -} -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/getloader.md b/docs/api/resources/resourcemanager/getloader.md deleted file mode 100644 index 255e6f49..00000000 --- a/docs/api/resources/resourcemanager/getloader.md +++ /dev/null @@ -1,27 +0,0 @@ -# ResourceManager::GetLoader - -```cpp -IResourceLoader* GetLoader(ResourceType type) const -``` - -获取指定类型的资源加载器。 - -**参数：** -- `type` - 资源类型 - -**返回：** 对应的加载器指针，未找到则返回 `nullptr` - -**复杂度：** O(1) - -**示例：** - -```cpp -IResourceLoader* texLoader = ResourceManager::Get().GetLoader(ResourceType::Texture); -if (texLoader) { - auto extensions = texLoader->GetSupportedExtensions(); -} -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/load.md b/docs/api/resources/resourcemanager/load.md deleted file mode 100644 index 83b65aab..00000000 --- a/docs/api/resources/resourcemanager/load.md +++ /dev/null @@ -1,32 +0,0 @@ -# ResourceManager::Load - -```cpp -template -ResourceHandle Load(const Containers::String& path, ImportSettings* settings = nullptr) -``` - -同步加载资源。模板方法，根据路径生成 GUID，先在缓存中查找是否已加载；若未加载则查找对应类型的加载器并同步加载，然后将结果加入缓存。 - -**参数：** -- `path` - 资源路径 -- `settings` - 导入设置（可选） - -**返回：** `ResourceHandle`，持有加载的资源 - -**复杂度：** O(n)，取决于加载器实现 - -**示例：** - -```cpp -ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); -ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); -ResourceHandle mat = ResourceManager::Get().Load("materials/player.mat"); - -if (tex.IsValid()) { - // 使用纹理... -} -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/loadasync.md b/docs/api/resources/resourcemanager/loadasync.md deleted file mode 100644 index 7c470813..00000000 --- a/docs/api/resources/resourcemanager/loadasync.md +++ /dev/null @@ -1,44 +0,0 @@ -# ResourceManager::LoadAsync - -```cpp -void LoadAsync(const Containers::String& path, ResourceType type, - std::function callback) -void LoadAsync(const Containers::String& path, ResourceType type, - ImportSettings* settings, std::function callback) -``` - -异步加载资源。将加载请求提交到 `AsyncLoader`，在后台工作线程执行加载，完成后在主线程通过回调通知。 - -**参数：** -- `path` - 资源路径 -- `type` - 资源类型 -- `settings` - 导入设置（可为 nullptr） -- `callback` - 加载完成回调 - -**返回：** 无 - -**复杂度：** 提交 O(1)，实际加载 O(n) - -**示例：** - -```cpp -ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture, - [](LoadResult result) { - if (result.success) { - ResourceHandle tex(result.resource); - printf("Loaded: %s\n", tex->GetPath().CStr()); - } - }); - -ResourceManager::Get().LoadAsync("models/player.fbx", ResourceType::Mesh, - nullptr, - [](LoadResult result) { - if (result.success) { - ResourceHandle mesh(result.resource); - } - }); -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/loadgroup.md b/docs/api/resources/resourcemanager/loadgroup.md deleted file mode 100644 index 23193e57..00000000 --- a/docs/api/resources/resourcemanager/loadgroup.md +++ /dev/null @@ -1,35 +0,0 @@ -# ResourceManager::LoadGroup - -```cpp -template -void LoadGroup(const Containers::Array& paths, - std::function)> callback) -``` - -批量异步加载同类资源。为路径数组中的每个路径提交一个异步加载请求，所有加载完成时通过回调通知。 - -**参数：** -- `paths` - 资源路径数组 -- `callback` - 每个资源加载完成时的回调 - -**返回：** 无 - -**复杂度：** O(k)，k 为路径数量（每个加载为 O(n)） - -**示例：** - -```cpp -Containers::Array texPaths = { - "textures/a.png", "textures/b.png", "textures/c.png" -}; -ResourceManager::Get().LoadGroup(texPaths, - [](ResourceHandle tex) { - if (tex.IsValid()) { - printf("Loaded: %s\n", tex->GetPath().CStr()); - } - }); -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/registerloader.md b/docs/api/resources/resourcemanager/registerloader.md deleted file mode 100644 index 62c01cc8..00000000 --- a/docs/api/resources/resourcemanager/registerloader.md +++ /dev/null @@ -1,26 +0,0 @@ -# ResourceManager::RegisterLoader - -```cpp -void RegisterLoader(IResourceLoader* loader) -``` - -注册资源加载器。管理器持有加载器指针所有权。 - -**参数：** -- `loader` - 加载器实例指针 - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceManager::Get().RegisterLoader(new TextureLoader()); -ResourceManager::Get().RegisterLoader(new MeshLoader()); -ResourceManager::Get().RegisterLoader(new MaterialLoader()); -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/resourcemanager.md b/docs/api/resources/resourcemanager/resourcemanager.md deleted file mode 100644 index 97921f4f..00000000 --- a/docs/api/resources/resourcemanager/resourcemanager.md +++ /dev/null @@ -1,101 +0,0 @@ -# ResourceManager - -**命名空间**: `XCEngine::Resources` - -**类型**: `class` (singleton) - -**描述**: 资源管理器单例，负责资源的加载、缓存、引用计数管理和异步加载调度。 - -## 概述 - -`ResourceManager` 是 XCEngine 资源管理系统的核心单例类。它提供统一的资源加载接口、自动缓存管理、引用计数跟踪和异步加载支持。所有资源访问都应通过 `ResourceManager` 进行。 - -## 单例访问 - -| 方法 | 描述 | -|------|------| -| `static ResourceManager& Get()` | 获取单例实例 | - -## 公共方法 - -| 方法 | 描述 | -|------|------| -| `void Initialize()` | 初始化资源管理器 | -| `void Shutdown()` | 关闭资源管理器，卸载所有资源 | -| `void SetResourceRoot(const Containers::String& rootPath)` | 设置资源根目录 | -| `const Containers::String& GetResourceRoot() const` | 获取资源根目录 | -| `ResourceHandle Load(const Containers::String& path, ImportSettings* settings = nullptr)` | 同步加载资源（模板方法） | -| `void LoadAsync(const Containers::String& path, ResourceType type, std::function callback)` | 异步加载资源 | -| `void LoadAsync(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function callback)` | 带设置的异步加载 | -| `void LoadGroup(const Containers::Array& paths, std::function)> callback)` | 批量异步加载同类资源 | -| `void Unload(const Containers::String& path)` | 按路径卸载资源 | -| `void Unload(ResourceGUID guid)` | 按 GUID 卸载资源 | -| `void UnloadUnused()` | 卸载所有无引用的资源 | -| `void UnloadAll()` | 卸载所有资源 | -| `void AddRef(ResourceGUID guid)` | 增加引用计数（内部使用） | -| `void Release(ResourceGUID guid)` | 减少引用计数（内部使用） | -| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 | -| `IResource* Find(const Containers::String& path)` | 按路径查找资源 | -| `IResource* Find(ResourceGUID guid)` | 按 GUID 查找资源 | -| `bool Exists(const Containers::String& path) const` | 检查资源是否存在 | -| `bool Exists(ResourceGUID guid) const` | 检查 GUID 对应资源是否存在 | -| `void RegisterLoader(IResourceLoader* loader)` | 注册资源加载器 | -| `void UnregisterLoader(ResourceType type)` | 注销加载器 | -| `IResourceLoader* GetLoader(ResourceType type) const` | 获取指定类型的加载器 | -| `void SetMemoryBudget(size_t bytes)` | 设置内存预算 | -| `size_t GetMemoryUsage() const` | 获取当前内存使用量 | -| `size_t GetMemoryBudget() const` | 获取内存预算 | -| `void FlushCache()` | 清空缓存 | -| `Containers::String ResolvePath(const Containers::String& relativePath) const` | 将相对路径解析为绝对路径 | -| `Containers::Array GetResourcePaths() const` | 获取所有已加载资源的路径列表 | -| `void UnloadGroup(const Containers::Array& guids)` | 按 GUID 批量卸载 | - -## 实现说明 - -```cpp -// 初始化 -ResourceManager::Get().Initialize(); -ResourceManager::Get().SetResourceRoot("resources/"); - -// 注册加载器 -ResourceManager::Get().RegisterLoader(new TextureLoader()); -ResourceManager::Get().RegisterLoader(new MeshLoader()); -ResourceManager::Get().RegisterLoader(new MaterialLoader()); - -// 同步加载 -ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); -ResourceHandle mesh = ResourceManager::Get().Load("models/player.fbx"); - -// 异步加载 -ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture, - [](LoadResult result) { - if (result.success) { - ResourceHandle tex(result.resource); - // 使用纹理... - } - }); - -// 批量加载 -Containers::Array paths = {"a.png", "b.png", "c.png"}; -ResourceManager::Get().LoadGroup(paths, - [](ResourceHandle tex) { - if (tex.IsValid()) { - // 处理加载完成的纹理... - } - }); - -// 设置内存预算 -ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024); // 1GB - -// 卸载 -ResourceManager::Get().UnloadUnused(); -ResourceManager::Get().Shutdown(); -``` - -## 相关文档 - -- [IResource](../iresource/iresource.md) - 资源基类 -- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄 -- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存 -- [AsyncLoader](../asyncloader/asyncloader.md) - 异步加载器 -- [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/resourcemanager/setmemorybudget.md b/docs/api/resources/resourcemanager/setmemorybudget.md deleted file mode 100644 index 6d790ba9..00000000 --- a/docs/api/resources/resourcemanager/setmemorybudget.md +++ /dev/null @@ -1,24 +0,0 @@ -# ResourceManager::SetMemoryBudget - -```cpp -void SetMemoryBudget(size_t bytes) -``` - -设置资源管理的内存预算上限。当缓存中资源的总内存占用超过预算时，会触发 LRU 驱逐策略释放内存。 - -**参数：** -- `bytes` - 内存预算大小（字节） - -**返回：** 无 - -**复杂度：** O(1) - -**示例：** - -```cpp -ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024); // 1GB 预算 -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/unload.md b/docs/api/resources/resourcemanager/unload.md deleted file mode 100644 index 8eea6d9a..00000000 --- a/docs/api/resources/resourcemanager/unload.md +++ /dev/null @@ -1,31 +0,0 @@ -# ResourceManager::Unload - -```cpp -void Unload(const Containers::String& path) -void Unload(ResourceGUID guid) -``` - -卸载指定资源。按路径或 GUID 查找资源，如果引用计数降至零则释放资源内存。 - -**参数：** -- `path` - 资源路径 -- `guid` - 资源全局唯一标识符 - -**返回：** 无 - -**复杂度：** O(1) 查找 - -**示例：** - -```cpp -// 按路径卸载 -ResourceManager::Get().Unload("textures/player.png"); - -// 按 GUID 卸载 -ResourceGUID guid = tex.GetGUID(); -ResourceManager::Get().Unload(guid); -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcemanager/unloadunused.md b/docs/api/resources/resourcemanager/unloadunused.md deleted file mode 100644 index 27bcb763..00000000 --- a/docs/api/resources/resourcemanager/unloadunused.md +++ /dev/null @@ -1,26 +0,0 @@ -# ResourceManager::UnloadUnused - -```cpp -void UnloadUnused() -``` - -卸载所有无引用的资源。遍历资源缓存，将引用计数为零的资源全部释放。常在场景切换或内存紧张时调用。 - -**参数：** 无 - -**返回：** 无 - -**复杂度：** O(n) - -**示例：** - -```cpp -// 切换场景时清理无用资源 -void OnSceneUnload() { - ResourceManager::Get().UnloadUnused(); -} -``` - -## 相关文档 - -- [ResourceManager 总览](resourcemanager.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getdirectory.md b/docs/api/resources/resourcepath/getdirectory.md new file mode 100644 index 00000000..4b30d40c --- /dev/null +++ b/docs/api/resources/resourcepath/getdirectory.md @@ -0,0 +1,32 @@ +# ResourcePath::GetDirectory + +```cpp +Containers::String GetDirectory() const +``` + +获取目录部分。 + +**详细描述：** + +返回路径中最后一个路径分隔符之前的所有内容，即目录路径。兼容 Windows (`\`) 和 Unix (`/`) 路径分隔符。 + +**返回：** `Containers::String`，目录路径 + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String dir = path.GetDirectory(); // "textures" + +ResourcePath path2("textures/subfolder/player.png"); +Containers::String dir2 = path2.GetDirectory(); // "textures/subfolder" + +ResourcePath path3("player.png"); +Containers::String dir3 = path3.GetDirectory(); // "" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getextension.md b/docs/api/resources/resourcepath/getextension.md new file mode 100644 index 00000000..4a6c0d0d --- /dev/null +++ b/docs/api/resources/resourcepath/getextension.md @@ -0,0 +1,32 @@ +# ResourcePath::GetExtension + +```cpp +Containers::String GetExtension() const +``` + +获取文件扩展名。 + +**详细描述：** + +返回路径字符串的文件扩展名部分，包括前缀点（`.`）。如果路径为空或不包含扩展名，返回空字符串。 + +**返回：** `Containers::String`，包含扩展名（如 `".png"`），如果无扩展名则返回空字符串 + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String ext = path.GetExtension(); // ".png" + +ResourcePath path2("textures/player"); +Containers::String ext2 = path2.GetExtension(); // "" + +ResourcePath path3(""); +Containers::String ext3 = path3.GetExtension(); // "" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getfilename.md b/docs/api/resources/resourcepath/getfilename.md new file mode 100644 index 00000000..b156f245 --- /dev/null +++ b/docs/api/resources/resourcepath/getfilename.md @@ -0,0 +1,32 @@ +# ResourcePath::GetFileName + +```cpp +Containers::String GetFileName() const +``` + +获取文件名（含扩展名）。 + +**详细描述：** + +返回路径中最后一个路径分隔符后的部分，包括文件名和扩展名。兼容 Windows (`\`) 和 Unix (`/`) 路径分隔符。 + +**返回：** `Containers::String`，文件名（含扩展名） + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String name = path.GetFileName(); // "player.png" + +ResourcePath path2("player.png"); +Containers::String name2 = path2.GetFileName(); // "player.png" + +ResourcePath path3("textures\\windows\\file.txt"); +Containers::String name3 = path3.GetFileName(); // "file.txt" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getfullpath.md b/docs/api/resources/resourcepath/getfullpath.md new file mode 100644 index 00000000..70cb94f5 --- /dev/null +++ b/docs/api/resources/resourcepath/getfullpath.md @@ -0,0 +1,26 @@ +# ResourcePath::GetFullPath + +```cpp +Containers::String GetFullPath() const +``` + +获取完整路径。 + +**详细描述：** + +返回存储的完整路径字符串。 + +**返回：** `Containers::String`，完整路径 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String fullPath = path.GetFullPath(); // "textures/player.png" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getpath.md b/docs/api/resources/resourcepath/getpath.md new file mode 100644 index 00000000..1b03ec54 --- /dev/null +++ b/docs/api/resources/resourcepath/getpath.md @@ -0,0 +1,27 @@ +# ResourcePath::GetPath + +```cpp +const Containers::String& GetPath() const +``` + +获取原始路径字符串。 + +**详细描述：** + +返回内部存储的路径字符串的常量引用。 + +**返回：** `const Containers::String&`，路径字符串的常量引用 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +const Containers::String& rawPath = path.GetPath(); // "textures/player.png" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 +- [SetPath](setpath.md) - 设置路径 diff --git a/docs/api/resources/resourcepath/getrelativepath.md b/docs/api/resources/resourcepath/getrelativepath.md new file mode 100644 index 00000000..e73d5aa7 --- /dev/null +++ b/docs/api/resources/resourcepath/getrelativepath.md @@ -0,0 +1,26 @@ +# ResourcePath::GetRelativePath + +```cpp +Containers::String GetRelativePath() const +``` + +获取相对路径。 + +**详细描述：** + +返回存储的相对路径字符串。当前实现直接返回完整路径。 + +**返回：** `Containers::String`，相对路径 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String relPath = path.GetRelativePath(); // "textures/player.png" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/getstem.md b/docs/api/resources/resourcepath/getstem.md new file mode 100644 index 00000000..bd79004e --- /dev/null +++ b/docs/api/resources/resourcepath/getstem.md @@ -0,0 +1,32 @@ +# ResourcePath::GetStem + +```cpp +Containers::String GetStem() const +``` + +获取文件名（不含扩展名）。 + +**详细描述：** + +返回路径中文件名部分，不包含扩展名。兼容 Windows (`\`) 和 Unix (`/`) 路径分隔符。 + +**返回：** `Containers::String`，文件名（不含扩展名） + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +Containers::String stem = path.GetStem(); // "player" + +ResourcePath path2("textures/player.backup.png"); +Containers::String stem2 = path2.GetStem(); // "player.backup" + +ResourcePath path3("textures"); +Containers::String stem3 = path3.GetStem(); // "textures" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/hasanyextension.md b/docs/api/resources/resourcepath/hasanyextension.md new file mode 100644 index 00000000..77917a09 --- /dev/null +++ b/docs/api/resources/resourcepath/hasanyextension.md @@ -0,0 +1,36 @@ +# ResourcePath::HasAnyExtension + +```cpp +bool HasAnyExtension(const char* const* extensions, Core::uint32 count) const +``` + +检查是否具有任意指定扩展名。 + +**详细描述：** + +遍历扩展名数组，检查路径是否匹配其中任意一个扩展名。扩展名应包含前缀点（`.`）。 + +**参数：** +- `extensions` - 扩展名数组指针 +- `count` - 扩展名数组长度 + +**返回：** `bool`，匹配任意扩展名返回 `true`，否则返回 `false` + +**复杂度：** O(n * m)，n 为路径长度，m 为扩展名数量 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); + +const char* imageExts[] = {".png", ".jpg", ".jpeg", ".bmp", ".tga"}; +bool isImage = path.HasAnyExtension(imageExts, 5); // true + +const char* videoExts[] = {".mp4", ".avi", ".mkv"}; +bool isVideo = path.HasAnyExtension(videoExts, 3); // false +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 +- [HasExtension](hasextension.md) - 检查单个扩展名 diff --git a/docs/api/resources/resourcepath/hasextension.md b/docs/api/resources/resourcepath/hasextension.md new file mode 100644 index 00000000..df694ef7 --- /dev/null +++ b/docs/api/resources/resourcepath/hasextension.md @@ -0,0 +1,33 @@ +# ResourcePath::HasExtension + +```cpp +bool HasExtension(const char* ext) const +``` + +检查是否具有指定扩展名。 + +**详细描述：** + +比较路径的扩展名与指定的扩展名。扩展名应包含前缀点（`.`）。 + +**参数：** +- `ext` - 要检查的扩展名（应包含 `.`，如 `".png"`） + +**返回：** `bool`，扩展名匹配返回 `true`，否则返回 `false` + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); + +bool isPng = path.HasExtension(".png"); // true +bool isJpg = path.HasExtension(".jpg"); // false +bool isInvalid = path.HasExtension("png"); // false (缺少前缀点) +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 +- [HasAnyExtension](hasanyextension.md) - 检查多个扩展名 diff --git a/docs/api/resources/resourcepath/isvalid.md b/docs/api/resources/resourcepath/isvalid.md new file mode 100644 index 00000000..5830fa9f --- /dev/null +++ b/docs/api/resources/resourcepath/isvalid.md @@ -0,0 +1,33 @@ +# ResourcePath::IsValid + +```cpp +bool IsValid() const +``` + +检查路径是否有效（非空）。 + +**详细描述：** + +判断路径是否有效，即路径字符串是否非空。 + +**返回：** `bool`，路径非空返回 `true`，否则返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourcePath validPath("textures/player.png"); +if (validPath.IsValid()) { + // 处理有效路径 +} + +ResourcePath emptyPath(""); +if (!emptyPath.IsValid()) { + // 处理空路径 +} +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 diff --git a/docs/api/resources/resourcepath/resourcepath.md b/docs/api/resources/resourcepath/resourcepath.md index daf71b09..d0aa0d6c 100644 --- a/docs/api/resources/resourcepath/resourcepath.md +++ b/docs/api/resources/resourcepath/resourcepath.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/ResourcePath.h` + **描述**: 资源路径封装类，提供路径解析、转换和 GUID 生成功能。 ## 概述 diff --git a/docs/api/resources/resourcepath/setpath.md b/docs/api/resources/resourcepath/setpath.md new file mode 100644 index 00000000..1a037660 --- /dev/null +++ b/docs/api/resources/resourcepath/setpath.md @@ -0,0 +1,29 @@ +# ResourcePath::SetPath + +```cpp +void SetPath(const Containers::String& path) +``` + +设置路径字符串。 + +**详细描述：** + +更新内部存储的路径字符串。 + +**参数：** +- `path` - 新的路径字符串 + +**复杂度：** O(n)，n 为路径长度 + +**示例：** + +```cpp +ResourcePath path; +path.SetPath("textures/player.png"); +Containers::String name = path.GetFileName(); // "player.png" +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 +- [GetPath](getpath.md) - 获取路径 diff --git a/docs/api/resources/resourcepath/toguid.md b/docs/api/resources/resourcepath/toguid.md new file mode 100644 index 00000000..f0864085 --- /dev/null +++ b/docs/api/resources/resourcepath/toguid.md @@ -0,0 +1,30 @@ +# ResourcePath::ToGUID + +```cpp +ResourceGUID ToGUID() const +``` + +将路径转换为 GUID。 + +**详细描述：** + +通过 `ResourceGUID::Generate` 方法根据路径字符串生成唯一的资源标识符。 + +**返回：** `ResourceGUID`，基于路径生成的全局唯一标识符 + +**复杂度：** O(n)，取决于 `ResourceGUID::Generate` 实现 + +**示例：** + +```cpp +ResourcePath path("textures/player.png"); +ResourceGUID guid = path.ToGUID(); + +// GUID 可用于资源查找、缓存键等 +ResourceHandle tex = ResourceManager::Get().Find(guid); +``` + +## 相关文档 + +- [ResourcePath 总览](resourcepath.md) - 返回类总览 +- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义 diff --git a/docs/api/resources/resources.md b/docs/api/resources/resources.md index fc28c9c0..e87bdb84 100644 --- a/docs/api/resources/resources.md +++ b/docs/api/resources/resources.md @@ -4,6 +4,8 @@ **类型**: `module` +**头文件**: `XCEngine/Resources/Resources.h` + **描述**: XCEngine 的资源管理系统，提供资源的异步加载、缓存和依赖管理。 ## 概述 @@ -19,6 +21,7 @@ Resources 模块提供了一套完整的资源管理解决方案，支持同步 | [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 | | [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 | | [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 | +| [ShaderLoader](shaderloader/index.md) | `ShaderLoader.h` | 着色器加载器 | | [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 | | [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 | | [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 | diff --git a/docs/api/resources/resourcetypes/generate.md b/docs/api/resources/resourcetypes/generate.md index e41bc239..23bfc1ad 100644 --- a/docs/api/resources/resourcetypes/generate.md +++ b/docs/api/resources/resourcetypes/generate.md @@ -5,20 +5,29 @@ static ResourceGUID Generate(const char* path) static ResourceGUID Generate(const Containers::String& path) ``` -从资源路径生成唯一的全局标识符。通过哈希算法将路径字符串转换为唯一的 64 位整数。 +从资源路径生成唯一的全局标识符。内部使用 FNV-1a 哈希算法将路径字符串转换为唯一的 64 位整数。 **参数：** -- `path` - 资源路径 +- `path` - 资源路径（相对路径或绝对路径） -**返回：** 生成的 `ResourceGUID` +**返回：** 生成的 `ResourceGUID`，其 `value` 为哈希结果 -**复杂度：** O(n) +**算法细节：** +- 采用 FNV-1a 哈希算法 +- 初始哈希值：14695981039346656037 (64位 FNV_offset_basis) +- 乘数：1099511628211 (64位 FNV_prime) +- 时间复杂度：O(n)，n 为路径字符串长度 **示例：** ```cpp ResourceGUID guid = ResourceGUID::Generate("textures/player.png"); ResourceGUID guid2 = ResourceGUID::Generate("models/player.fbx"); + +// 不同路径产生不同 GUID +if (guid != guid2) { + // 路径不同，GUID 必然不同 +} ``` ## 相关文档 diff --git a/docs/api/resources/resourcetypes/getresourcetypename.md b/docs/api/resources/resourcetypes/getresourcetypename.md index 7a57e27c..08db87ec 100644 --- a/docs/api/resources/resourcetypes/getresourcetypename.md +++ b/docs/api/resources/resourcetypes/getresourcetypename.md @@ -4,12 +4,12 @@ constexpr const char* GetResourceTypeName(ResourceType type) ``` -获取资源类型的字符串名称。通过 switch 语句返回对应的类型名字符串。 +获取资源类型的字符串名称。该函数是 `constexpr`，在编译时即可确定返回值。通过 switch 语句返回对应类型名的常量字符串指针。 **参数：** -- `type` - 资源类型枚举值 +- `type` - `ResourceType` 枚举值 -**返回：** 类型名字符串（如 `"Texture"`、`"Mesh"` 等） +**返回：** 类型名字符串常量指针（如 `"Texture"`、`"Mesh"` 等），未识别的类型返回 `"Unknown"` **复杂度：** O(1) @@ -17,7 +17,8 @@ constexpr const char* GetResourceTypeName(ResourceType type) ```cpp const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture" -const char* name2 = GetResourceTypeName(ResourceType::Shader); // "Shader" +const char* name2 = GetResourceTypeName(ResourceType::Shader); // "Shader" +const char* name3 = GetResourceTypeName(ResourceType::Unknown); // "Unknown" ``` ## 相关文档 diff --git a/docs/api/resources/resourcetypes/resourcetypes.md b/docs/api/resources/resourcetypes/resourcetypes.md index 5cf14a02..ae941036 100644 --- a/docs/api/resources/resourcetypes/resourcetypes.md +++ b/docs/api/resources/resourcetypes/resourcetypes.md @@ -2,23 +2,29 @@ **命名空间**: `XCEngine::Resources` -**类型**: `enums` / `structs` +**类型**: 类/结构体/枚举定义 -**描述**: 资源模块中使用的所有类型定义，包括资源类型枚举、GUID 结构体等。 +**描述**: 资源模块的基础类型定义，提供资源类型枚举、全局唯一标识符(GUID)以及模板类型查询功能。 ## 概述 -本文档汇总了 Resources 模块中的所有类型定义，包括资源类型枚举、GUID 结构体等基础类型。 +`ResourceTypes` 模块定义了资源系统中使用的基础类型，包括： +- `ResourceType` 枚举：标识资源的具体类型 +- `ResourceGUID` 结构体：用于唯一标识每个资源的 64 位全局唯一标识符 +- `GetResourceType()` 模板特化：在编译时获取类型对应的资源类型 +- `GetResourceTypeName()` 函数：获取资源类型的字符串表示 --- -## ResourceType +## 公共类型 + +### ResourceType 资源类型枚举。 | 值 | 描述 | |----|------| -| `Unknown` | 未知类型 | +| `Unknown` | 未知类型，默认值 | | `Texture` | 纹理资源 | | `Mesh` | 网格/模型资源 | | `Material` | 材质资源 | @@ -34,20 +40,20 @@ --- -## ResourceGUID +### ResourceGUID -全局唯一标识符结构体，用于唯一标识每个资源。 +全局唯一标识符结构体，用于唯一标识每个资源。采用 64 位无符号整数存储，内部通过 FNV-1a 哈希算法从资源路径生成。 ```cpp struct ResourceGUID { Core::uint64 value; - ResourceGUID() : value(0) {} - explicit ResourceGUID(Core::uint64 v) : value(v) {} + ResourceGUID(); + explicit ResourceGUID(Core::uint64 v); - bool IsValid() const { return value != 0; } - bool operator==(const ResourceGUID& other) const { return value == other.value; } - bool operator!=(const ResourceGUID& other) const { return value != other.value; } + bool IsValid() const; + bool operator==(const ResourceGUID& other) const; + bool operator!=(const ResourceGUID& other) const; static ResourceGUID Generate(const char* path); static ResourceGUID Generate(const Containers::String& path); @@ -56,35 +62,56 @@ struct ResourceGUID { }; ``` -### 比较运算 - -| 运算符 | 描述 | -|------|------| -| `operator==(ResourceGUID, ResourceGUID)` | 判断相等 | -| `operator!=(ResourceGUID, ResourceGUID)` | 判断不等 | - -### 哈希支持 - -`ResourceGUID` 可作为 HashMap 的键使用（特化了 `std::hash`）。 - -### 静态方法 +#### 构造方法 | 方法 | 描述 | |------|------| -| `static ResourceGUID Generate(const char* path)` | 从资源路径生成唯一 GUID | -| `static ResourceGUID Generate(const Containers::String& path)` | 从资源路径生成唯一 GUID | -| `Containers::String ToString() const` | 转换为字符串 | +| `ResourceGUID()` | 默认构造，value 初始化为 0 | +| `explicit ResourceGUID(Core::uint64 v)` | 从 64 位整数构造 | -### 辅助函数 +#### 公共方法 -| 函数 | 描述 | +| 方法 | 描述 | |------|------| -| `constexpr const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 | -| `ResourceGUID MakeResourceGUID(const char* path)` | 从路径生成 GUID 的辅助函数 | +| `bool IsValid() const` | 检查 GUID 是否有效（value != 0） | +| `Containers::String ToString() const` | 转换为十六进制字符串表示 | +| `bool operator==(const ResourceGUID& other) const` | 判断相等 | +| `bool operator!=(const ResourceGUID& other) const` | 判断不等 | -### 模板特化 +#### 静态方法 + +| 方法 | 描述 | +|------|------| +| `static ResourceGUID Generate(const char* path)` | 从 C 字符串路径生成唯一 GUID（使用 FNV-1a 哈希算法） | +| `static ResourceGUID Generate(const Containers::String& path)` | 从 String 路径生成唯一 GUID | + +#### 哈希支持 + +`ResourceGUID` 特化了 `std::hash`，可作为 `HashMap`、`HashSet` 的键使用： ```cpp +namespace std { +template<> +struct hash { + size_t operator()(const XCEngine::Resources::ResourceGUID& guid) const noexcept { + return static_cast(guid.value); + } +}; +} +``` + +--- + +## 模板特化 + +### GetResourceType + +模板特化函数，用于在编译时获取类型对应的 `ResourceType`。 + +```cpp +template +ResourceType GetResourceType(); + template<> inline ResourceType GetResourceType() { return ResourceType::Texture; } template<> inline ResourceType GetResourceType() { return ResourceType::Mesh; } template<> inline ResourceType GetResourceType() { return ResourceType::Material; } @@ -93,12 +120,34 @@ template<> inline ResourceType GetResourceType() { return Resou template<> inline ResourceType GetResourceType() { return ResourceType::Binary; } ``` -**注意**: `GetResourceType()` 是模板特化函数，用于在编译时获取资源类型。 +| 类型 T | 返回值 | +|--------|--------| +| `Texture` | `ResourceType::Texture` | +| `Mesh` | `ResourceType::Mesh` | +| `Material` | `ResourceType::Material` | +| `Shader` | `ResourceType::Shader` | +| `AudioClip` | `ResourceType::AudioClip` | +| `BinaryResource` | `ResourceType::Binary` | + +--- + +## 辅助函数 + +| 函数 | 描述 | +|------|------| +| `constexpr const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 | +| `ResourceGUID MakeResourceGUID(const char* path)` | 从路径生成 GUID 的简写函数 | + +--- ## 使用示例 ```cpp -// 使用 ResourceGUID +#include "XCEngine/Resources/ResourceTypes.h" + +using namespace XCEngine::Resources; + +// 创建 ResourceGUID ResourceGUID texGuid = ResourceGUID::Generate("textures/player.png"); ResourceGUID meshGuid = ResourceGUID::Generate("models/player.fbx"); @@ -109,22 +158,26 @@ if (texGuid == meshGuid) { // 有效性检查 if (texGuid.IsValid()) { - // GUID 有效 + // GUID 有效（value != 0） } -// 在 HashMap 中使用 +// 转换为字符串 +Containers::String guidStr = texGuid.ToString(); // "0000163a5b4c8d9f" + +// 在 HashMap 中作为键使用 Containers::HashMap cache; cache[texGuid] = texture; // 获取类型名称 const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture" -// 使用模板获取类型 +// 使用模板获取类型（编译时） ResourceType type = GetResourceType(); // ResourceType::Texture ``` +--- + ## 相关文档 - [IResource](../iresource/iresource.md) - 资源基类 -- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 - [Resources 总览](../resources.md) - 返回模块总览 diff --git a/docs/api/resources/shader-loader/index.md b/docs/api/resources/shader-loader/index.md new file mode 100644 index 00000000..f3e8381e --- /dev/null +++ b/docs/api/resources/shader-loader/index.md @@ -0,0 +1,59 @@ +# ShaderLoader + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (Class) + +## 描述 + +着色器资源加载器，负责从磁盘加载 `.vert`、`.frag`、`.geom`、`.comp`、`.glsl`、`.hlsl` 和 `.shader` 格式的着色器资源文件。 + +## 概述 + +`ShaderLoader` 继承自 `IResourceLoader`，实现了着色器资源的加载功能。它支持多种图形 API 的着色器格式，包括 GLSL（OpenGL/Vulkan）和 HLSL（DirectX）。加载过程中会根据文件扩展名自动检测着色器类型和语言，创建 `Shader` 对象并设置相应的元数据。当前实现专注于文件读取和基础资源创建，着色器编译和实际绑定由渲染层完成。 + +## 公共方法 + +| 方法 | 签名 | 描述 | +|------|------|------| +| [ShaderLoader](methods/constructor.md) | `ShaderLoader()` | 默认构造函数 | +| [~ShaderLoader](methods/destructor.md) | `virtual ~ShaderLoader()` | 析构函数 | +| [GetResourceType](methods/get-resource-type.md) | `ResourceType GetResourceType() const` | 返回资源类型为 Shader | +| [GetSupportedExtensions](methods/get-supported-extensions.md) | `Array GetSupportedExtensions() const` | 返回支持的扩展名列表 | +| [CanLoad](methods/can-load.md) | `bool CanLoad(const String& path) const` | 检查给定路径是否可被加载 | +| [Load](methods/load.md) | `LoadResult Load(const String& path, const ImportSettings* settings = nullptr)` | 加载指定路径的着色器资源 | +| [GetDefaultSettings](methods/get-default-settings.md) | `ImportSettings* GetDefaultSettings() const` | 返回默认导入设置 | + +## 使用示例 + +```cpp +#include "Resources/ShaderLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载着色器 +auto shaderHandle = ResourceManager::Get().Load("assets/shaders/pbr.vert"); +if (shaderHandle.IsValid()) { + Shader* shader = shaderHandle.Get(); + // 使用着色器... +} + +// 直接使用 ShaderLoader +ShaderLoader loader; +LoadResult result = loader.Load("assets/shaders/pbr.frag"); +if (result.IsSuccess()) { + Shader* shader = static_cast(result.GetResource()); + // 使用着色器... +} +``` + +## 相关文档 + +- [Shader](../shader/shader.md) +- [IResourceLoader](../iloader/iloader.md) +- [ResourceManager](../resource-manager/resource-manager.md) diff --git a/docs/api/resources/shader-loader/methods/can-load.md b/docs/api/resources/shader-loader/methods/can-load.md new file mode 100644 index 00000000..713b3139 --- /dev/null +++ b/docs/api/resources/shader-loader/methods/can-load.md @@ -0,0 +1,36 @@ +# ShaderLoader::CanLoad + +## 方法签名 + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +## 详细描述 + +检查此加载器是否能加载指定路径的着色器文件。该方法通过获取文件扩展名并与支持列表进行匹配来判断。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| path | `const Containers::String&` | 文件路径 | + +## 返回值 + +`bool` - 如果扩展名在支持列表中则返回 `true`，否则返回 `false` + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; + +bool canLoad1 = loader.CanLoad("shaders/pbr.vert"); // true +bool canLoad2 = loader.CanLoad("shaders/pbr.frag"); // true +bool canLoad3 = loader.CanLoad("shaders/pbr.hlsl"); // true +bool canLoad4 = loader.CanLoad("textures/wood.png"); // false +``` diff --git a/docs/api/resources/shader-loader/methods/constructor.md b/docs/api/resources/shader-loader/methods/constructor.md new file mode 100644 index 00000000..a4d2f314 --- /dev/null +++ b/docs/api/resources/shader-loader/methods/constructor.md @@ -0,0 +1,29 @@ +# ShaderLoader::ShaderLoader + +## 方法签名 + +```cpp +ShaderLoader(); +``` + +## 详细描述 + +默认构造函数，使用默认行为构造 `ShaderLoader` 对象。该构造函数不执行任何特殊初始化操作。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +``` diff --git a/docs/api/resources/shader-loader/methods/destructor.md b/docs/api/resources/shader-loader/methods/destructor.md new file mode 100644 index 00000000..0985500b --- /dev/null +++ b/docs/api/resources/shader-loader/methods/destructor.md @@ -0,0 +1,33 @@ +# ShaderLoader::~ShaderLoader + +## 方法签名 + +```cpp +virtual ~ShaderLoader() override; +``` + +## 详细描述 + +析构函数，用于销毁 `ShaderLoader` 对象。该析构函数不执行任何特殊清理操作。 + +## 参数 + +无 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +{ + ShaderLoader loader; + // 使用 loader... +} +// loader 在此自动销毁 +``` + +## 相关文档 + +- [ShaderLoader 总览](../../../rhi/d3d12/fence/index.md) - 返回类总览 diff --git a/docs/api/resources/shader-loader/methods/get-default-settings.md b/docs/api/resources/shader-loader/methods/get-default-settings.md new file mode 100644 index 00000000..bd096f71 --- /dev/null +++ b/docs/api/resources/shader-loader/methods/get-default-settings.md @@ -0,0 +1,31 @@ +# ShaderLoader::GetDefaultSettings + +## 方法签名 + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +## 详细描述 + +返回默认的导入设置。当前实现返回 `nullptr`，表示没有特定的默认设置。 + +## 参数 + +无 + +## 返回值 + +`ImportSettings*` - 始终返回 `nullptr` + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +ImportSettings* settings = loader.GetDefaultSettings(); +// settings == nullptr +``` diff --git a/docs/api/resources/shader-loader/methods/get-resource-type.md b/docs/api/resources/shader-loader/methods/get-resource-type.md new file mode 100644 index 00000000..f6c16124 --- /dev/null +++ b/docs/api/resources/shader-loader/methods/get-resource-type.md @@ -0,0 +1,31 @@ +# ShaderLoader::GetResourceType + +## 方法签名 + +```cpp +ResourceType GetResourceType() const override; +``` + +## 详细描述 + +返回此加载器支持的资源类型。该方法继承自 `IResourceLoader` 接口，返回值为 `ResourceType::Shader`。 + +## 参数 + +无 + +## 返回值 + +`ResourceType` - 资源类型枚举值，当前返回 `ResourceType::Shader` + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +ResourceType type = loader.GetResourceType(); +// type == ResourceType::Shader +``` diff --git a/docs/api/resources/shader-loader/methods/get-supported-extensions.md b/docs/api/resources/shader-loader/methods/get-supported-extensions.md new file mode 100644 index 00000000..f86d1b01 --- /dev/null +++ b/docs/api/resources/shader-loader/methods/get-supported-extensions.md @@ -0,0 +1,44 @@ +# ShaderLoader::GetSupportedExtensions + +## 方法签名 + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +## 详细描述 + +返回此加载器支持的文件扩展名列表。支持以下格式： + +| 扩展名 | 描述 | +|--------|------| +| `.vert` | 顶点着色器 (Vertex Shader) | +| `.frag` | 片段着色器 (Fragment/Pixel Shader) | +| `.geom` | 几何着色器 (Geometry Shader) | +| `.comp` | 计算着色器 (Compute Shader) | +| `.glsl` | 通用 GLSL 着色器 | +| `.hlsl` | HLSL 着色器 | +| `.shader` | 通用着色器文件 | + +## 参数 + +无 + +## 返回值 + +`Containers::Array` - 支持的文件扩展名数组 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +auto extensions = loader.GetSupportedExtensions(); + +for (const auto& ext : extensions) { + printf("Supported extension: %s\n", ext.CStr()); +} +``` diff --git a/docs/api/resources/shader-loader/methods/load.md b/docs/api/resources/shader-loader/methods/load.md new file mode 100644 index 00000000..b54b86ef --- /dev/null +++ b/docs/api/resources/shader-loader/methods/load.md @@ -0,0 +1,74 @@ +# ShaderLoader::Load + +## 方法签名 + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +## 详细描述 + +加载指定路径的着色器资源文件。加载过程包括： + +1. 读取文件数据 +2. 将二进制数据转换为字符串形式的着色器源代码 +3. 创建 `Shader` 对象并设置基本信息（路径、名称、GUID） +4. 根据文件扩展名检测着色器语言（HLSL 或 GLSL） +5. 根据文件扩展名检测着色器类型（顶点、片段、几何、计算） +6. 设置着色器源代码和有效性标志 +7. 计算并设置资源的内存占用 + +**语言检测规则：** +- `.hlsl` 扩展名 → `ShaderLanguage::HLSL` +- 其他扩展名 → `ShaderLanguage::GLSL` + +**类型检测规则：** +- `.vert` → `ShaderType::Vertex` +- `.frag` → `ShaderType::Fragment` +- `.geom` → `ShaderType::Geometry` +- `.comp` → `ShaderType::Compute` +- 其他扩展名 → `ShaderType::Fragment`（默认） + +## 参数 + +| 参数 | 类型 | 默认值 | 描述 | +|------|------|--------|------| +| path | `const Containers::String&` | - | 着色器文件路径 | +| settings | `const ImportSettings*` | `nullptr` | 导入设置（当前未使用） | + +## 返回值 + +`LoadResult` - 加载结果对象，包含成功加载的 `Shader` 指针或错误信息 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; + +// 加载顶点着色器 +LoadResult vertResult = loader.Load("assets/shaders/pbr.vert"); +if (vertResult.IsSuccess()) { + Shader* vertShader = static_cast(vertResult.GetResource()); + printf("Loaded vertex shader: %s\n", vertShader->m_name.CStr()); +} + +// 加载片段着色器 +LoadResult fragResult = loader.Load("assets/shaders/pbr.frag"); +if (fragResult.IsSuccess()) { + Shader* fragShader = static_cast(fragResult.GetResource()); + printf("Loaded fragment shader: %s\n", fragShader->m_name.CStr()); +} else { + printf("Failed to load fragment shader: %s\n", fragResult.GetError().CStr()); +} + +// 加载 HLSL 着色器 +LoadResult hlslResult = loader.Load("assets/shaders/vertex.hlsl"); +if (hlslResult.IsSuccess()) { + Shader* hlslShader = static_cast(hlslResult.GetResource()); + // HLSL 着色器... +} +``` diff --git a/docs/api/resources/shader/addattribute.md b/docs/api/resources/shader/addattribute.md index b1d2312e..2f2ad378 100644 --- a/docs/api/resources/shader/addattribute.md +++ b/docs/api/resources/shader/addattribute.md @@ -11,7 +11,9 @@ void AddAttribute(const ShaderAttribute& attribute) **返回：** 无 -**复杂度：** O(1) +**线程安全：** ❌ 非线程安全 + +**复杂度：** Amortized O(1) **示例：** diff --git a/docs/api/resources/shader/adduniform.md b/docs/api/resources/shader/adduniform.md index 21d0b5f3..6e4bba8b 100644 --- a/docs/api/resources/shader/adduniform.md +++ b/docs/api/resources/shader/adduniform.md @@ -11,7 +11,9 @@ void AddUniform(const ShaderUniform& uniform) **返回：** 无 -**复杂度：** O(1) +**线程安全：** ❌ 非线程安全 + +**复杂度：** Amortized O(1) **示例：** diff --git a/docs/api/resources/shader/constructor.md b/docs/api/resources/shader/constructor.md new file mode 100644 index 00000000..1fb4ea52 --- /dev/null +++ b/docs/api/resources/shader/constructor.md @@ -0,0 +1,25 @@ +# Shader::Shader + +```cpp +Shader() +``` + +默认构造函数，创建一个无效的 Shader 对象。 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +Shader vs; +vs.SetShaderType(ShaderType::Vertex); +vs.SetShaderLanguage(ShaderLanguage::GLSL); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/destructor.md b/docs/api/resources/shader/destructor.md new file mode 100644 index 00000000..5b5b1efd --- /dev/null +++ b/docs/api/resources/shader/destructor.md @@ -0,0 +1,27 @@ +# Shader::~Shader + +```cpp +virtual ~Shader() +``` + +析构函数，释放 Shader 对象持有的所有资源。 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) - 平凡析构函数 + +**示例：** + +```cpp +{ + Shader vs; + vs.SetShaderType(ShaderType::Vertex); + // ... +} // vs 超出作用域，自动调用析构函数 +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/getattributes.md b/docs/api/resources/shader/getattributes.md new file mode 100644 index 00000000..6056fb06 --- /dev/null +++ b/docs/api/resources/shader/getattributes.md @@ -0,0 +1,27 @@ +# Shader::GetAttributes + +```cpp +const Containers::Array& GetAttributes() const +``` + +获取着色器的顶点属性列表。 + +**返回：** `const Containers::Array&` - 属性列表的引用 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +const Containers::Array& attrs = shader->GetAttributes(); +for (const auto& attr : attrs) { + // 处理每个 attribute +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/getcompiledbinary.md b/docs/api/resources/shader/getcompiledbinary.md new file mode 100644 index 00000000..aa86325e --- /dev/null +++ b/docs/api/resources/shader/getcompiledbinary.md @@ -0,0 +1,24 @@ +# Shader::GetCompiledBinary + +```cpp +const Containers::Array& GetCompiledBinary() const +``` + +获取编译后的着色器二进制数据。 + +**返回：** `const Containers::Array&` - 编译后二进制数据的引用 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +const Containers::Array& binary = shader->GetCompiledBinary(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/getguid.md b/docs/api/resources/shader/getguid.md new file mode 100644 index 00000000..434641ee --- /dev/null +++ b/docs/api/resources/shader/getguid.md @@ -0,0 +1,25 @@ +# Shader::GetGUID + +```cpp +ResourceGUID GetGUID() const override +``` + +获取着色器资源的全局唯一标识符。 + +**返回：** `ResourceGUID` - 全局唯一标识符 + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +ResourceGUID guid = shader->GetGUID(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/getmemorysize.md b/docs/api/resources/shader/getmemorysize.md new file mode 100644 index 00000000..482a3b29 --- /dev/null +++ b/docs/api/resources/shader/getmemorysize.md @@ -0,0 +1,25 @@ +# Shader::GetMemorySize + +```cpp +size_t GetMemorySize() const override +``` + +获取着色器资源的内存大小。 + +**返回：** `size_t` - 内存大小（字节） + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +size_t memSize = shader->GetMemorySize(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/getname.md b/docs/api/resources/shader/getname.md new file mode 100644 index 00000000..961a1836 --- /dev/null +++ b/docs/api/resources/shader/getname.md @@ -0,0 +1,25 @@ +# Shader::GetName + +```cpp +const Containers::String& GetName() const override +``` + +获取着色器资源名称。 + +**返回：** `const Containers::String&` - 着色器名称的引用 + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +Containers::String name = shader->GetName(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/getpath.md b/docs/api/resources/shader/getpath.md new file mode 100644 index 00000000..7268ac18 --- /dev/null +++ b/docs/api/resources/shader/getpath.md @@ -0,0 +1,25 @@ +# Shader::GetPath + +```cpp +const Containers::String& GetPath() const override +``` + +获取着色器资源路径。 + +**返回：** `const Containers::String&` - 着色器路径的引用 + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +Containers::String path = shader->GetPath(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/getrhi.md b/docs/api/resources/shader/getrhi.md new file mode 100644 index 00000000..0b08ba55 --- /dev/null +++ b/docs/api/resources/shader/getrhi.md @@ -0,0 +1,28 @@ +# Shader::GetRHIResource + +```cpp +class IRHIShader* GetRHIResource() const +``` + +获取 RHI 着色器资源指针。 + +**返回：** `class IRHIShader*` - RHI 着色器资源指针，可能为 `nullptr` + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +class IRHIShader* rhiShader = shader->GetRHIResource(); +if (rhiShader != nullptr) { + // RHI 着色器已设置 +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [RHIShader](../../rhi/shader/shader.md) - RHI 着色器接口 diff --git a/docs/api/resources/shader/getshaderlanguage.md b/docs/api/resources/shader/getshaderlanguage.md new file mode 100644 index 00000000..9cac45f0 --- /dev/null +++ b/docs/api/resources/shader/getshaderlanguage.md @@ -0,0 +1,27 @@ +# Shader::GetShaderLanguage + +```cpp +ShaderLanguage GetShaderLanguage() const +``` + +获取着色器语言。 + +**返回：** `ShaderLanguage` - 着色器语言枚举值 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +ShaderLanguage lang = shader->GetShaderLanguage(); +if (lang == ShaderLanguage::GLSL) { + // 这是 GLSL 着色器 +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/getshadertype.md b/docs/api/resources/shader/getshadertype.md new file mode 100644 index 00000000..3e337905 --- /dev/null +++ b/docs/api/resources/shader/getshadertype.md @@ -0,0 +1,27 @@ +# Shader::GetShaderType + +```cpp +ShaderType GetShaderType() const +``` + +获取着色器类型。 + +**返回：** `ShaderType` - 着色器类型枚举值 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +ShaderType type = shader->GetShaderType(); +if (type == ShaderType::Vertex) { + // 这是一个顶点着色器 +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/getsourcecode.md b/docs/api/resources/shader/getsourcecode.md new file mode 100644 index 00000000..0675dd71 --- /dev/null +++ b/docs/api/resources/shader/getsourcecode.md @@ -0,0 +1,24 @@ +# Shader::GetSourceCode + +```cpp +const Containers::String& GetSourceCode() const +``` + +获取着色器源码。 + +**返回：** `const Containers::String&` - 着色器源码的引用 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +const Containers::String& source = shader->GetSourceCode(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/gettype.md b/docs/api/resources/shader/gettype.md new file mode 100644 index 00000000..63b64102 --- /dev/null +++ b/docs/api/resources/shader/gettype.md @@ -0,0 +1,27 @@ +# Shader::GetType + +```cpp +ResourceType GetType() const override +``` + +返回资源类型为 `ResourceType::Shader`。 + +**返回：** `ResourceType` - 资源类型枚举值 `ResourceType::Shader` + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +if (shader->GetType() == ResourceType::Shader) { + // 这是一个着色器资源 +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/getuniforms.md b/docs/api/resources/shader/getuniforms.md new file mode 100644 index 00000000..2339495c --- /dev/null +++ b/docs/api/resources/shader/getuniforms.md @@ -0,0 +1,27 @@ +# Shader::GetUniforms + +```cpp +const Containers::Array& GetUniforms() const +``` + +获取着色器的 Uniform 变量列表。 + +**返回：** `const Containers::Array&` - Uniform 列表的引用 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +const Containers::Array& uniforms = shader->GetUniforms(); +for (const auto& uniform : uniforms) { + // 处理每个 uniform +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/isvalid.md b/docs/api/resources/shader/isvalid.md new file mode 100644 index 00000000..5a197c3e --- /dev/null +++ b/docs/api/resources/shader/isvalid.md @@ -0,0 +1,29 @@ +# Shader::IsValid + +```cpp +bool IsValid() const override +``` + +检查着色器资源是否有效。 + +**返回：** `bool` - 资源有效返回 `true`，否则返回 `false` + +**线程安全：** ✅ 线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +ResourceHandle shader = ResourceManager::Get().Load("shaders/vertex.glsl"); +if (shader->IsValid()) { + // 着色器资源有效 +} else { + // 着色器资源无效 +} +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [IResource](../iresource/iresource.md) - 资源基类 diff --git a/docs/api/resources/shader/release.md b/docs/api/resources/shader/release.md new file mode 100644 index 00000000..fc2266c8 --- /dev/null +++ b/docs/api/resources/shader/release.md @@ -0,0 +1,34 @@ +# Shader::Release + +```cpp +void Release() +``` + +释放着色器持有的所有资源。 + +此方法继承自 `IResource` 接口。调用后： +- 清空源码字符串 (`m_sourceCode`) +- 清空编译后的二进制数据 (`m_compiledBinary`) +- 清空 Uniform 列表 (`m_uniforms`) +- 清空 Attribute 列表 (`m_attributes`) +- 释放 RHI 着色器资源指针 (`m_rhiResource`) +- 将 `m_isValid` 标记为 `false` + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(n) - 取决于列表中元素数量 + +**示例：** + +```cpp +// 使用完 shader 后释放 +ResourceHandle vs = ResourceManager::Get().Load("shaders/vertex.glsl"); +// ... 使用着色器 ... +vs->Release(); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/setbinary.md b/docs/api/resources/shader/setbinary.md new file mode 100644 index 00000000..b1171074 --- /dev/null +++ b/docs/api/resources/shader/setbinary.md @@ -0,0 +1,28 @@ +# Shader::SetCompiledBinary + +```cpp +void SetCompiledBinary(const Containers::Array& binary) +``` + +设置编译后的着色器二进制数据。 + +**参数：** +- `binary` - 编译后的二进制数据数组 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(n) - 复制二进制数据 + +**示例：** + +```cpp +// 假设 compiler 是外部着色器编译器 +Containers::Array compiledSpirv = compiler.Compile(sourceCode); +shader.SetCompiledBinary(compiledSpirv); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/setrhi.md b/docs/api/resources/shader/setrhi.md new file mode 100644 index 00000000..c5eb9c70 --- /dev/null +++ b/docs/api/resources/shader/setrhi.md @@ -0,0 +1,34 @@ +# Shader::SetRHIResource + +```cpp +void SetRHIResource(class IRHIShader* resource) +``` + +设置 RHI 着色器资源指针。 + +**参数：** +- `resource` - RHI 着色器资源指针 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +// 创建 RHI 着色器资源 +RHIShaderDesc desc; +desc.type = RHIShaderType::Vertex; +desc.binary = compiledBinary; +class IRHIShader* rhiShader = RHIDevice::Get().CreateShader(desc); + +// 设置到 Shader 对象 +shader.SetRHIResource(rhiShader); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 +- [RHIShader](../../rhi/shader/shader.md) - RHI 着色器接口 diff --git a/docs/api/resources/shader/setshaderlanguage.md b/docs/api/resources/shader/setshaderlanguage.md new file mode 100644 index 00000000..49e3a7f7 --- /dev/null +++ b/docs/api/resources/shader/setshaderlanguage.md @@ -0,0 +1,28 @@ +# Shader::SetShaderLanguage + +```cpp +void SetShaderLanguage(ShaderLanguage lang) +``` + +设置着色器语言。 + +**参数：** +- `lang` - 着色器语言枚举值 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +Shader vs; +vs.SetShaderLanguage(ShaderLanguage::GLSL); +vs.SetShaderLanguage(ShaderLanguage::HLSL); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/setshadertype.md b/docs/api/resources/shader/setshadertype.md new file mode 100644 index 00000000..ef078a6d --- /dev/null +++ b/docs/api/resources/shader/setshadertype.md @@ -0,0 +1,28 @@ +# Shader::SetShaderType + +```cpp +void SetShaderType(ShaderType type) +``` + +设置着色器类型。 + +**参数：** +- `type` - 着色器类型枚举值 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(1) + +**示例：** + +```cpp +Shader vs; +vs.SetShaderType(ShaderType::Vertex); +vs.SetShaderType(ShaderType::Fragment); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/setsourcecode.md b/docs/api/resources/shader/setsourcecode.md new file mode 100644 index 00000000..dd99ff3a --- /dev/null +++ b/docs/api/resources/shader/setsourcecode.md @@ -0,0 +1,35 @@ +# Shader::SetSourceCode + +```cpp +void SetSourceCode(const Containers::String& source) +``` + +设置着色器源码。 + +**参数：** +- `source` - 着色器源码字符串 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全 + +**复杂度：** O(n) - 复制源码字符串 + +**示例：** + +```cpp +Shader vs; +vs.SetShaderType(ShaderType::Vertex); +vs.SetShaderLanguage(ShaderLanguage::GLSL); +vs.SetSourceCode(R"( +#version 450 +layout(location = 0) in vec3 aPosition; +void main() { + gl_Position = vec4(aPosition, 1.0); +} +)"); +``` + +## 相关文档 + +- [Shader 总览](shader.md) - 返回类总览 diff --git a/docs/api/resources/shader/shader.md b/docs/api/resources/shader/shader.md index 6caf6b55..2edc2648 100644 --- a/docs/api/resources/shader/shader.md +++ b/docs/api/resources/shader/shader.md @@ -4,6 +4,8 @@ **类型**: `class` +**头文件**: `XCEngine/Resources/Shader.h` + **描述**: 着色器资源类，管理着色器源码、编译后的二进制和 uniform/attribute 信息。 ## 概述 @@ -71,17 +73,27 @@ Uniform 变量描述。 | 方法 | 描述 | |------|------| +| `Shader()` | 默认构造函数 | +| `virtual ~Shader()` | 析构函数 | | `ResourceType GetType() const` | 返回 `ResourceType::Shader` | | `const Containers::String& GetName() const` | 获取着色器名称 | | `const Containers::String& GetPath() const` | 获取着色器路径 | | `ResourceGUID GetGUID() const` | 获取全局唯一标识符 | | `bool IsValid() const` | 检查着色器是否有效 | | `size_t GetMemorySize() const` | 获取内存大小 | -| `void Release()` | 释放着色器引用 | +| `void Release()` | 释放着色器资源 | -## 实现说明 +### Release 详细说明 -**注意**: `ShaderLoader::DetectShaderType()` 对于非标准扩展名始终返回 `ShaderType::Fragment`。`ShaderLoader::ParseShaderSource()` 为 stub，始终返回 true。 +`Release()` 方法释放 Shader 实例持有的所有资源，包括： +- 清空源码字符串 (`m_sourceCode`) +- 清空编译后的二进制数据 (`m_compiledBinary`) +- 清空 Uniform 列表 (`m_uniforms`) +- 清空 Attribute 列表 (`m_attributes`) +- 释放 RHI 着色器资源指针 (`m_rhiResource`) +- 将 `m_isValid` 标记为 `false` + +调用此方法后，Shader 对象回到无效状态，可被 ResourceManager 回收。 ### 类型与语言 diff --git a/docs/api/resources/shaderloader/index.md b/docs/api/resources/shaderloader/index.md new file mode 100644 index 00000000..a2d296dd --- /dev/null +++ b/docs/api/resources/shaderloader/index.md @@ -0,0 +1,58 @@ +# ShaderLoader + +## 命名空间 + +`XCEngine::Resources` + +## 类型 + +类 (Class) + +## 描述 + +着色器资源加载器，负责从磁盘加载 `.vert`、`.frag`、`.geom`、`.comp`、`.glsl`、`.hlsl` 和 `.shader` 格式的着色器资源文件。 + +## 概述 + +`ShaderLoader` 继承自 `IResourceLoader`，实现了着色器资源的加载功能。它支持多种着色器语言和类型，能够根据文件扩展名自动识别着色器语言（GLSL/HLSL）和着色器类型（Vertex/Fragment/Geometry/Compute）。加载过程中会读取源文件内容、检测着色器类型并创建 `Shader` 对象。 + +## 公共方法 + +| 方法 | 签名 | 描述 | +|------|------|------| +| [ShaderLoader](methods/constructor.md) | `ShaderLoader()` | 默认构造函数 | +| [GetResourceType](methods/get-resource-type.md) | `ResourceType GetResourceType() const` | 返回资源类型为 Shader | +| [GetSupportedExtensions](methods/get-supported-extensions.md) | `Array GetSupportedExtensions() const` | 返回支持的扩展名列表 | +| [CanLoad](methods/can-load.md) | `bool CanLoad(const String& path) const` | 检查给定路径是否可被加载 | +| [Load](methods/load.md) | `LoadResult Load(const String& path, const ImportSettings* settings = nullptr)` | 加载指定路径的着色器资源 | +| [GetDefaultSettings](methods/get-default-settings.md) | `ImportSettings* GetDefaultSettings() const` | 返回默认导入设置 | + +## 使用示例 + +```cpp +#include "Resources/ShaderLoader.h" +#include "Resources/ResourceManager.h" + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载着色器 +auto shaderHandle = ResourceManager::Get().Load("shaders/forward.vert"); +if (shaderHandle.IsValid()) { + Shader* shader = shaderHandle.Get(); + // 使用着色器... +} + +// 直接使用 ShaderLoader +ShaderLoader loader; +LoadResult result = loader.Load("shaders/pbr.frag"); +if (result.IsSuccess()) { + Shader* shader = static_cast(result.GetResource()); + // 使用着色器... +} +``` + +## 相关文档 + +- [Shader](../shader/shader.md) +- [IResourceLoader](../iloader/iloader.md) +- [ResourceManager](../resourcemanager/resourcemanager.md) diff --git a/docs/api/resources/shaderloader/methods/can-load.md b/docs/api/resources/shaderloader/methods/can-load.md new file mode 100644 index 00000000..83844555 --- /dev/null +++ b/docs/api/resources/shaderloader/methods/can-load.md @@ -0,0 +1,27 @@ +# ShaderLoader::CanLoad + +## 方法签名 + +```cpp +bool CanLoad(const Containers::String& path) const override; +``` + +## 详细描述 + +检查给定路径的文件是否可以被该加载器加载。通过提取文件扩展名并与支持列表进行比较来判断。 + +## 参数 + +- `path` - 资源文件的完整或相对路径 + +## 返回值 + +`bool` - 如果文件扩展名在支持列表中返回 `true`，否则返回 `false` + +## 示例 + +```cpp +ShaderLoader loader; +bool canLoad = loader.CanLoad("shaders/pbr.vert"); // true +bool canLoad2 = loader.CanLoad("textures/wood.png"); // false +``` diff --git a/docs/api/resources/shaderloader/methods/constructor.md b/docs/api/resources/shaderloader/methods/constructor.md new file mode 100644 index 00000000..0188b697 --- /dev/null +++ b/docs/api/resources/shaderloader/methods/constructor.md @@ -0,0 +1,29 @@ +# ShaderLoader::ShaderLoader + +## 方法签名 + +```cpp +ShaderLoader(); +``` + +## 详细描述 + +默认构造函数，创建一个 `ShaderLoader` 实例。该加载器负责管理着色器资源的加载流程。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +``` diff --git a/docs/api/resources/shaderloader/methods/get-default-settings.md b/docs/api/resources/shaderloader/methods/get-default-settings.md new file mode 100644 index 00000000..2f24e76a --- /dev/null +++ b/docs/api/resources/shaderloader/methods/get-default-settings.md @@ -0,0 +1,27 @@ +# ShaderLoader::GetDefaultSettings + +## 方法签名 + +```cpp +ImportSettings* GetDefaultSettings() const override; +``` + +## 详细描述 + +返回着色器资源的默认导入设置。当前实现返回 `nullptr`，表示着色器加载不使用导入设置。 + +## 参数 + +无 + +## 返回值 + +`ImportSettings*` - 始终返回 `nullptr` + +## 示例 + +```cpp +ShaderLoader loader; +ImportSettings* settings = loader.GetDefaultSettings(); +// settings == nullptr +``` diff --git a/docs/api/resources/shaderloader/methods/get-resource-type.md b/docs/api/resources/shaderloader/methods/get-resource-type.md new file mode 100644 index 00000000..6f2c7ce8 --- /dev/null +++ b/docs/api/resources/shaderloader/methods/get-resource-type.md @@ -0,0 +1,27 @@ +# ShaderLoader::GetResourceType + +## 方法签名 + +```cpp +ResourceType GetResourceType() const override; +``` + +## 详细描述 + +返回该加载器管理的资源类型，固定为 `ResourceType::Shader`。此方法继承自 `IResourceLoader` 接口，用于资源管理器识别加载器类型。 + +## 参数 + +无 + +## 返回值 + +`ResourceType` - 资源类型枚举值，始终返回 `ResourceType::Shader` + +## 示例 + +```cpp +ShaderLoader loader; +ResourceType type = loader.GetResourceType(); +// type == ResourceType::Shader +``` diff --git a/docs/api/resources/shaderloader/methods/get-supported-extensions.md b/docs/api/resources/shaderloader/methods/get-supported-extensions.md new file mode 100644 index 00000000..841d3e3d --- /dev/null +++ b/docs/api/resources/shaderloader/methods/get-supported-extensions.md @@ -0,0 +1,37 @@ +# ShaderLoader::GetSupportedExtensions + +## 方法签名 + +```cpp +Containers::Array GetSupportedExtensions() const override; +``` + +## 详细描述 + +返回该加载器支持的文件扩展名列表。支持以下扩展名： + +- `vert` - 顶点着色器 +- `frag` - 片段着色器 +- `geom` - 几何着色器 +- `comp` - 计算着色器 +- `glsl` - 通用 GLSL 着色器 +- `hlsl` - HLSL 着色器 +- `shader` - 通用着色器 + +## 参数 + +无 + +## 返回值 + +`Containers::Array` - 支持的文件扩展名数组 + +## 示例 + +```cpp +ShaderLoader loader; +auto extensions = loader.GetSupportedExtensions(); +for (const auto& ext : extensions) { + // 处理每个扩展名 +} +``` diff --git a/docs/api/resources/shaderloader/methods/load.md b/docs/api/resources/shaderloader/methods/load.md new file mode 100644 index 00000000..e13d8ced --- /dev/null +++ b/docs/api/resources/shaderloader/methods/load.md @@ -0,0 +1,45 @@ +# ShaderLoader::Load + +## 方法签名 + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; +``` + +## 详细描述 + +加载指定路径的着色器资源文件。加载流程如下： + +1. 读取文件数据到内存 +2. 根据扩展名识别着色器语言（HLSL 或 GLSL） +3. 检测着色器类型（Vertex/Fragment/Geometry/Compute） +4. 创建 `Shader` 对象并设置属性 + +如果加载失败，返回的 `LoadResult` 将包含错误信息。 + +## 参数 + +- `path` - 着色器文件的路径 +- `settings` - 可选的导入设置指针（当前实现中未使用） + +## 返回值 + +`LoadResult` - 加载结果，成功时包含 `Shader` 指针，失败时包含错误信息 + +## 示例 + +```cpp +#include "Resources/ShaderLoader.h" + +using namespace XCEngine::Resources; + +ShaderLoader loader; +LoadResult result = loader.Load("shaders/forward.vert"); +if (result.IsSuccess()) { + Shader* shader = static_cast(result.GetResource()); + // 使用着色器... +} else { + // 处理错误 + const String& error = result.GetErrorMessage(); +} +``` diff --git a/docs/api/resources/texture-import-settings/texture-import-settings.md b/docs/api/resources/texture-import-settings/texture-import-settings.md new file mode 100644 index 00000000..46045716 --- /dev/null +++ b/docs/api/resources/texture-import-settings/texture-import-settings.md @@ -0,0 +1,120 @@ +# TextureImportSettings + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**继承**: `ImportSettings` + +**头文件**: `XCEngine/Resources/TextureImportSettings.h` + +**描述**: 纹理资源导入设置类，定义从外部图像文件导入纹理时的配置选项。 + +--- + +## 概述 + +`TextureImportSettings` 继承自 `ImportSettings`，提供纹理导入时的完整配置能力。支持纹理类型、目标格式、Mipmap 生成、各项异性过滤、sRGB 转换、图像翻转、边框颜色、压缩质量、硬件压缩、纹理最大尺寸、法线贴图生成等选项。`LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。 + +--- + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| `TextureImportSettings()` | 构造函数 | +| `virtual ~TextureImportSettings() override` | 析构函数 | +| `Core::UniqueRef Clone() const override` | 克隆设置对象 | +| `bool LoadFromJSON(const Containers::String& json) override` | 从 JSON 加载设置（stub） | +| `Containers::String SaveToJSON() const override` | 保存为 JSON（stub） | +| `void SetTextureType(TextureType type)` | 设置纹理类型 | +| `TextureType GetTextureType() const` | 获取纹理类型 | +| `void SetTargetFormat(TextureFormat format)` | 设置目标格式 | +| `TextureFormat GetTargetFormat() const` | 获取目标格式 | +| `void SetGenerateMipmaps(bool generate)` | 设置是否生成 Mipmap | +| `bool GetGenerateMipmaps() const` | 获取是否生成 Mipmap | +| `void SetMipmapFilter(MipmapFilter filter)` | 设置 Mipmap 滤波器 | +| `MipmapFilter GetMipmapFilter() const` | 获取 Mipmap 滤波器 | +| `void SetMaxAnisotropy(Core::uint32 anisotropy)` | 设置最大各向异性级别 | +| `Core::uint32 GetMaxAnisotropy() const` | 获取最大各向异性级别 | +| `void SetSRGB(bool srgb)` | 设置是否 sRGB | +| `bool GetSRGB() const` | 获取 sRGB 设置 | +| `void SetFlipVertical(bool flip)` | 设置是否垂直翻转 | +| `bool GetFlipVertical() const` | 获取垂直翻转设置 | +| `void SetFlipHorizontal(bool flip)` | 设置是否水平翻转 | +| `bool GetFlipHorizontal() const` | 获取水平翻转设置 | +| `void SetBorderColor(const Math::Vector3& color)` | 设置边框颜色 | +| `const Math::Vector3& GetBorderColor() const` | 获取边框颜色 | +| `void SetCompressionQuality(CompressionQuality quality)` | 设置压缩质量 | +| `CompressionQuality GetCompressionQuality() const` | 获取压缩质量 | +| `void SetUseHardwareCompression(bool use)` | 设置是否使用硬件压缩 | +| `bool GetUseHardwareCompression() const` | 获取硬件压缩设置 | +| `void SetMaxSize(Core::uint32 size)` | 设置最大纹理尺寸 | +| `Core::uint32 GetMaxSize() const` | 获取最大纹理尺寸 | +| `void SetGenerateNormalMap(bool generate)` | 设置是否生成法线贴图 | +| `bool GetGenerateNormalMap() const` | 获取法线贴图生成设置 | +| `void SetNormalMapStrength(float strength)` | 设置法线贴图强度 | +| `float GetNormalMapStrength() const` | 获取法线贴图强度 | + +--- + +## MipmapFilter 枚举 + +| 值 | 描述 | +|------|------| +| `Box` | Box 滤波器 | +| `Kaiser` | Kaiser 滤波器 | + +--- + +## CompressionQuality 枚举 + +| 值 | 描述 | +|------|------| +| `Low` | 低质量 | +| `Medium` | 中等质量 | +| `High` | 高质量 | +| `Ultra` | 超高质量 | + +--- + +## 使用示例 + +```cpp +#include +#include + +// 创建导入设置 +TextureImportSettings settings; +settings.SetTextureType(TextureType::Texture2D); +settings.SetTargetFormat(TextureFormat::RGBA8); +settings.SetGenerateMipmaps(true); +settings.SetMipmapFilter(MipmapFilter::Kaiser); +settings.SetMaxAnisotropy(16); +settings.SetSRGB(true); +settings.SetFlipVertical(false); +settings.SetFlipHorizontal(false); +settings.SetBorderColor(Math::Vector3::Zero()); +settings.SetCompressionQuality(CompressionQuality::High); +settings.SetUseHardwareCompression(true); +settings.SetMaxSize(2048); +settings.SetGenerateNormalMap(false); +settings.SetNormalMapStrength(1.0f); + +// 克隆设置 +auto cloned = settings.Clone(); + +// 加载纹理资源 +ResourceHandle tex = ResourceManager::Get().Load("textures/diffuse.png", &settings); +``` + +--- + +## 相关文档 + +- [方法详情](methods.md) - 所有方法的详细文档 +- [ImportSettings](../importsettings/importsettings.md) - 导入设置基类 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Texture](../texture/texture.md) - 纹理资源类 +- [Resources 总览](../resources.md) - 资源模块总览 diff --git a/docs/api/resources/texture-loader/index.md b/docs/api/resources/texture-loader/index.md new file mode 100644 index 00000000..c89bd578 --- /dev/null +++ b/docs/api/resources/texture-loader/index.md @@ -0,0 +1,139 @@ +# TextureLoader + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**描述**: 纹理资源加载器，负责从文件加载纹理资源。 + +**继承自**: `IResourceLoader` + +## 概述 + +`TextureLoader` 是 XCEngine 中的纹理资源加载器实现类，继承自 `IResourceLoader`。它支持从多种图像格式加载纹理数据，包括 PNG、JPG、TGA、BMP、GIF、HDR 和 DDS。 + +## 头文件 + +```cpp +#include +``` + +## 支持的格式 + +| 扩展名 | 描述 | +|--------|------| +| `png` | PNG 图像 | +| `jpg` / `jpeg` | JPEG 图像 | +| `tga` | TGA 图像 | +| `bmp` | BMP 图像 | +| `gif` | GIF 图像 | +| `hdr` | HDR 图像 | +| `dds` | DDS 压缩纹理 | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| `ResourceType GetResourceType() const` | 返回 `ResourceType::Texture` | +| `Containers::Array GetSupportedExtensions() const` | 获取支持的扩展名列表 | +| `bool CanLoad(const Containers::String& path) const` | 检查是否支持加载指定路径的纹理 | +| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 加载纹理资源 | +| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 | + +### GetResourceType + +```cpp +ResourceType GetResourceType() const override +``` + +返回资源的类型标识。 + +**返回值**: `ResourceType::Texture` + +--- + +### GetSupportedExtensions + +```cpp +Containers::Array GetSupportedExtensions() const override +``` + +返回所有支持的纹理文件扩展名列表。 + +**返回值**: 包含所有支持扩展名的字符串数组。 + +**支持的扩展名**: `png`, `jpg`, `jpeg`, `tga`, `bmp`, `gif`, `hdr`, `dds` + +--- + +### CanLoad + +```cpp +bool CanLoad(const Containers::String& path) const override +``` + +检查指定的文件路径是否可以被此加载器处理。 + +**参数**: +- `path`: 文件路径 + +**返回值**: 如果文件扩展名受支持返回 `true`，否则返回 `false`。 + +--- + +### Load + +```cpp +LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override +``` + +从指定路径加载纹理资源。 + +**参数**: +- `path`: 纹理文件路径 +- `settings`: 导入设置（可选，当前未使用） + +**返回值**: 加载成功返回包含 `Texture` 指针的 `LoadResult`；失败返回包含错误信息的 `LoadResult`。 + +**实现说明**: 当前实现仅读取文件数据和创建基础 `Texture` 对象，不解析实际的图像格式数据。 + +--- + +### GetDefaultSettings + +```cpp +ImportSettings* GetDefaultSettings() const override +``` + +获取默认的纹理导入设置。 + +**返回值**: `nullptr`（当前无默认设置） + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Resources; + +// 通过 ResourceManager 加载纹理 +ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); + +// 检查加载器是否支持特定格式 +TextureLoader loader; +if (loader.CanLoad("assets/image.dds")) { + // 可以加载 DDS 格式 +} +``` + +## 相关文档 + +- [Texture](../texture/texture.md) - 纹理资源类 +- [IResourceLoader](../iloader/iloader.md) - 资源加载器基类 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览 + +## 实现说明 + +**注意**: `Load()` 方法当前为示例实现，不解析 PNG/JPG 等格式的实际图像像素数据，仅创建空 `Texture` 对象并设置基础资源参数（name、path、guid、memorySize）。实际图像数据解析需要在后续版本中实现。 diff --git a/docs/api/resources/texture/create.md b/docs/api/resources/texture/create.md index 96f621ff..d7fdc743 100644 --- a/docs/api/resources/texture/create.md +++ b/docs/api/resources/texture/create.md @@ -6,32 +6,39 @@ bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, const void* data, size_t dataSize) ``` -创建纹理资源。设置纹理的尺寸、格式和像素数据，并分配 GPU 资源。 +创建纹理资源。设置纹理的尺寸、格式和像素数据。 **参数：** -- `width` - 纹理宽度（像素） -- `height` - 纹理高度（像素） -- `depth` - 纹理深度（3D 纹理设为 1） -- `mipLevels` - Mipmap 级别数 -- `type` - 纹理类型 -- `format` - 纹理格式 -- `data` - 像素数据指针 -- `dataSize` - 像素数据大小 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `width` | `Core::uint32` | 纹理宽度（像素） | +| `height` | `Core::uint32` | 纹理高度（像素） | +| `depth` | `Core::uint32` | 纹理深度（3D 纹理设为 1） | +| `mipLevels` | `Core::uint32` | Mipmap 级别数 | +| `type` | `TextureType` | 纹理类型 | +| `format` | `TextureFormat` | 纹理格式 | +| `data` | `const void*` | 像素数据指针（可为 nullptr） | +| `dataSize` | `size_t` | 像素数据大小 | **返回：** 创建成功返回 true -**复杂度：** O(n)，n 为像素数量 +**复杂度：** O(n)，n 为像素数据大小 **示例：** ```cpp Texture tex; bool ok = tex.Create( - 1024, 1024, 1, 0, + 1024, 1024, 1, 1, TextureType::Texture2D, TextureFormat::RGBA8_UNORM, pixelData, pixelDataSize ); + +if (ok) { + // 纹理创建成功 +} ``` ## 相关文档 diff --git a/docs/api/resources/texture/generatemipmaps.md b/docs/api/resources/texture/generatemipmaps.md index 37a51645..4de75d5d 100644 --- a/docs/api/resources/texture/generatemipmaps.md +++ b/docs/api/resources/texture/generatemipmaps.md @@ -8,15 +8,18 @@ bool GenerateMipmaps() **参数：** 无 -**返回：** 生成成功返回 true +**返回：** 生成成功返回 true；当前始终返回 false（stub 实现） **复杂度：** O(n) **示例：** ```cpp +Texture tex; tex.Create(1024, 1024, 1, 1, TextureType::Texture2D, TextureFormat::RGBA8_UNORM, data, size); -tex.GenerateMipmaps(); + +// 注意：当前实现返回 false，Mipmap 生成功能尚未完成 +bool success = tex.GenerateMipmaps(); ``` ## 相关文档 diff --git a/docs/api/resources/texture/getarraysize.md b/docs/api/resources/texture/getarraysize.md new file mode 100644 index 00000000..d645eb3c --- /dev/null +++ b/docs/api/resources/texture/getarraysize.md @@ -0,0 +1,36 @@ +# Texture::GetArraySize + +```cpp +Core::uint32 GetArraySize() const +``` + +获取纹理数组大小。对于非数组纹理返回 1。 + +**参数：** 无 + +**返回：** 纹理数组大小 + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +Core::uint32 arraySize = tex.GetArraySize(); // 返回 1 + +Texture texArray; +texArray.Create(1024, 1024, 1, 1, + TextureType::Texture2DArray, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +Core::uint32 arraySizeArray = texArray.GetArraySize(); // 返回数组长度 +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetTextureType](gettexturetype.md) - 获取纹理类型 \ No newline at end of file diff --git a/docs/api/resources/texture/getdepth.md b/docs/api/resources/texture/getdepth.md new file mode 100644 index 00000000..925a6122 --- /dev/null +++ b/docs/api/resources/texture/getdepth.md @@ -0,0 +1,37 @@ +# Texture::GetDepth + +```cpp +Core::uint32 GetDepth() const +``` + +获取纹理深度。对于 3D 纹理返回体积深度，对于 2D 纹理返回 1。 + +**参数：** 无 + +**返回：** 纹理深度（像素） + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex2D; +tex2D.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +Core::uint32 depth2D = tex2D.GetDepth(); // 返回 1 + +Texture tex3D; +tex3D.Create(64, 64, 32, 1, + TextureType::Texture3D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +Core::uint32 depth3D = tex3D.GetDepth(); // 返回 32 +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetWidth](getwidth.md) - 获取纹理宽度 +- [GetHeight](getheight.md) - 获取纹理高度 \ No newline at end of file diff --git a/docs/api/resources/texture/getformat.md b/docs/api/resources/texture/getformat.md new file mode 100644 index 00000000..1cc78fe5 --- /dev/null +++ b/docs/api/resources/texture/getformat.md @@ -0,0 +1,29 @@ +# Texture::GetFormat + +```cpp +TextureFormat GetFormat() const +``` + +获取纹理像素格式。 + +**参数：** 无 + +**返回：** `TextureFormat` 枚举值 + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +TextureFormat format = tex.GetFormat(); // 返回 TextureFormat::RGBA8_UNORM +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [TextureFormat 枚举](./texture.md#textureformat) - 格式枚举说明 \ No newline at end of file diff --git a/docs/api/resources/texture/getheight.md b/docs/api/resources/texture/getheight.md new file mode 100644 index 00000000..1fb44869 --- /dev/null +++ b/docs/api/resources/texture/getheight.md @@ -0,0 +1,30 @@ +# Texture::GetHeight + +```cpp +Core::uint32 GetHeight() const +``` + +获取纹理高度。 + +**参数：** 无 + +**返回：** 纹理高度（像素） + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 512, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); + +Core::uint32 height = tex.GetHeight(); // 返回 512 +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetWidth](getwidth.md) - 获取纹理宽度 \ No newline at end of file diff --git a/docs/api/resources/texture/getmiplevels.md b/docs/api/resources/texture/getmiplevels.md new file mode 100644 index 00000000..19cd056e --- /dev/null +++ b/docs/api/resources/texture/getmiplevels.md @@ -0,0 +1,32 @@ +# Texture::GetMipLevels + +```cpp +Core::uint32 GetMipLevels() const +``` + +获取 Mipmap 级别数。Mipmap 是纹理的多级渐远表示，用于在不同距离时提供合适的细节级别。 + +**参数：** 无 + +**返回：** Mipmap 级别数 + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +Core::uint32 mips = tex.GetMipLevels(); // 返回 1 + +tex.GenerateMipmaps(); // 如果实现生成多级 mipmap +Core::uint32 mipsAfter = tex.GetMipLevels(); // 可能返回 > 1 +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GenerateMipmaps](generatemipmaps.md) - 生成 Mipmap 链 \ No newline at end of file diff --git a/docs/api/resources/texture/getpixeldata.md b/docs/api/resources/texture/getpixeldata.md new file mode 100644 index 00000000..ce38c022 --- /dev/null +++ b/docs/api/resources/texture/getpixeldata.md @@ -0,0 +1,36 @@ +# Texture::GetPixelData + +```cpp +const void* GetPixelData() const +``` + +获取纹理像素数据指针。 + +**参数：** 无 + +**返回：** 像素数据指针，如果纹理未创建或无效返回 `nullptr` + +**线程安全：** ✅ + +**示例：** + +```cpp +// 假设已有像素数据 +std::vector pixels(1024 * 1024 * 4, 255); + +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + pixels.data(), pixels.size()); + +const void* data = tex.GetPixelData(); +if (data != nullptr) { + // 可以读取像素数据 +} +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetPixelDataSize](getpixeldatasize.md) - 获取像素数据大小 \ No newline at end of file diff --git a/docs/api/resources/texture/getpixeldatasize.md b/docs/api/resources/texture/getpixeldatasize.md new file mode 100644 index 00000000..cef0e47a --- /dev/null +++ b/docs/api/resources/texture/getpixeldatasize.md @@ -0,0 +1,32 @@ +# Texture::GetPixelDataSize + +```cpp +size_t GetPixelDataSize() const +``` + +获取纹理像素数据大小（字节）。 + +**参数：** 无 + +**返回：** 像素数据大小（字节） + +**线程安全：** ✅ + +**示例：** + +```cpp +std::vector pixels(1024 * 1024 * 4, 255); + +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + pixels.data(), pixels.size()); + +size_t size = tex.GetPixelDataSize(); // 返回 4194304 (1024*1024*4) +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetPixelData](getpixeldata.md) - 获取像素数据指针 \ No newline at end of file diff --git a/docs/api/resources/texture/gettexturetype.md b/docs/api/resources/texture/gettexturetype.md new file mode 100644 index 00000000..9bd95a33 --- /dev/null +++ b/docs/api/resources/texture/gettexturetype.md @@ -0,0 +1,29 @@ +# Texture::GetTextureType + +```cpp +TextureType GetTextureType() const +``` + +获取纹理类型。 + +**参数：** 无 + +**返回：** `TextureType` 枚举值 + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +TextureType type = tex.GetTextureType(); // 返回 TextureType::Texture2D +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetArraySize](getarraysize.md) - 获取数组大小 \ No newline at end of file diff --git a/docs/api/resources/texture/getusage.md b/docs/api/resources/texture/getusage.md new file mode 100644 index 00000000..ad759ad3 --- /dev/null +++ b/docs/api/resources/texture/getusage.md @@ -0,0 +1,29 @@ +# Texture::GetUsage + +```cpp +TextureUsage GetUsage() const +``` + +获取纹理用途标志。用途标志可组合使用。 + +**参数：** 无 + +**返回：** `TextureUsage` 枚举值 + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +TextureUsage usage = tex.GetUsage(); // 返回 TextureUsage::ShaderResource +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [TextureUsage 枚举](./texture.md#textureusage) - 用途枚举说明 \ No newline at end of file diff --git a/docs/api/resources/texture/getwidth.md b/docs/api/resources/texture/getwidth.md new file mode 100644 index 00000000..c9a5797f --- /dev/null +++ b/docs/api/resources/texture/getwidth.md @@ -0,0 +1,30 @@ +# Texture::GetWidth + +```cpp +Core::uint32 GetWidth() const +``` + +获取纹理宽度。 + +**参数：** 无 + +**返回：** 纹理宽度（像素） + +**线程安全：** ✅ + +**示例：** + +```cpp +Texture tex; +tex.Create(1024, 512, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); + +Core::uint32 width = tex.GetWidth(); // 返回 1024 +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [GetHeight](getheight.md) - 获取纹理高度 \ No newline at end of file diff --git a/docs/api/resources/texture/texture.md b/docs/api/resources/texture/texture.md index 1c8fa988..636052a1 100644 --- a/docs/api/resources/texture/texture.md +++ b/docs/api/resources/texture/texture.md @@ -2,7 +2,9 @@ **命名空间**: `XCEngine::Resources` -**类型**: `class` +**类型**: `class` (inherits from `IResource`) + +**头文件**: `XCEngine/Resources/Texture.h` **描述**: 纹理资源类，管理 2D/3D 纹理和立方体贴图的像素数据。 @@ -79,74 +81,74 @@ ## 公共方法 -### 基础属性 +### 构造与析构 | 方法 | 描述 | |------|------| -| `ResourceType GetType() const` | 返回 `ResourceType::Texture` | -| `const Containers::String& GetName() const` | 获取纹理名称 | -| `const Containers::String& GetPath() const` | 获取纹理路径 | -| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 | -| `bool IsValid() const` | 检查纹理是否有效 | -| `size_t GetMemorySize() const` | 获取内存大小 | -| `void Release()` | 释放纹理引用 | +| [`Texture`](texture_constructor.md) | 默认构造函数 | +| [`~Texture`](texture_destructor.md) | 析构函数 | + +### IResource 实现 + +继承自 `IResource` 接口。 + +| 方法 | 描述 | +|------|------| +| [`GetType`](../iresource/gettype.md) | 返回 `ResourceType::Texture` | +| [`GetName`](../iresource/getname.md) | 获取纹理名称 | +| [`GetPath`](../iresource/getpath.md) | 获取纹理路径 | +| [`GetGUID`](../iresource/getguid.md) | 获取全局唯一标识符 | +| [`IsValid`](../iresource/isvalid.md) | 检查纹理是否有效 | +| [`GetMemorySize`](../iresource/getmemorysize.md) | 获取内存大小 | +| [`Release`](../iresource/release.md) | 释放纹理引用 | ### 纹理属性 | 方法 | 描述 | |------|------| -| `Core::uint32 GetWidth() const` | 获取纹理宽度（像素） | -| `Core::uint32 GetHeight() const` | 获取纹理高度（像素） | -| `Core::uint32 GetDepth() const` | 获取纹理深度（3D 纹理） | -| `Core::uint32 GetMipLevels() const` | 获取 Mipmap 级别数 | -| `Core::uint32 GetArraySize() const` | 获取数组大小 | -| `TextureType GetTextureType() const` | 获取纹理类型 | -| `TextureFormat GetFormat() const` | 获取纹理格式 | -| `TextureUsage GetUsage() const` | 获取纹理用途标志 | +| [`GetWidth`](getwidth.md) | 获取纹理宽度（像素） | +| [`GetHeight`](getheight.md) | 获取纹理高度（像素） | +| [`GetDepth`](getdepth.md) | 获取纹理深度（3D 纹理） | +| [`GetMipLevels`](getmiplevels.md) | 获取 Mipmap 级别数 | +| [`GetArraySize`](getarraysize.md) | 获取数组大小 | +| [`GetTextureType`](gettexturetype.md) | 获取纹理类型 | +| [`GetFormat`](getformat.md) | 获取纹理格式 | +| [`GetUsage`](getusage.md) | 获取纹理用途标志 | ### 像素数据 | 方法 | 描述 | |------|------| -| `const void* GetPixelData() const` | 获取像素数据指针 | -| `size_t GetPixelDataSize() const` | 获取像素数据大小 | +| [`GetPixelData`](getpixeldata.md) | 获取像素数据指针 | +| [`GetPixelDataSize`](getpixeldatasize.md) | 获取像素数据大小 | ### 创建与操作 | 方法 | 描述 | |------|------| -| `bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, Core::uint32 mipLevels, TextureType type, TextureFormat format, const void* data, size_t dataSize)` | 创建纹理 | -| `bool GenerateMipmaps()` | 生成 Mipmap（当前返回 false - stub） | - -## 实现说明 - -**注意**: `Create()` 方法中 `mipLevels` 参数为 0 时不会自动计算所有级别。`GenerateMipmaps()` 当前返回 false，为 stub 实现。 +| [`Create`](create.md) | 创建纹理 | +| [`GenerateMipmaps`](generatemipmaps.md) | 生成 Mipmap 链 | ## 使用示例 ```cpp -// 加载纹理 -ResourceHandle tex = ResourceManager::Get().Load("textures/player.png"); - // 手动创建纹理 Texture tex; bool created = tex.Create( 1024, // 宽度 1024, // 高度 1, // 深度 - 0, // Mipmap 级别（0=全部） - TextureType::Texture2D, // 类型 - TextureFormat::RGBA8_UNORM, // 格式 + 1, // Mipmap 级别数 + TextureType::Texture2D, // 类型 + TextureFormat::RGBA8_UNORM, // 格式 pixelData, // 像素数据 pixelDataSize // 数据大小 ); -// 生成 Mipmap -tex.GenerateMipmaps(); - // 访问纹理属性 uint32_t w = tex.GetWidth(); uint32_t h = tex.GetHeight(); +auto format = tex.GetFormat(); ``` ## 相关文档 @@ -154,8 +156,4 @@ uint32_t h = tex.GetHeight(); - [IResource](../iresource/iresource.md) - 资源基类 - [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 - [RHITexture](../../rhi/texture/texture.md) - RHI 纹理接口 -- [Resources 总览](../resources.md) - 返回模块总览 - -## 实现说明 - -**注意**: `TextureLoader::Load()` 仅为示例实现，不解析 PNG/JPG 等格式的实际图像数据，仅创建空纹理对象。 +- [Resources 总览](../resources.md) - 返回模块总览 \ No newline at end of file diff --git a/docs/api/resources/texture/texture_constructor.md b/docs/api/resources/texture/texture_constructor.md new file mode 100644 index 00000000..62e1e4d4 --- /dev/null +++ b/docs/api/resources/texture/texture_constructor.md @@ -0,0 +1,29 @@ +# Texture::Texture + +```cpp +Texture() +``` + +默认构造函数。创建一个无效的 Texture 对象，需要调用 `Create` 方法进行初始化。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ + +**示例：** + +```cpp +Texture tex; +// tex 此时无效，需要调用 Create 方法 +bool ok = tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [Create](create.md) - 创建纹理方法 \ No newline at end of file diff --git a/docs/api/resources/texture/texture_destructor.md b/docs/api/resources/texture/texture_destructor.md new file mode 100644 index 00000000..fb6decb5 --- /dev/null +++ b/docs/api/resources/texture/texture_destructor.md @@ -0,0 +1,31 @@ +# Texture::~Texture + +```cpp +virtual ~Texture() +``` + +析构函数。释放纹理占用的资源。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ + +**示例：** + +```cpp +{ + Texture tex; + tex.Create(1024, 1024, 1, 1, + TextureType::Texture2D, + TextureFormat::RGBA8_UNORM, + nullptr, 0); + // tex 超出作用域时自动调用析构函数释放资源 +} +``` + +## 相关文档 + +- [Texture 总览](texture.md) - 返回类总览 +- [Release](../iresource/release.md) - 手动释放资源方法 \ No newline at end of file diff --git a/docs/api/resources/textureimportsettings/clone.md b/docs/api/resources/textureimportsettings/clone.md new file mode 100644 index 00000000..9b25c039 --- /dev/null +++ b/docs/api/resources/textureimportsettings/clone.md @@ -0,0 +1,25 @@ +# TextureImportSettings::Clone + +```cpp +Core::UniqueRef Clone() const override; +``` + +创建并返回一份当前设置的深拷贝。 + +**返回：** `Core::UniqueRef` - 新的 `TextureImportSettings` 克隆 + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetTextureType(TextureType::Texture2D); + +auto cloned = settings.Clone(); +// cloned 是独立的副本，修改不影响原对象 +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/getbordercolor.md b/docs/api/resources/textureimportsettings/getbordercolor.md new file mode 100644 index 00000000..6a5c400d --- /dev/null +++ b/docs/api/resources/textureimportsettings/getbordercolor.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetBorderColor + +参见 [`SetBorderColor`](setbordercolor.md) diff --git a/docs/api/resources/textureimportsettings/getcompressionquality.md b/docs/api/resources/textureimportsettings/getcompressionquality.md new file mode 100644 index 00000000..6a25c1f2 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getcompressionquality.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetCompressionQuality + +参见 [`SetCompressionQuality`](setcompressionquality.md) diff --git a/docs/api/resources/textureimportsettings/getfliphhorizontal.md b/docs/api/resources/textureimportsettings/getfliphhorizontal.md new file mode 100644 index 00000000..4ff040d7 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getfliphhorizontal.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetFlipHorizontal + +参见 [`SetFlipHorizontal`](setfliphhorizontal.md) diff --git a/docs/api/resources/textureimportsettings/getflipvertical.md b/docs/api/resources/textureimportsettings/getflipvertical.md new file mode 100644 index 00000000..d9ff83f2 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getflipvertical.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetFlipVertical + +参见 [`SetFlipVertical`](setflipvertical.md) diff --git a/docs/api/resources/textureimportsettings/getgeneratemipmaps.md b/docs/api/resources/textureimportsettings/getgeneratemipmaps.md new file mode 100644 index 00000000..26171747 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getgeneratemipmaps.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetGenerateMipmaps + +参见 [`SetGenerateMipmaps`](setgeneratemipmaps.md) diff --git a/docs/api/resources/textureimportsettings/getgeneratenormalmap.md b/docs/api/resources/textureimportsettings/getgeneratenormalmap.md new file mode 100644 index 00000000..2e34239e --- /dev/null +++ b/docs/api/resources/textureimportsettings/getgeneratenormalmap.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetGenerateNormalMap + +参见 [`SetGenerateNormalMap`](setgeneratenormalmap.md) diff --git a/docs/api/resources/textureimportsettings/getmaxanisotropy.md b/docs/api/resources/textureimportsettings/getmaxanisotropy.md new file mode 100644 index 00000000..ed878d34 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getmaxanisotropy.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetMaxAnisotropy + +参见 [`SetMaxAnisotropy`](setmaxanisotropy.md) diff --git a/docs/api/resources/textureimportsettings/getmaxsize.md b/docs/api/resources/textureimportsettings/getmaxsize.md new file mode 100644 index 00000000..1e83dcc5 --- /dev/null +++ b/docs/api/resources/textureimportsettings/getmaxsize.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetMaxSize + +参见 [`SetMaxSize`](setmaxsize.md) diff --git a/docs/api/resources/textureimportsettings/getmipmapfilter.md b/docs/api/resources/textureimportsettings/getmipmapfilter.md new file mode 100644 index 00000000..650ef7dc --- /dev/null +++ b/docs/api/resources/textureimportsettings/getmipmapfilter.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetMipmapFilter + +参见 [`SetMipmapFilter`](setmipmapfilter.md) diff --git a/docs/api/resources/textureimportsettings/getnormalmapstrength.md b/docs/api/resources/textureimportsettings/getnormalmapstrength.md new file mode 100644 index 00000000..b844d9cb --- /dev/null +++ b/docs/api/resources/textureimportsettings/getnormalmapstrength.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetNormalMapStrength + +参见 [`SetNormalMapStrength`](setnormalmapstrength.md) diff --git a/docs/api/resources/textureimportsettings/getsrgb.md b/docs/api/resources/textureimportsettings/getsrgb.md new file mode 100644 index 00000000..15f4721a --- /dev/null +++ b/docs/api/resources/textureimportsettings/getsrgb.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetSRGB + +参见 [`SetSRGB`](setsrgb.md) diff --git a/docs/api/resources/textureimportsettings/gettargetformat.md b/docs/api/resources/textureimportsettings/gettargetformat.md new file mode 100644 index 00000000..e71dbb23 --- /dev/null +++ b/docs/api/resources/textureimportsettings/gettargetformat.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetTargetFormat + +参见 [`SetTargetFormat`](settargetformat.md) diff --git a/docs/api/resources/textureimportsettings/gettexturetype.md b/docs/api/resources/textureimportsettings/gettexturetype.md new file mode 100644 index 00000000..03b8f98a --- /dev/null +++ b/docs/api/resources/textureimportsettings/gettexturetype.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetTextureType + +参见 [`SetTextureType`](settexturetype.md) diff --git a/docs/api/resources/textureimportsettings/getusehardwarecompression.md b/docs/api/resources/textureimportsettings/getusehardwarecompression.md new file mode 100644 index 00000000..0d0be77b --- /dev/null +++ b/docs/api/resources/textureimportsettings/getusehardwarecompression.md @@ -0,0 +1,3 @@ +# TextureImportSettings::GetUseHardwareCompression + +参见 [`SetUseHardwareCompression`](setusehardwarecompression.md) diff --git a/docs/api/resources/textureimportsettings/loadfromjson.md b/docs/api/resources/textureimportsettings/loadfromjson.md new file mode 100644 index 00000000..30efb7cc --- /dev/null +++ b/docs/api/resources/textureimportsettings/loadfromjson.md @@ -0,0 +1,28 @@ +# TextureImportSettings::LoadFromJSON + +```cpp +bool LoadFromJSON(const Containers::String& json) override; +``` + +从 JSON 字符串加载导入设置。 + +**参数：** +- `json` - JSON 格式的设置字符串 + +**返回：** `bool` - 加载是否成功 + +**注意：** 当前为 stub 实现，始终返回 `false`。 + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +bool success = settings.LoadFromJSON(R"({"textureType":1,"sRGB":true})"); +// 当前实现返回 false +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/savetojson.md b/docs/api/resources/textureimportsettings/savetojson.md new file mode 100644 index 00000000..d0970739 --- /dev/null +++ b/docs/api/resources/textureimportsettings/savetojson.md @@ -0,0 +1,26 @@ +# TextureImportSettings::SaveToJSON + +```cpp +Containers::String SaveToJSON() const override; +``` + +将当前设置序列化为 JSON 字符串。 + +**返回：** `Containers::String` - JSON 格式的设置字符串 + +**注意：** 当前为 stub 实现，始终返回空字符串。 + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetSRGB(true); +Containers::String json = settings.SaveToJSON(); +// 当前实现返回空字符串 +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setbordercolor.md b/docs/api/resources/textureimportsettings/setbordercolor.md new file mode 100644 index 00000000..c99dce5a --- /dev/null +++ b/docs/api/resources/textureimportsettings/setbordercolor.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetBorderColor / GetBorderColor + +```cpp +void SetBorderColor(const Math::Vector3& color); +const Math::Vector3& GetBorderColor() const; +``` + +设置或获取纹理边框颜色。 + +**参数：** +- `color` - 边框颜色（RGB） + +**返回：** `const Math::Vector3&` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetBorderColor(Math::Vector3(1.0f, 0.0f, 0.0f)); // 红色边框 +const Math::Vector3& color = settings.GetBorderColor(); +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setcompressionquality.md b/docs/api/resources/textureimportsettings/setcompressionquality.md new file mode 100644 index 00000000..adbaff55 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setcompressionquality.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetCompressionQuality / GetCompressionQuality + +```cpp +void SetCompressionQuality(CompressionQuality quality); +CompressionQuality GetCompressionQuality() const; +``` + +设置或获取纹理压缩质量级别。 + +**参数：** +- `quality` - 压缩质量（`Low`、`Medium`、`High`、`Ultra`） + +**返回：** `CompressionQuality` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetCompressionQuality(CompressionQuality::High); +CompressionQuality quality = settings.GetCompressionQuality(); // CompressionQuality::High +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setfliphhorizontal.md b/docs/api/resources/textureimportsettings/setfliphhorizontal.md new file mode 100644 index 00000000..f1d9cb14 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setfliphhorizontal.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetFlipHorizontal / GetFlipHorizontal + +```cpp +void SetFlipHorizontal(bool flip); +bool GetFlipHorizontal() const; +``` + +设置或获取是否在导入时水平翻转纹理。 + +**参数：** +- `flip` - 是否水平翻转 + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetFlipHorizontal(true); +bool flip = settings.GetFlipHorizontal(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setflipvertical.md b/docs/api/resources/textureimportsettings/setflipvertical.md new file mode 100644 index 00000000..465088c6 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setflipvertical.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetFlipVertical / GetFlipVertical + +```cpp +void SetFlipVertical(bool flip); +bool GetFlipVertical() const; +``` + +设置或获取是否在导入时垂直翻转纹理。 + +**参数：** +- `flip` - 是否垂直翻转 + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetFlipVertical(true); +bool flip = settings.GetFlipVertical(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setgeneratemipmaps.md b/docs/api/resources/textureimportsettings/setgeneratemipmaps.md new file mode 100644 index 00000000..13e4ad80 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setgeneratemipmaps.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetGenerateMipmaps / GetGenerateMipmaps + +```cpp +void SetGenerateMipmaps(bool generate); +bool GetGenerateMipmaps() const; +``` + +设置或获取是否生成 Mipmap。 + +**参数：** +- `generate` - 是否生成 Mipmap + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetGenerateMipmaps(true); +bool generate = settings.GetGenerateMipmaps(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setgeneratenormalmap.md b/docs/api/resources/textureimportsettings/setgeneratenormalmap.md new file mode 100644 index 00000000..e843ba57 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setgeneratenormalmap.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetGenerateNormalMap / GetGenerateNormalMap + +```cpp +void SetGenerateNormalMap(bool generate); +bool GetGenerateNormalMap() const; +``` + +设置或获取是否在导入时生成法线贴图。 + +**参数：** +- `generate` - 是否生成法线贴图 + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetGenerateNormalMap(true); +bool generate = settings.GetGenerateNormalMap(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setmaxanisotropy.md b/docs/api/resources/textureimportsettings/setmaxanisotropy.md new file mode 100644 index 00000000..204372f4 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setmaxanisotropy.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetMaxAnisotropy / GetMaxAnisotropy + +```cpp +void SetMaxAnisotropy(Core::uint32 anisotropy); +Core::uint32 GetMaxAnisotropy() const; +``` + +设置或获取最大各向异性过滤级别。 + +**参数：** +- `anisotropy` - 各向异性级别（通常为 1, 2, 4, 8, 16） + +**返回：** `Core::uint32` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetMaxAnisotropy(16); +Core::uint32 anisotropy = settings.GetMaxAnisotropy(); // 16 +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setmaxsize.md b/docs/api/resources/textureimportsettings/setmaxsize.md new file mode 100644 index 00000000..f9005c9c --- /dev/null +++ b/docs/api/resources/textureimportsettings/setmaxsize.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetMaxSize / GetMaxSize + +```cpp +void SetMaxSize(Core::uint32 size); +Core::uint32 GetMaxSize() const; +``` + +设置或获取最大纹理尺寸。纹理将被缩放以适应此尺寸。 + +**参数：** +- `size` - 最大边长（像素） + +**返回：** `Core::uint32` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetMaxSize(2048); +Core::uint32 size = settings.GetMaxSize(); // 2048 +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setmipmapfilter.md b/docs/api/resources/textureimportsettings/setmipmapfilter.md new file mode 100644 index 00000000..77d7c413 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setmipmapfilter.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetMipmapFilter / GetMipmapFilter + +```cpp +void SetMipmapFilter(MipmapFilter filter); +MipmapFilter GetMipmapFilter() const; +``` + +设置或获取 Mipmap 滤波算法。 + +**参数：** +- `filter` - Mipmap 滤波器类型（`MipmapFilter::Box` 或 `MipmapFilter::Kaiser`） + +**返回：** `MipmapFilter` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetMipmapFilter(MipmapFilter::Kaiser); +MipmapFilter filter = settings.GetMipmapFilter(); // MipmapFilter::Kaiser +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setnormalmapstrength.md b/docs/api/resources/textureimportsettings/setnormalmapstrength.md new file mode 100644 index 00000000..1598de38 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setnormalmapstrength.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetNormalMapStrength / GetNormalMapStrength + +```cpp +void SetNormalMapStrength(float strength); +float GetNormalMapStrength() const; +``` + +设置或获取法线贴图强度。 + +**参数：** +- `strength` - 法线贴图强度系数 + +**返回：** `float` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetNormalMapStrength(2.0f); +float strength = settings.GetNormalMapStrength(); // 2.0f +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/setsrgb.md b/docs/api/resources/textureimportsettings/setsrgb.md new file mode 100644 index 00000000..6ea7e6b0 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setsrgb.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetSRGB / GetSRGB + +```cpp +void SetSRGB(bool srgb); +bool GetSRGB() const; +``` + +设置或获取 sRGB 颜色空间标记。 + +**参数：** +- `srgb` - 是否使用 sRGB 颜色空间 + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetSRGB(true); +bool srgb = settings.GetSRGB(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/settargetformat.md b/docs/api/resources/textureimportsettings/settargetformat.md new file mode 100644 index 00000000..aabf9329 --- /dev/null +++ b/docs/api/resources/textureimportsettings/settargetformat.md @@ -0,0 +1,28 @@ +# TextureImportSettings::SetTargetFormat / GetTargetFormat + +```cpp +void SetTargetFormat(TextureFormat format); +TextureFormat GetTargetFormat() const; +``` + +设置或获取目标纹理格式。 + +**参数：** +- `format` - 目标格式（参见 `TextureFormat` 枚举） + +**返回：** `TextureFormat` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetTargetFormat(TextureFormat::RGBA8); +TextureFormat format = settings.GetTargetFormat(); // TextureFormat::RGBA8 +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 +- [Texture](../texture/texture.md) - 纹理格式定义 diff --git a/docs/api/resources/textureimportsettings/settexturetype.md b/docs/api/resources/textureimportsettings/settexturetype.md new file mode 100644 index 00000000..8602d10c --- /dev/null +++ b/docs/api/resources/textureimportsettings/settexturetype.md @@ -0,0 +1,28 @@ +# TextureImportSettings::SetTextureType / GetTextureType + +```cpp +void SetTextureType(TextureType type); +TextureType GetTextureType() const; +``` + +设置或获取纹理类型。 + +**参数：** +- `type` - 纹理类型（参见 `TextureType` 枚举） + +**返回：** `TextureType` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetTextureType(TextureType::Texture2D); +TextureType type = settings.GetTextureType(); // TextureType::Texture2D +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 +- [Texture](../texture/texture.md) - 纹理类型定义 diff --git a/docs/api/resources/textureimportsettings/setusehardwarecompression.md b/docs/api/resources/textureimportsettings/setusehardwarecompression.md new file mode 100644 index 00000000..5aa83098 --- /dev/null +++ b/docs/api/resources/textureimportsettings/setusehardwarecompression.md @@ -0,0 +1,27 @@ +# TextureImportSettings::SetUseHardwareCompression / GetUseHardwareCompression + +```cpp +void SetUseHardwareCompression(bool use); +bool GetUseHardwareCompression() const; +``` + +设置或获取是否使用硬件压缩（GPU 压缩格式）。 + +**参数：** +- `use` - 是否使用硬件压缩 + +**返回：** `bool` / `void` + +**线程安全：** ✅ + +**示例：** + +```cpp +TextureImportSettings settings; +settings.SetUseHardwareCompression(true); +bool use = settings.GetUseHardwareCompression(); // true +``` + +## 相关文档 + +- [TextureImportSettings 总览](textureimportsettings.md) - 返回类总览 diff --git a/docs/api/resources/textureimportsettings/textureimportsettings.md b/docs/api/resources/textureimportsettings/textureimportsettings.md new file mode 100644 index 00000000..a7798ad2 --- /dev/null +++ b/docs/api/resources/textureimportsettings/textureimportsettings.md @@ -0,0 +1,101 @@ +# TextureImportSettings + +**命名空间**: `XCEngine::Resources` + +**类型**: `class` + +**继承**: `ImportSettings` + +**描述**: 纹理资源导入设置类，配置纹理导入时的各种参数选项。 + +## 概述 + +`TextureImportSettings` 继承自 `ImportSettings`，提供了纹理资源导入时的完整配置选项。包括纹理类型、目标格式、Mipmap 生成、压缩质量、各向异性、sRGB 转换、翻转操作、法线图生成等功能。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Clone`](clone.md) | 克隆一份导入设置 | +| [`LoadFromJSON`](loadfromjson.md) | 从 JSON 加载设置 | +| [`SaveToJSON`](savetojson.md) | 保存设置到 JSON | +| [`SetTextureType`](settexturetype.md) | 设置纹理类型 | +| [`GetTextureType`](gettexturetype.md) | 获取纹理类型 | +| [`SetTargetFormat`](settargetformat.md) | 设置目标格式 | +| [`GetTargetFormat`](gettargetformat.md) | 获取目标格式 | +| [`SetGenerateMipmaps`](setgeneratemipmaps.md) | 设置是否生成 Mipmap | +| [`GetGenerateMipmaps`](getgeneratemipmaps.md) | 获取是否生成 Mipmap | +| [`SetMipmapFilter`](setmipmapfilter.md) | 设置 Mipmap 滤波器 | +| [`GetMipmapFilter`](getmipmapfilter.md) | 获取 Mipmap 滤波器 | +| [`SetMaxAnisotropy`](setmaxanisotropy.md) | 设置最大各向异性级别 | +| [`GetMaxAnisotropy`](getmaxanisotropy.md) | 获取最大各向异性级别 | +| [`SetSRGB`](setsrgb.md) | 设置是否 sRGB | +| [`GetSRGB`](getsrgb.md) | 获取 sRGB 设置 | +| [`SetFlipVertical`](setflipvertical.md) | 设置是否垂直翻转 | +| [`GetFlipVertical`](getflipvertical.md) | 获取垂直翻转设置 | +| [`SetFlipHorizontal`](setfliphhorizontal.md) | 设置是否水平翻转 | +| [`GetFlipHorizontal`](getfliphhorizontal.md) | 获取水平翻转设置 | +| [`SetBorderColor`](setbordercolor.md) | 设置边框颜色 | +| [`GetBorderColor`](getbordercolor.md) | 获取边框颜色 | +| [`SetCompressionQuality`](setcompressionquality.md) | 设置压缩质量 | +| [`GetCompressionQuality`](getcompressionquality.md) | 获取压缩质量 | +| [`SetUseHardwareCompression`](setusehardwarecompression.md) | 设置是否使用硬件压缩 | +| [`GetUseHardwareCompression`](getusehardwarecompression.md) | 获取硬件压缩设置 | +| [`SetMaxSize`](setmaxsize.md) | 设置最大纹理尺寸 | +| [`GetMaxSize`](getmaxsize.md) | 获取最大纹理尺寸 | +| [`SetGenerateNormalMap`](setgeneratenormalmap.md) | 设置是否生成法线贴图 | +| [`GetGenerateNormalMap`](getgeneratenormalmap.md) | 获取法线贴图生成设置 | +| [`SetNormalMapStrength`](setnormalmapstrength.md) | 设置法线贴图强度 | +| [`GetNormalMapStrength`](getnormalmapstrength.md) | 获取法线贴图强度 | + +## 枚举类型 + +### MipmapFilter + +Mipmap 滤波算法。 + +| 值 | 描述 | +|----|------| +| `Box` | Box 滤波器 | +| `Kaiser` | Kaiser 滤波器 | + +### CompressionQuality + +纹理压缩质量级别。 + +| 值 | 描述 | +|----|------| +| `Low` | 低质量压缩 | +| `Medium` | 中等质量压缩 | +| `High` | 高质量压缩 | +| `Ultra` | 超高质量压缩 | + +## 使用示例 + +```cpp +#include + +TextureImportSettings settings; +settings.SetTextureType(TextureType::Texture2D); +settings.SetGenerateMipmaps(true); +settings.SetMipmapFilter(MipmapFilter::Kaiser); +settings.SetSRGB(true); +settings.SetCompressionQuality(CompressionQuality::High); +settings.SetMaxAnisotropy(16); +settings.SetMaxSize(2048); +settings.SetGenerateNormalMap(true); +settings.SetNormalMapStrength(1.0f); + +// 保存设置 +Containers::String json = settings.SaveToJSON(); + +// 克隆设置 +auto cloned = settings.Clone(); +``` + +## 相关文档 + +- [ImportSettings](../importsettings/importsettings.md) - 导入设置基类 +- [Texture](../texture/texture.md) - 纹理资源 +- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器 +- [Resources 总览](../resources.md) - 返回模块总览