fix: improve doc link navigation and tree display
- Fix link resolution with proper relative/absolute path handling - Improve link styling with underline decoration - Hide leaf nodes from tree, only show directories - Fix log file path for packaged app
This commit is contained in:
107
docs/api/resources/asyncloader/asyncloader.md
Normal file
107
docs/api/resources/asyncloader/asyncloader.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# AsyncLoader
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (singleton)
|
||||
|
||||
**描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。
|
||||
|
||||
## 概述
|
||||
|
||||
`AsyncLoader` 是 XCEngine 的后台异步加载系统。它使用独立工作线程从磁盘加载资源，并在加载完成后通过回调通知调用者。它维护待处理队列和完成队列，通过双缓冲机制实现无锁的线程安全操作。
|
||||
|
||||
## 单例访问
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `static AsyncLoader& Get()` | 获取单例实例 |
|
||||
|
||||
## LoadRequest 结构体
|
||||
|
||||
异步加载请求结构体。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `path` | `Containers::String` | 资源路径 |
|
||||
| `type` | `ResourceType` | 资源类型 |
|
||||
| `callback` | `std::function<void(LoadResult)>` | 加载完成回调函数 |
|
||||
| `settings` | `ImportSettings*` | 导入设置（可为 nullptr） |
|
||||
| `requestId` | `Core::uint64` | 请求唯一标识符 |
|
||||
|
||||
### 构造方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `LoadRequest()` | 默认构造 |
|
||||
| `LoadRequest(const Containers::String& p, ResourceType t, std::function<void(LoadResult)> cb, ImportSettings* s = nullptr)` | 从参数构造 |
|
||||
| `LoadRequest(LoadRequest&& other) noexcept` | 移动构造 |
|
||||
| `LoadRequest(const LoadRequest&) = default` | 拷贝构造 |
|
||||
|
||||
### 赋值
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `LoadRequest& operator=(LoadRequest&& other) noexcept` | 移动赋值 |
|
||||
| `LoadRequest& operator=(const LoadRequest&) = default` | 拷贝赋值 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void Initialize(Core::uint32 workerThreadCount = 2)` | 初始化异步加载器，创建工作线程 |
|
||||
| `void Shutdown()` | 关闭异步加载器，等待所有挂起任务完成 |
|
||||
| `void Submit(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 提交异步加载请求 |
|
||||
| `void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载请求 |
|
||||
| `void Update()` | 更新函数，在主线程调用，处理完成的加载请求 |
|
||||
| `bool IsLoading() const` | 是否有正在加载的资源 |
|
||||
| `Core::uint32 GetPendingCount() const` | 获取待处理加载请求数量 |
|
||||
| `float GetProgress() const` | 获取整体加载进度（0.0f ~ 1.0f） |
|
||||
| `void CancelAll()` | 取消所有待处理的加载请求 |
|
||||
| `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: 当前 `AsyncLoader` 的实现为部分完成状态（stub）：
|
||||
- `Initialize()` 工作线程数参数被忽略
|
||||
- `Submit()` 仅将请求加入队列，不进行实际异步加载
|
||||
- `Update()` 不执行实际加载，直接调用回调返回成功
|
||||
- `QueueCompleted()` 和 `Cancel()` 为空实现
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 初始化（使用 4 个工作线程）
|
||||
AsyncLoader::Get().Initialize(4);
|
||||
|
||||
// 提交多个异步加载请求
|
||||
AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
|
||||
[](LoadResult result) {
|
||||
if (result.success) {
|
||||
ResourceHandle<Texture> tex(result.resource);
|
||||
printf("Texture loaded: %s\n", tex->GetPath().CStr());
|
||||
}
|
||||
});
|
||||
|
||||
AsyncLoader::Get().Submit("models/player.fbx", ResourceType::Mesh,
|
||||
[](LoadResult result) {
|
||||
if (result.success) {
|
||||
ResourceHandle<Mesh> mesh(result.resource);
|
||||
printf("Mesh loaded: %s\n", mesh->GetPath().CStr());
|
||||
}
|
||||
});
|
||||
|
||||
// 在主循环中调用 Update 处理完成回调
|
||||
while (AsyncLoader::Get().IsLoading()) {
|
||||
AsyncLoader::Get().Update(); // 在主线程分发回调
|
||||
// 其他渲染逻辑...
|
||||
}
|
||||
|
||||
// 关闭
|
||||
AsyncLoader::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
26
docs/api/resources/asyncloader/cancelall.md
Normal file
26
docs/api/resources/asyncloader/cancelall.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# AsyncLoader::CancelAll
|
||||
|
||||
```cpp
|
||||
void CancelAll()
|
||||
```
|
||||
|
||||
取消所有待处理的加载请求。清空待处理队列，不会触发任何回调。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
// 场景切换时取消所有加载请求
|
||||
void OnSceneChange() {
|
||||
AsyncLoader::Get().CancelAll();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [AsyncLoader 总览](asyncloader.md) - 返回类总览
|
||||
24
docs/api/resources/asyncloader/getprogress.md
Normal file
24
docs/api/resources/asyncloader/getprogress.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# AsyncLoader::GetProgress
|
||||
|
||||
```cpp
|
||||
float GetProgress() const
|
||||
```
|
||||
|
||||
获取整体加载进度。返回已完成加载数与总请求数的比值，范围 0.0f ~ 1.0f。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 加载进度（0.0f ~ 1.0f）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
float progress = AsyncLoader::Get().GetProgress();
|
||||
printf("Loading: %.1f%%\n", progress * 100.0f);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [AsyncLoader 总览](asyncloader.md) - 返回类总览
|
||||
35
docs/api/resources/asyncloader/submit.md
Normal file
35
docs/api/resources/asyncloader/submit.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# AsyncLoader::Submit
|
||||
|
||||
```cpp
|
||||
void Submit(const Containers::String& path, ResourceType type,
|
||||
std::function<void(LoadResult)> callback)
|
||||
void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings,
|
||||
std::function<void(LoadResult)> callback)
|
||||
```
|
||||
|
||||
提交异步加载请求。将请求加入待处理队列，由工作线程在后台执行加载。
|
||||
|
||||
**参数：**
|
||||
- `path` - 资源路径
|
||||
- `type` - 资源类型
|
||||
- `settings` - 导入设置（可为 nullptr）
|
||||
- `callback` - 加载完成回调
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
|
||||
[](LoadResult result) {
|
||||
if (result.success) {
|
||||
ResourceHandle<Texture> tex(result.resource);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [AsyncLoader 总览](asyncloader.md) - 返回类总览
|
||||
27
docs/api/resources/asyncloader/update.md
Normal file
27
docs/api/resources/asyncloader/update.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# AsyncLoader::Update
|
||||
|
||||
```cpp
|
||||
void Update()
|
||||
```
|
||||
|
||||
更新函数，在主线程调用。处理完成的加载请求，将结果从完成队列取出并在主线程执行回调。必须在主线程调用以确保线程安全。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)，n 为完成队列中的请求数
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
// 在主循环中调用
|
||||
while (running) {
|
||||
AsyncLoader::Get().Update(); // 分发完成的加载回调
|
||||
RenderFrame();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [AsyncLoader 总览](asyncloader.md) - 返回类总览
|
||||
139
docs/api/resources/audioclip/audioclip.md
Normal file
139
docs/api/resources/audioclip/audioclip.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# AudioClip
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 音频片段资源类，管理音频样本数据、格式信息和播放参数。
|
||||
|
||||
## 概述
|
||||
|
||||
`AudioClip` 是 XCEngine 中的音频资源类，继承自 `IResource`。它管理音频的原始样本数据、采样率、通道数、位深度、时长、格式类型和播放参数。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/AudioClip.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### AudioFormat
|
||||
|
||||
音频格式枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Unknown` | 未知格式 |
|
||||
| `WAV` | WAV 格式 |
|
||||
| `OGG` | OGG Vorbis 格式 |
|
||||
| `MP3` | MP3 格式 |
|
||||
| `FLAC` | FLAC 无损格式 |
|
||||
|
||||
### AudioType
|
||||
|
||||
音频类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `SoundEffect` | 音效 |
|
||||
| `Music` | 音乐 |
|
||||
| `Voice` | 语音 |
|
||||
| `Ambient` | 环境音 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourceType GetType() const` | 返回 `ResourceType::AudioClip` |
|
||||
| `const Containers::String& GetName() const` | 获取音频名称 |
|
||||
| `const Containers::String& GetPath() const` | 获取音频路径 |
|
||||
| `ResourceGUID GetGUID() const` | 获取全局唯一标识符 |
|
||||
| `bool IsValid() const` | 检查音频是否有效 |
|
||||
| `size_t GetMemorySize() const` | 获取内存大小 |
|
||||
| `void Release()` | 释放音频引用 |
|
||||
|
||||
### 音频数据
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetAudioData(const Containers::Array<Core::uint8>& data)` | 设置音频数据（根据采样率、通道数、位深度自动计算时长） |
|
||||
| `const Containers::Array<Core::uint8>& GetAudioData() const` | 获取音频数据指针 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**:
|
||||
- `AudioLoader::Load()` 加载 WAV 文件时仅设置格式，不解析 WAV 头信息来设置采样率、通道数和位深度。这些字段需要手动设置或通过 `SetAudioData()` 的自动计算（需先设置 `m_sampleRate`、`m_channels`、`m_bitsPerSample`）。
|
||||
- `AudioLoader::ParseWAVData()` 为 stub，始终返回 true。
|
||||
- `AudioLoader::DetectAudioFormat()` 不检测 AIFF/AIF 格式的文件头，仅依赖扩展名判断。
|
||||
|
||||
### 音频参数
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetSampleRate(Core::uint32 rate)` | 设置采样率（Hz） |
|
||||
| `Core::uint32 GetSampleRate() const` | 获取采样率 |
|
||||
| `void SetChannels(Core::uint32 channels)` | 设置通道数（1=单声道, 2=立体声） |
|
||||
| `Core::uint32 GetChannels() const` | 获取通道数 |
|
||||
| `void SetBitsPerSample(Core::uint32 bits)` | 设置位深度（8/16/24/32） |
|
||||
| `Core::uint32 GetBitsPerSample() const` | 获取位深度 |
|
||||
| `void SetDuration(float seconds)` | 设置时长（秒） |
|
||||
| `float GetDuration() const` | 获取时长（秒） |
|
||||
|
||||
### 格式与类型
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetAudioFormat(AudioFormat format)` | 设置音频格式 |
|
||||
| `AudioFormat GetAudioFormat() const` | 获取音频格式 |
|
||||
| `void SetAudioType(AudioType type)` | 设置音频类型 |
|
||||
| `AudioType GetAudioType() const` | 获取音频类型 |
|
||||
|
||||
### 3D 和循环
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetIs3D(bool is3D)` | 设置是否为 3D 音频 |
|
||||
| `bool Is3D() const` | 检查是否为 3D 音频 |
|
||||
| `void SetLoop(bool loop)` | 设置是否循环播放 |
|
||||
| `bool IsLoop() const` | 检查是否循环播放 |
|
||||
|
||||
### RHI 资源
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `class IRHIAudioBuffer* GetRHIResource() const` | 获取 RHI 音频缓冲区 |
|
||||
| `void SetRHIResource(class IRHIAudioBuffer* resource)` | 设置 RHI 音频缓冲区 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载音频
|
||||
ResourceHandle<AudioClip> sfx = ResourceManager::Get().Load<AudioClip>("sounds/explosion.wav");
|
||||
ResourceHandle<AudioClip> music = ResourceManager::Get().Load<AudioClip>("music/background.ogg");
|
||||
|
||||
// 设置参数
|
||||
sfx->SetAudioType(AudioType::SoundEffect);
|
||||
sfx->SetSampleRate(44100);
|
||||
sfx->SetChannels(2);
|
||||
sfx->SetBitsPerSample(16);
|
||||
sfx->SetDuration(1.5f);
|
||||
sfx->SetLoop(false);
|
||||
|
||||
// 3D 音频
|
||||
sfx->SetIs3D(false);
|
||||
music->SetIs3D(false);
|
||||
|
||||
// 获取信息
|
||||
uint32_t sampleRate = sfx->GetSampleRate();
|
||||
float duration = sfx->GetDuration();
|
||||
bool loop = sfx->IsLoop();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
29
docs/api/resources/audioclip/setaudiodata.md
Normal file
29
docs/api/resources/audioclip/setaudiodata.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# AudioClip::SetAudioData
|
||||
|
||||
```cpp
|
||||
void SetAudioData(const Containers::Array<Core::uint8>& data)
|
||||
```
|
||||
|
||||
设置音频原始样本数据。
|
||||
|
||||
**参数：**
|
||||
- `data` - 音频数据字节数组
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
auto wavData = ResourceFileSystem::Get().ReadResource("sounds/explosion.wav");
|
||||
AudioClip* clip = new AudioClip();
|
||||
clip->SetAudioData(wavData);
|
||||
clip->SetSampleRate(44100);
|
||||
clip->SetChannels(2);
|
||||
clip->SetBitsPerSample(16);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [AudioClip 总览](audioclip.md) - 返回类总览
|
||||
27
docs/api/resources/dependencygraph/adddependency.md
Normal file
27
docs/api/resources/dependencygraph/adddependency.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceDependencyGraph::AddDependency
|
||||
|
||||
```cpp
|
||||
void AddDependency(ResourceGUID owner, ResourceGUID dependency)
|
||||
```
|
||||
|
||||
添加资源依赖关系。表示 `owner` 资源依赖 `dependency` 资源。依赖关系是单向的。
|
||||
|
||||
**参数：**
|
||||
- `owner` - 拥有依赖关系的主体资源
|
||||
- `dependency` - 被依赖的资源
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
// Material 依赖 Texture 和 Shader
|
||||
graph.AddDependency(materialGuid, textureGuid);
|
||||
graph.AddDependency(materialGuid, shaderGuid);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
|
||||
27
docs/api/resources/dependencygraph/addnode.md
Normal file
27
docs/api/resources/dependencygraph/addnode.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceDependencyGraph::AddNode
|
||||
|
||||
```cpp
|
||||
void AddNode(ResourceGUID guid, ResourceType type)
|
||||
```
|
||||
|
||||
向依赖图中添加一个新节点。如果节点已存在则忽略。
|
||||
|
||||
**参数：**
|
||||
- `guid` - 资源的全局唯一标识符
|
||||
- `type` - 资源类型
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceDependencyGraph graph;
|
||||
graph.AddNode(textureGuid, ResourceType::Texture);
|
||||
graph.AddNode(materialGuid, ResourceType::Material);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
|
||||
88
docs/api/resources/dependencygraph/dependencygraph.md
Normal file
88
docs/api/resources/dependencygraph/dependencygraph.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# ResourceDependencyGraph
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 资源依赖图管理器，负责跟踪资源之间的依赖关系、引用计数和拓扑排序。
|
||||
|
||||
## 概述
|
||||
|
||||
`ResourceDependencyGraph` 维护了所有资源之间的依赖关系图。它支持添加/移除依赖节点、查询依赖关系、循环依赖检测、拓扑排序（用于正确的加载/卸载顺序）等功能。
|
||||
|
||||
## DependencyNode 结构体
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `guid` | `ResourceGUID` | 资源全局唯一标识符 |
|
||||
| `type` | `ResourceType` | 资源类型 |
|
||||
| `dependencies` | `Containers::Array<ResourceGUID>` | 此资源依赖的其他资源 |
|
||||
| `dependents` | `Containers::Array<ResourceGUID>` | 依赖此资源的其他资源 |
|
||||
| `refCount` | `Core::uint32` | 引用计数 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void AddNode(ResourceGUID guid, ResourceType type)` | 添加依赖节点 |
|
||||
| `void RemoveNode(ResourceGUID guid)` | 移除依赖节点 |
|
||||
| `bool HasNode(ResourceGUID guid) const` | 检查节点是否存在 |
|
||||
| `void AddDependency(ResourceGUID owner, ResourceGUID dependency)` | 添加依赖关系（A 依赖 B） |
|
||||
| `void RemoveDependency(ResourceGUID owner, ResourceGUID dependency)` | 移除依赖关系 |
|
||||
| `Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const` | 获取指定资源的直接依赖列表 |
|
||||
| `Containers::Array<ResourceGUID> GetDependents(ResourceGUID guid) const` | 获取依赖指定资源的所有资源列表 |
|
||||
| `Containers::Array<ResourceGUID> GetAllDependencies(ResourceGUID guid) const` | 获取所有递归依赖（包括传递依赖） |
|
||||
| `void IncrementRefCount(ResourceGUID guid)` | 增加引用计数 |
|
||||
| `void DecrementRefCount(ResourceGUID guid)` | 减少引用计数 |
|
||||
| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 |
|
||||
| `bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const` | 检测是否存在循环依赖 |
|
||||
| `Containers::Array<ResourceGUID> TopologicalSort() const` | 拓扑排序（当前返回空数组 - stub） |
|
||||
| `bool Unload(ResourceGUID guid)` | 安全卸载（考虑依赖关系） |
|
||||
| `void Clear()` | 清空所有节点和依赖关系 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `TopologicalSort()` 当前为 stub，返回空数组。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
ResourceDependencyGraph graph;
|
||||
|
||||
// 添加节点
|
||||
graph.AddNode(textureGuid, ResourceType::Texture);
|
||||
graph.AddNode(materialGuid, ResourceType::Material);
|
||||
graph.AddNode(shaderGuid, ResourceType::Shader);
|
||||
|
||||
// 设置依赖关系：Material 依赖 Texture 和 Shader
|
||||
graph.AddDependency(materialGuid, textureGuid);
|
||||
graph.AddDependency(materialGuid, shaderGuid);
|
||||
|
||||
// 查询依赖
|
||||
auto deps = graph.GetDependencies(materialGuid);
|
||||
// deps 包含 textureGuid 和 shaderGuid
|
||||
|
||||
// 查询被依赖者
|
||||
auto dependents = graph.GetDependents(textureGuid);
|
||||
// dependents 包含 materialGuid
|
||||
|
||||
// 拓扑排序（正确的加载顺序）
|
||||
auto loadOrder = graph.TopologicalSort();
|
||||
// loadOrder 保证依赖在目标之前加载
|
||||
|
||||
// 循环依赖检测
|
||||
Containers::Array<ResourceGUID> cycle;
|
||||
if (graph.HasCircularDependency(guid, cycle)) {
|
||||
printf("Circular dependency detected!");
|
||||
}
|
||||
|
||||
// 引用计数
|
||||
graph.IncrementRefCount(guid);
|
||||
graph.DecrementRefCount(guid);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
25
docs/api/resources/dependencygraph/getdependencies.md
Normal file
25
docs/api/resources/dependencygraph/getdependencies.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# ResourceDependencyGraph::GetDependencies
|
||||
|
||||
```cpp
|
||||
Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const
|
||||
```
|
||||
|
||||
获取指定资源直接依赖的所有资源列表。不包含传递依赖。
|
||||
|
||||
**参数：**
|
||||
- `guid` - 资源全局唯一标识符
|
||||
|
||||
**返回：** 直接依赖的 GUID 数组
|
||||
|
||||
**复杂度：** O(k)，k 为直接依赖数量
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
auto deps = graph.GetDependencies(materialGuid);
|
||||
// 返回 Material 直接依赖的资源（Texture、Shader 等）
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
|
||||
31
docs/api/resources/dependencygraph/hascirculardependency.md
Normal file
31
docs/api/resources/dependencygraph/hascirculardependency.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# ResourceDependencyGraph::HasCircularDependency
|
||||
|
||||
```cpp
|
||||
bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const
|
||||
```
|
||||
|
||||
检测是否存在以指定节点为起点的循环依赖。使用 DFS 遍历依赖图，检测回路。
|
||||
|
||||
**参数：**
|
||||
- `guid` - 起始节点
|
||||
- `outCycle` - 输出参数，检测到的循环路径（包含形成环的节点 GUID）
|
||||
|
||||
**返回：** 如果存在循环依赖则返回 true，否则返回 false
|
||||
|
||||
**复杂度：** O(n + e)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Containers::Array<ResourceGUID> cycle;
|
||||
if (graph.HasCircularDependency(guid, cycle)) {
|
||||
printf("Circular dependency detected: ");
|
||||
for (const auto& g : cycle) {
|
||||
printf("%llu ", g.value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
|
||||
28
docs/api/resources/dependencygraph/topologicalsort.md
Normal file
28
docs/api/resources/dependencygraph/topologicalsort.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# ResourceDependencyGraph::TopologicalSort
|
||||
|
||||
```cpp
|
||||
Containers::Array<ResourceGUID> TopologicalSort() const
|
||||
```
|
||||
|
||||
拓扑排序。按依赖顺序返回所有节点，确保被依赖的资源排在依赖者之前。用于确定正确的加载和卸载顺序。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 按依赖顺序排序的 GUID 数组
|
||||
|
||||
**复杂度：** O(n + e)，n 为节点数，e 为边数
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
auto loadOrder = graph.TopologicalSort();
|
||||
// loadOrder[0] 是最底层依赖（如 Texture）
|
||||
// loadOrder[last] 是最顶层资源（如 Material）
|
||||
for (const auto& guid : loadOrder) {
|
||||
ResourceManager::Get().Load(guid);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
|
||||
84
docs/api/resources/filearchive/filearchive.md
Normal file
84
docs/api/resources/filearchive/filearchive.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# FileArchive
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (extends IArchive)
|
||||
|
||||
**描述**: 文件归档封装类，用于读取归档包（如 .pak、.zip）中的资源文件。
|
||||
|
||||
## 概述
|
||||
|
||||
`FileArchive` 实现了 `IArchive` 接口，提供从单个归档包文件中读取资源的功能。它维护已打开归档的路径和有效性状态。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/FileArchive.h>
|
||||
```
|
||||
|
||||
## 继承关系
|
||||
|
||||
```
|
||||
IArchive
|
||||
└── FileArchive
|
||||
```
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造与析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `FileArchive()` | 默认构造 |
|
||||
| `~FileArchive()` | 析构函数，关闭归档 |
|
||||
|
||||
### IArchive 接口实现
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Open(const Containers::String& path) override` | 打开归档文件 |
|
||||
| `void Close() override` | 关闭归档文件 |
|
||||
| `bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override` | 从归档中读取文件数据 |
|
||||
| `size_t GetSize(const Containers::String& fileName) const override` | 获取归档内文件大小 |
|
||||
| `bool Exists(const Containers::String& fileName) const override` | 检查文件是否存在于归档中 |
|
||||
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const override` | 枚举归档内匹配的文件（当前为 stub） |
|
||||
| `bool IsValid() const override` | 检查归档是否有效 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `Enumerate()` 当前为 stub，仅清空输出数组。
|
||||
|
||||
### 访问器
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `const Containers::String& GetPath() const` | 获取归档文件路径 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
FileArchive archive;
|
||||
if (archive.Open("data/resources.pak")) {
|
||||
// 检查文件是否存在
|
||||
if (archive.Exists("textures/player.png")) {
|
||||
// 获取文件大小
|
||||
size_t size = archive.GetSize("textures/player.png");
|
||||
|
||||
// 读取文件内容
|
||||
Containers::Array<Core::uint8> buffer(size);
|
||||
archive.Read("textures/player.png", buffer.Data(), size, 0);
|
||||
}
|
||||
|
||||
// 枚举文件
|
||||
Containers::Array<Containers::String> files;
|
||||
archive.Enumerate("textures/*.png", files);
|
||||
|
||||
archive.Close();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IArchive](../filesystem/filesystem.md) - 归档接口
|
||||
- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
26
docs/api/resources/filesystem/exists.md
Normal file
26
docs/api/resources/filesystem/exists.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# ResourceFileSystem::Exists
|
||||
|
||||
```cpp
|
||||
bool Exists(const Containers::String& relativePath) const
|
||||
```
|
||||
|
||||
检查资源文件是否存在。优先在归档包中查找，其次在目录中查找。
|
||||
|
||||
**参数：**
|
||||
- `relativePath` - 资源相对路径
|
||||
|
||||
**返回：** 如果存在则返回 true
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
if (ResourceFileSystem::Get().Exists("shaders/default.vert")) {
|
||||
// 文件存在...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceFileSystem 总览](filesystem.md) - 返回类总览
|
||||
104
docs/api/resources/filesystem/filesystem.md
Normal file
104
docs/api/resources/filesystem/filesystem.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# ResourceFileSystem
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 资源文件系统，负责资源文件的查找、读取和虚拟文件系统（支持目录和归档包）管理。
|
||||
|
||||
## 概述
|
||||
|
||||
`ResourceFileSystem` 实现了虚拟资源文件系统，支持从多个目录和归档包（如 `.zip`、`.pak`）中查找和读取资源。它通过 `IArchive` 接口支持不同的归档格式，并提供资源信息缓存。
|
||||
|
||||
## 单例访问
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `static ResourceFileSystem& Get()` | 获取单例实例 |
|
||||
|
||||
## IArchive 接口
|
||||
|
||||
抽象归档接口，用于封装单个归档包或目录的读取操作。
|
||||
|
||||
### 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual bool Open(const Containers::String& path)` | 打开归档 |
|
||||
| `virtual void Close()` | 关闭归档 |
|
||||
| `virtual bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const` | 从归档中读取文件 |
|
||||
| `virtual size_t GetSize(const Containers::String& fileName) const` | 获取文件大小 |
|
||||
| `virtual bool Exists(const Containers::String& fileName) const` | 检查文件是否存在 |
|
||||
| `virtual void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举匹配的文件 |
|
||||
| `virtual bool IsValid() const` | 是否有效 |
|
||||
|
||||
## ResourceInfo 结构体
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `path` | `Containers::String` | 资源相对路径 |
|
||||
| `size` | `size_t` | 文件大小（字节） |
|
||||
| `modifiedTime` | `Core::uint64` | 修改时间戳 |
|
||||
| `inArchive` | `bool` | 是否在归档包中 |
|
||||
| `archivePath` | `Containers::String` | 所属归档路径 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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<Core::uint8> ReadResource(const Containers::String& relativePath) const` | 读取资源文件内容（字节数组） |
|
||||
| `bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const` | 获取资源信息（部分字段可能未填充） |
|
||||
| `void EnumerateResources(const Containers::String& pattern, Containers::Array<ResourceInfo>& outResources) const` | 枚举匹配的资源（当前为 stub，仅清空输出） |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: 当前 `GetResourceInfo()` 不填充 `modifiedTime` 字段，`EnumerateResources()` 为 stub 实现。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 初始化资源文件系统
|
||||
ResourceFileSystem::Get().Initialize("resources/");
|
||||
|
||||
// 添加归档包（优先于目录）
|
||||
ResourceFileSystem::Get().AddArchive("data/resources.pak");
|
||||
|
||||
// 添加额外资源目录
|
||||
ResourceFileSystem::Get().AddDirectory("user_content/");
|
||||
|
||||
// 检查资源是否存在
|
||||
if (ResourceFileSystem::Get().Exists("textures/player.png")) {
|
||||
// 读取资源
|
||||
auto data = ResourceFileSystem::Get().ReadResource("textures/player.png");
|
||||
// 使用数据...
|
||||
}
|
||||
|
||||
// 获取资源信息
|
||||
ResourceInfo info;
|
||||
if (ResourceFileSystem::Get().GetResourceInfo("shaders/default.vert", info)) {
|
||||
printf("Size: %zu, InArchive: %s\n", info.size, info.inArchive ? "yes" : "no");
|
||||
}
|
||||
|
||||
// 枚举资源
|
||||
Containers::Array<ResourceInfo> textures;
|
||||
ResourceFileSystem::Get().EnumerateResources("textures/*.png", textures);
|
||||
for (const auto& tex : textures) {
|
||||
printf("Found: %s\n", tex.path.CStr());
|
||||
}
|
||||
|
||||
// 关闭
|
||||
ResourceFileSystem::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [IResourceLoader](../iloader/iloader.md) - 资源加载器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
24
docs/api/resources/filesystem/initialize.md
Normal file
24
docs/api/resources/filesystem/initialize.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# ResourceFileSystem::Initialize
|
||||
|
||||
```cpp
|
||||
void Initialize(const Containers::String& rootPath)
|
||||
```
|
||||
|
||||
初始化资源文件系统。设置资源根目录，准备虚拟文件系统。
|
||||
|
||||
**参数：**
|
||||
- `rootPath` - 资源根目录路径
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceFileSystem::Get().Initialize("resources/");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceFileSystem 总览](filesystem.md) - 返回类总览
|
||||
27
docs/api/resources/filesystem/readresource.md
Normal file
27
docs/api/resources/filesystem/readresource.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceFileSystem::ReadResource
|
||||
|
||||
```cpp
|
||||
Containers::Array<Core::uint8> ReadResource(const Containers::String& relativePath) const
|
||||
```
|
||||
|
||||
读取资源文件内容。优先从归档包中读取，其次从目录中查找。
|
||||
|
||||
**参数：**
|
||||
- `relativePath` - 资源相对路径
|
||||
|
||||
**返回：** 文件内容的字节数组，读取失败返回空数组
|
||||
|
||||
**复杂度：** O(n)，n 为文件大小
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
auto data = ResourceFileSystem::Get().ReadResource("textures/player.png");
|
||||
if (!data.Empty()) {
|
||||
// 使用数据...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceFileSystem 总览](filesystem.md) - 返回类总览
|
||||
31
docs/api/resources/iloader/canload.md
Normal file
31
docs/api/resources/iloader/canload.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# IResourceLoader::CanLoad
|
||||
|
||||
```cpp
|
||||
bool CanLoad(const Containers::String& path) const
|
||||
```
|
||||
|
||||
检查此加载器是否能加载指定路径的资源。通过比对路径扩展名与支持列表判断。
|
||||
|
||||
**参数：**
|
||||
- `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 总览](iloader.md) - 返回类总览
|
||||
25
docs/api/resources/iloader/getdefaultsettings.md
Normal file
25
docs/api/resources/iloader/getdefaultsettings.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# IResourceLoader::GetDefaultSettings
|
||||
|
||||
```cpp
|
||||
ImportSettings* GetDefaultSettings() const = 0
|
||||
```
|
||||
|
||||
获取此加载器的默认导入设置。纯虚方法，子类返回其特有的默认设置实例。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 默认 `ImportSettings` 指针，调用者不持有所有权
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ImportSettings* TextureLoader::GetDefaultSettings() const {
|
||||
return new TextureImportSettings();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResourceLoader 总览](iloader.md) - 返回类总览
|
||||
25
docs/api/resources/iloader/getsupportedextensions.md
Normal file
25
docs/api/resources/iloader/getsupportedextensions.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# IResourceLoader::GetSupportedExtensions
|
||||
|
||||
```cpp
|
||||
Containers::Array<Containers::String> GetSupportedExtensions() const
|
||||
```
|
||||
|
||||
获取此加载器支持的文件扩展名列表。用于 `CanLoad` 判断和编辑器中资源类型识别。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 支持的扩展名数组（如 `{".png", ".jpg", ".bmp"}`）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Containers::Array<Containers::String> TextureLoader::GetSupportedExtensions() const {
|
||||
return {".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dds"};
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResourceLoader 总览](iloader.md) - 返回类总览
|
||||
119
docs/api/resources/iloader/iloader.md
Normal file
119
docs/api/resources/iloader/iloader.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# IResourceLoader
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (abstract)
|
||||
|
||||
**描述**: 资源加载器抽象接口，定义了资源加载的标准协议。每个资源类型需要提供对应的加载器实现。
|
||||
|
||||
## 概述
|
||||
|
||||
`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; }
|
||||
};
|
||||
```
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 资源信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourceType GetResourceType() const` | 获取此加载器支持的资源类型 |
|
||||
| `Containers::Array<Containers::String> GetSupportedExtensions() const` | 获取支持的文件扩展名列表 |
|
||||
| `bool CanLoad(const Containers::String& path) const` | 检查此加载器是否能加载指定路径 |
|
||||
| `ImportSettings* GetDefaultSettings() const` | 获取默认导入设置 |
|
||||
|
||||
### 同步加载
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)` | 同步加载资源 |
|
||||
|
||||
### 异步加载
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function<void(LoadResult)> callback)` | 异步加载资源（内部默认实现调用同步 Load） |
|
||||
|
||||
### 辅助方法（受保护）
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `static Containers::Array<Core::uint8> 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<Containers::String> 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) - 返回模块总览
|
||||
42
docs/api/resources/iloader/load.md
Normal file
42
docs/api/resources/iloader/load.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# IResourceLoader::Load
|
||||
|
||||
```cpp
|
||||
LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr)
|
||||
```
|
||||
|
||||
同步加载资源。纯虚方法，由具体加载器实现。从指定路径读取文件数据，解析为对应类型的资源对象。
|
||||
|
||||
**参数：**
|
||||
- `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 总览](iloader.md) - 返回类总览
|
||||
34
docs/api/resources/iloader/loadasync.md
Normal file
34
docs/api/resources/iloader/loadasync.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# IResourceLoader::LoadAsync
|
||||
|
||||
```cpp
|
||||
void LoadAsync(const Containers::String& path, const ImportSettings* settings,
|
||||
std::function<void(LoadResult)> callback)
|
||||
```
|
||||
|
||||
异步加载资源。默认实现直接调用同步 `Load` 方法并在当前线程执行回调。子类可重写以实现真正的多线程异步加载。
|
||||
|
||||
**参数：**
|
||||
- `path` - 资源路径
|
||||
- `settings` - 导入设置（可为 nullptr）
|
||||
- `callback` - 加载完成回调函数
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
void AsyncTextureLoader::LoadAsync(const Containers::String& path,
|
||||
const ImportSettings* settings,
|
||||
std::function<void(LoadResult)> callback) {
|
||||
std::thread([this, path, settings, callback]() {
|
||||
LoadResult result = Load(path, settings);
|
||||
callback(result); // 回调可在工作线程执行
|
||||
}).detach();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResourceLoader 总览](iloader.md) - 返回类总览
|
||||
173
docs/api/resources/importsettings/importsettings.md
Normal file
173
docs/api/resources/importsettings/importsettings.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# ImportSettings
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (abstract)
|
||||
|
||||
**描述**: 资源导入设置抽象基类，定义资源导入时的配置选项接口。
|
||||
|
||||
## 概述
|
||||
|
||||
`ImportSettings` 是所有资源导入设置的抽象基类。它提供了克隆和 JSON 序列化接口，允许不同资源类型定义各自的导入选项。引擎内置了两个具体实现：`TextureImportSettings` 和 `MeshImportSettings`。
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual Core::UniqueRef<ImportSettings> Clone() const = 0` | 克隆一份设置 |
|
||||
| `virtual bool LoadFromJSON(const Containers::String& json)` | 从 JSON 加载设置（当前返回 false - stub） |
|
||||
| `virtual Containers::String SaveToJSON() const` | 保存为 JSON 字符串（当前返回空字符串 - stub） |
|
||||
|
||||
---
|
||||
|
||||
## TextureImportSettings
|
||||
|
||||
纹理导入设置，继承自 `ImportSettings`。
|
||||
|
||||
**头文件**: `XCEngine/Resources/TextureImportSettings.h`
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。
|
||||
|
||||
### 枚举类型
|
||||
|
||||
#### MipmapFilter
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Box` | Box 滤波器 |
|
||||
| `Kaiser` | Kaiser 滤波器 |
|
||||
|
||||
#### CompressionQuality
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Low` | 低质量 |
|
||||
| `Medium` | 中等质量 |
|
||||
| `High` | 高质量 |
|
||||
| `Ultra` | 超高质量 |
|
||||
|
||||
### 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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` | 获取法线贴图强度 |
|
||||
|
||||
---
|
||||
|
||||
## MeshImportSettings
|
||||
|
||||
网格导入设置，继承自 `ImportSettings`。
|
||||
|
||||
**头文件**: `XCEngine/Resources/MeshImportSettings.h`
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `LoadFromJSON()` 和 `SaveToJSON()` 当前为 stub 实现。
|
||||
|
||||
### MeshImportFlags
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `None` | 无特殊标志 |
|
||||
| `FlipUVs` | 翻转 UV 坐标 |
|
||||
| `FlipWindingOrder` | 翻转绕序 |
|
||||
| `GenerateNormals` | 生成法线 |
|
||||
| `GenerateTangents` | 生成切线 |
|
||||
| `OptimizeMesh` | 优化网格 |
|
||||
| `ImportSkinning` | 导入骨骼蒙皮 |
|
||||
| `ImportAnimations` | 导入动画 |
|
||||
| `ImportMaterials` | 导入材质 |
|
||||
| `ImportCameras` | 导入相机 |
|
||||
| `ImportLights` | 导入灯光 |
|
||||
|
||||
支持位运算组合（`operator|`、`operator&`、`operator~`）。
|
||||
|
||||
### 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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` | 获取阈值 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/TextureImportSettings.h>
|
||||
#include <XCEngine/Resources/MeshImportSettings.h>
|
||||
|
||||
// 纹理导入设置
|
||||
TextureImportSettings texSettings;
|
||||
texSettings.SetTextureType(TextureType::Texture2D);
|
||||
texSettings.SetGenerateMipmaps(true);
|
||||
texSettings.SetSRGB(true);
|
||||
texSettings.SetCompressionQuality(CompressionQuality::High);
|
||||
texSettings.SetMaxAnisotropy(16);
|
||||
|
||||
// 加载设置
|
||||
texSettings.LoadFromJSON(R"({"sRGB":true,"maxAnisotropy":8})");
|
||||
|
||||
// 保存设置
|
||||
Containers::String json = texSettings.SaveToJSON();
|
||||
|
||||
// 网格导入设置
|
||||
MeshImportSettings meshSettings;
|
||||
meshSettings.SetImportFlags(MeshImportFlags::FlipUVs | MeshImportFlags::GenerateNormals);
|
||||
meshSettings.SetScale(1.0f);
|
||||
meshSettings.SetAxisConversion(true);
|
||||
|
||||
// 使用设置加载资源
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png", &texSettings);
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx", &meshSettings);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResourceLoader](../iloader/iloader.md) - 资源加载器
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
34
docs/api/resources/iresource/initialize.md
Normal file
34
docs/api/resources/iresource/initialize.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# IResource::Initialize
|
||||
|
||||
```cpp
|
||||
void Initialize(const ConstructParams& params)
|
||||
```
|
||||
|
||||
使用构造参数初始化资源。将参数中的名称、路径、GUID 和内存大小写入对应成员变量，并将资源标记为有效状态。
|
||||
|
||||
**参数：**
|
||||
- `params` - 包含资源名称、路径、GUID 和内存大小的构造参数结构体
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
class MyResource : public IResource {
|
||||
public:
|
||||
MyResource() {
|
||||
ConstructParams params;
|
||||
params.name = "player_texture";
|
||||
params.path = "textures/player.png";
|
||||
params.guid = ResourceGUID::Generate(params.path);
|
||||
params.memorySize = 1024 * 1024; // 1MB
|
||||
Initialize(params);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource 总览](iresource.md) - 返回类总览
|
||||
57
docs/api/resources/iresource/iresource.md
Normal file
57
docs/api/resources/iresource/iresource.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# IResource
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (abstract)
|
||||
|
||||
**描述**: 资源基类接口，所有具体资源类型（Texture、Mesh、Material 等）都必须继承自此类。
|
||||
|
||||
## 概述
|
||||
|
||||
`IResource` 是 XCEngine 资源管理系统的核心抽象基类。它定义了所有资源共有的基本属性和行为，包括资源类型、名称、路径、GUID、内存大小和有效性状态。
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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()` | 将资源标记为无效 |
|
||||
|
||||
### 构造参数
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `m_name` | `Containers::String` | 资源名称 |
|
||||
| `m_path` | `Containers::String` | 资源路径 |
|
||||
| `m_guid` | `ResourceGUID` | 全局唯一标识符 |
|
||||
| `m_isValid` | `bool` | 资源是否有效 |
|
||||
| `m_memorySize` | `size_t` | 内存占用大小 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
class MyResource : public IResource {
|
||||
public:
|
||||
ResourceType GetType() const override { return ResourceType::Custom; }
|
||||
const Containers::String& GetName() const override { return m_name; }
|
||||
const Containers::String& GetPath() const override { return m_path; }
|
||||
ResourceGUID GetGUID() const override { return m_guid; }
|
||||
bool IsValid() const override { return m_isValid; }
|
||||
size_t GetMemorySize() const override { return m_memorySize; }
|
||||
void Release() override { /* 释放逻辑 */ }
|
||||
};
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
33
docs/api/resources/iresource/release.md
Normal file
33
docs/api/resources/iresource/release.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# IResource::Release
|
||||
|
||||
```cpp
|
||||
virtual void Release() = 0
|
||||
```
|
||||
|
||||
释放资源引用。纯虚方法，由具体资源类实现，用于执行资源特有的清理逻辑（如释放 GPU 资源、释放内存等）。在 `ResourceHandle` 析构或调用 `Reset()` 时会自动触发。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1) 或 O(n)，取决于具体实现
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
class Texture : public IResource {
|
||||
public:
|
||||
void Release() override {
|
||||
if (m_rhiTexture) {
|
||||
m_rhiTexture->Release();
|
||||
m_rhiTexture = nullptr;
|
||||
}
|
||||
m_pixelData.Clear();
|
||||
m_isValid = false;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource 总览](iresource.md) - 返回类总览
|
||||
28
docs/api/resources/iresource/setinvalid.md
Normal file
28
docs/api/resources/iresource/setinvalid.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# IResource::SetInvalid
|
||||
|
||||
```cpp
|
||||
void SetInvalid()
|
||||
```
|
||||
|
||||
将资源标记为无效状态。此方法用于在加载失败或资源损坏时将 `m_isValid` 设为 false，之后调用 `IsValid()` 将返回 false。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
void LoadFailed() {
|
||||
texture->SetInvalid();
|
||||
if (!texture->IsValid()) {
|
||||
// 处理资源无效情况
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource 总览](iresource.md) - 返回类总览
|
||||
151
docs/api/resources/material/material.md
Normal file
151
docs/api/resources/material/material.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Material
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 材质资源类，管理渲染所需的着色器和属性参数。
|
||||
|
||||
## 概述
|
||||
|
||||
`Material` 是 XCEngine 中的材质资源类，继承自 `IResource`。它管理材质关联的着色器和各种属性参数（浮点数、向量、纹理等），并支持将属性数据打包到常量缓冲区。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/Material.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### MaterialPropertyType
|
||||
|
||||
材质属性类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Float` | 单精度浮点数 |
|
||||
| `Float2` | 二维浮点向量 |
|
||||
| `Float3` | 三维浮点向量 |
|
||||
| `Float4` | 四维浮点向量 |
|
||||
| `Int` | 整数 |
|
||||
| `Int2` | 二维整数向量 |
|
||||
| `Int3` | 三维整数向量 |
|
||||
| `Int4` | 四维整数向量 |
|
||||
| `Bool` | 布尔值 |
|
||||
| `Texture` | 纹理资源 |
|
||||
| `Cubemap` | 立方体贴图资源 |
|
||||
|
||||
## 结构体
|
||||
|
||||
### MaterialProperty
|
||||
|
||||
材质属性结构体。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | `Containers::String` | 属性名称 |
|
||||
| `type` | `MaterialPropertyType` | 属性类型 |
|
||||
| `value` | `union` | 属性值（float/int/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()` | 释放材质引用 |
|
||||
|
||||
### 着色器管理
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetShader(const ResourceHandle<Shader>& shader)` | 设置材质着色器 |
|
||||
| `Shader* GetShader() const` | 获取材质着色器 |
|
||||
|
||||
### 属性设置
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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>& texture)` | 设置纹理属性 |
|
||||
|
||||
### 属性获取
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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<Texture> GetTexture(const Containers::String& name) const` | 获取纹理属性 |
|
||||
|
||||
### 常量缓冲区
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `const Containers::Array<Core::uint8>& GetConstantBufferData() const` | 获取常量缓冲区数据 |
|
||||
| `void UpdateConstantBuffer()` | 更新常量缓冲区数据 |
|
||||
|
||||
### 属性管理
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool HasProperty(const Containers::String& name) const` | 检查属性是否存在 |
|
||||
| `void RemoveProperty(const Containers::String& name)` | 移除属性 |
|
||||
| `void ClearAllProperties()` | 清空所有属性 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `MaterialLoader::ParseMaterialData()` 为 stub，始终返回 true。`MaterialLoader::Load()` 仅为示例实现，未解析材质属性。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载材质
|
||||
ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
|
||||
|
||||
// 设置着色器
|
||||
mat->SetShader(shaderHandle);
|
||||
|
||||
// 设置各种属性
|
||||
mat->SetFloat("roughness", 0.5f);
|
||||
mat->SetFloat3("albedo", Math::Vector3(1.0f, 0.8f, 0.6f));
|
||||
mat->SetTexture("albedoMap", albedoTex);
|
||||
mat->SetTexture("normalMap", normalTex);
|
||||
mat->SetInt("normalScale", 1);
|
||||
|
||||
// 获取属性
|
||||
float roughness = mat->GetFloat("roughness");
|
||||
Math::Vector3 albedo = mat->GetFloat3("albedo");
|
||||
|
||||
// 检查属性
|
||||
if (mat->HasProperty("metallic")) {
|
||||
float metallic = mat->GetFloat("metallic");
|
||||
}
|
||||
|
||||
// 更新常量缓冲区
|
||||
mat->UpdateConstantBuffer();
|
||||
auto cbData = mat->GetConstantBufferData();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [Shader](../shader/shader.md) - 着色器资源
|
||||
- [Texture](../texture/texture.md) - 纹理资源
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
27
docs/api/resources/material/setfloat.md
Normal file
27
docs/api/resources/material/setfloat.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 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) - 返回类总览
|
||||
26
docs/api/resources/material/setshader.md
Normal file
26
docs/api/resources/material/setshader.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Material::SetShader
|
||||
|
||||
```cpp
|
||||
void SetShader(const ResourceHandle<Shader>& shader)
|
||||
```
|
||||
|
||||
设置材质使用的着色器。
|
||||
|
||||
**参数：**
|
||||
- `shader` - 着色器资源句柄
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Shader> vs = ResourceManager::Get().Load<Shader>("shaders/vertex.glsl");
|
||||
ResourceHandle<Shader> fs = ResourceManager::Get().Load<Shader>("shaders/fragment.glsl");
|
||||
mat->SetShader(vs);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Material 总览](material.md) - 返回类总览
|
||||
28
docs/api/resources/material/settexture.md
Normal file
28
docs/api/resources/material/settexture.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Material::SetTexture
|
||||
|
||||
```cpp
|
||||
void SetTexture(const Containers::String& name, const ResourceHandle<Texture>& texture)
|
||||
```
|
||||
|
||||
设置材质纹理属性。
|
||||
|
||||
**参数：**
|
||||
- `name` - 属性名称
|
||||
- `texture` - 纹理资源句柄
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> albedoTex = ResourceManager::Get().Load<Texture>("textures/albedo.png");
|
||||
ResourceHandle<Texture> normalTex = ResourceManager::Get().Load<Texture>("textures/normal.png");
|
||||
mat->SetTexture("albedoMap", albedoTex);
|
||||
mat->SetTexture("normalMap", normalTex);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Material 总览](material.md) - 返回类总览
|
||||
26
docs/api/resources/material/updateconstantbuffer.md
Normal file
26
docs/api/resources/material/updateconstantbuffer.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 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) - 返回类总览
|
||||
30
docs/api/resources/mesh/addsection.md
Normal file
30
docs/api/resources/mesh/addsection.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# 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) - 返回类总览
|
||||
150
docs/api/resources/mesh/mesh.md
Normal file
150
docs/api/resources/mesh/mesh.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Mesh
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 网格资源类，管理 3D 模型的顶点数据、索引数据和网格分段信息。
|
||||
|
||||
## 概述
|
||||
|
||||
`Mesh` 是 XCEngine 中的网格资源类，继承自 `IResource`。它管理网格的顶点数据（位置、法线、UV、切线、颜色、骨骼权重等）、索引数据和网格分段（submesh）。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/Mesh.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### 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 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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()` | 释放网格引用 |
|
||||
|
||||
### 顶点数据
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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` | 获取顶点属性标志 |
|
||||
|
||||
### 索引数据
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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 位索引 |
|
||||
|
||||
### 网格分段
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void AddSection(const MeshSection& section)` | 添加网格分段 |
|
||||
| `const Containers::Array<MeshSection>& GetSections() const` | 获取所有分段 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载网格
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
|
||||
|
||||
// 手动设置顶点数据
|
||||
struct Vertex {
|
||||
float position[3];
|
||||
float normal[3];
|
||||
float uv[2];
|
||||
};
|
||||
|
||||
Containers::Array<Vertex> vertices;
|
||||
vertices.Resize(vertexCount);
|
||||
// ... 填充顶点数据 ...
|
||||
|
||||
mesh->SetVertexData(
|
||||
vertices.Data(),
|
||||
vertices.Size() * sizeof(Vertex),
|
||||
vertexCount,
|
||||
sizeof(Vertex),
|
||||
VertexAttribute::Position | VertexAttribute::Normal | VertexAttribute::UV0
|
||||
);
|
||||
|
||||
// 设置索引数据
|
||||
Containers::Array<uint32_t> indices;
|
||||
indices.Resize(indexCount);
|
||||
// ... 填充索引数据 ...
|
||||
|
||||
mesh->SetIndexData(
|
||||
indices.Data(),
|
||||
indices.Size() * sizeof(uint32_t),
|
||||
indexCount,
|
||||
true // 32 位索引
|
||||
);
|
||||
|
||||
// 添加分段（一个网格可能有多个材质）
|
||||
MeshSection section;
|
||||
section.baseVertex = 0;
|
||||
section.vertexCount = vertexCount;
|
||||
section.startIndex = 0;
|
||||
section.indexCount = indexCount;
|
||||
section.materialID = 0;
|
||||
mesh->AddSection(section);
|
||||
|
||||
// 访问数据
|
||||
uint32_t vCount = mesh->GetVertexCount();
|
||||
uint32_t iCount = mesh->GetIndexCount();
|
||||
auto sections = mesh->GetSections();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [Material](../material/material.md) - 材质资源
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
- **实现说明**: `MeshLoader::Load()` 仅为示例实现，不解析 FBX/OBJ 等格式的实际网格数据
|
||||
30
docs/api/resources/mesh/setindexdata.md
Normal file
30
docs/api/resources/mesh/setindexdata.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# 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<uint32_t> indices;
|
||||
// ... 填充索引数据 ...
|
||||
mesh->SetIndexData(indices.Data(), indices.Size() * sizeof(uint32_t),
|
||||
indices.Size(), true);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Mesh 总览](mesh.md) - 返回类总览
|
||||
37
docs/api/resources/mesh/setvertexdata.md
Normal file
37
docs/api/resources/mesh/setvertexdata.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# 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) - 返回类总览
|
||||
25
docs/api/resources/resourcecache/add.md
Normal file
25
docs/api/resources/resourcecache/add.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# ResourceCache::Add
|
||||
|
||||
```cpp
|
||||
void Add(ResourceGUID guid, IResource* resource)
|
||||
```
|
||||
|
||||
添加资源到缓存。将资源和 GUID 关联并记录内存大小、访问时间。线程安全。
|
||||
|
||||
**参数：**
|
||||
- `guid` - 资源全局唯一标识符
|
||||
- `resource` - 资源指针
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
cache.Add(guid, resource);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceCache 总览](resourcecache.md) - 返回类总览
|
||||
23
docs/api/resources/resourcecache/flush.md
Normal file
23
docs/api/resources/resourcecache/flush.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# ResourceCache::Flush
|
||||
|
||||
```cpp
|
||||
void Flush()
|
||||
```
|
||||
|
||||
清空缓存，释放所有资源。将所有缓存条目标记为待释放状态，调用每个资源的 `Release()` 方法。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
cache.Flush();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceCache 总览](resourcecache.md) - 返回类总览
|
||||
27
docs/api/resources/resourcecache/getlrulist.md
Normal file
27
docs/api/resources/resourcecache/getlrulist.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceCache::GetLRUList
|
||||
|
||||
```cpp
|
||||
Containers::Array<ResourceGUID> 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) - 返回类总览
|
||||
25
docs/api/resources/resourcecache/onmemorypressure.md
Normal file
25
docs/api/resources/resourcecache/onmemorypressure.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# ResourceCache::OnMemoryPressure
|
||||
|
||||
```cpp
|
||||
void OnMemoryPressure(size_t requiredBytes)
|
||||
```
|
||||
|
||||
内存压力回调。当系统内存紧张时调用此方法，从 LRU 列表头部开始驱逐资源，直到释放足够空间。
|
||||
|
||||
**参数：**
|
||||
- `requiredBytes` - 需要释放的字节数
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
// 需要 100MB 空间
|
||||
cache.OnMemoryPressure(100 * 1024 * 1024);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceCache 总览](resourcecache.md) - 返回类总览
|
||||
79
docs/api/resources/resourcecache/resourcecache.md
Normal file
79
docs/api/resources/resourcecache/resourcecache.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 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<ResourceGUID> 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) - 返回模块总览
|
||||
27
docs/api/resources/resourcecache/touch.md
Normal file
27
docs/api/resources/resourcecache/touch.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 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) - 返回类总览
|
||||
27
docs/api/resources/resourcehandle/get.md
Normal file
27
docs/api/resources/resourcehandle/get.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceHandle::Get
|
||||
|
||||
```cpp
|
||||
T* Get() const
|
||||
```
|
||||
|
||||
获取资源裸指针。返回句柄内部持有的资源指针，不进行任何引用计数操作。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 资源裸指针，可能为 `nullptr`（当句柄为空时）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
|
||||
Texture* raw = tex.Get();
|
||||
if (raw != nullptr) {
|
||||
uint32_t w = raw->GetWidth();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle 总览](resourcehandle.md) - 返回类总览
|
||||
27
docs/api/resources/resourcehandle/getguid.md
Normal file
27
docs/api/resources/resourcehandle/getguid.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ResourceHandle::GetGUID
|
||||
|
||||
```cpp
|
||||
ResourceGUID GetGUID() const
|
||||
```
|
||||
|
||||
获取资源的全局唯一标识符。如果内部指针为空，则返回一个值为 0 的空 GUID。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 资源的 `ResourceGUID`，如果句柄为空则返回 `ResourceGUID(0)`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
|
||||
ResourceGUID guid = tex.GetGUID();
|
||||
if (guid.IsValid()) {
|
||||
printf("GUID: %s\n", guid.ToString().CStr());
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle 总览](resourcehandle.md) - 返回类总览
|
||||
29
docs/api/resources/resourcehandle/isvalid.md
Normal file
29
docs/api/resources/resourcehandle/isvalid.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# ResourceHandle::IsValid
|
||||
|
||||
```cpp
|
||||
bool IsValid() const
|
||||
```
|
||||
|
||||
检查句柄是否持有有效资源。判断条件为：内部指针非空且资源的 `IsValid()` 返回 true。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 如果持有有效资源则返回 true，否则返回 false
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
|
||||
if (tex.IsValid()) {
|
||||
// 安全访问资源
|
||||
tex->GenerateMipmaps();
|
||||
} else {
|
||||
printf("Texture load failed!\n");
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle 总览](resourcehandle.md) - 返回类总览
|
||||
31
docs/api/resources/resourcehandle/reset.md
Normal file
31
docs/api/resources/resourcehandle/reset.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# ResourceHandle::Reset
|
||||
|
||||
```cpp
|
||||
void Reset()
|
||||
```
|
||||
|
||||
释放当前持有的资源引用。如果内部持有的资源指针非空，则调用 `ResourceManager::Release()` 减少引用计数，并将内部指针置为 `nullptr`。析构函数会自动调用此方法。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
|
||||
// 使用纹理...
|
||||
tex.Reset(); // 释放引用，引用计数 -1
|
||||
|
||||
// 或者让句柄离开作用域自动释放
|
||||
{
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx");
|
||||
// 使用网格...
|
||||
} // mesh 自动 Reset()
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle 总览](resourcehandle.md) - 返回类总览
|
||||
74
docs/api/resources/resourcehandle/resourcehandle.md
Normal file
74
docs/api/resources/resourcehandle/resourcehandle.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# ResourceHandle
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class` (template)
|
||||
|
||||
**描述**: 模板资源句柄类，提供资源的引用计数式安全访问，自动管理资源的加载和释放。
|
||||
|
||||
## 概述
|
||||
|
||||
`ResourceHandle<T>` 是一个模板句柄类，用于安全地持有对资源的引用。它通过 `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<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
|
||||
|
||||
// 检查有效性
|
||||
if (tex.IsValid()) {
|
||||
// 安全访问资源
|
||||
uint32_t width = tex->GetWidth();
|
||||
}
|
||||
|
||||
// 拷贝句柄（引用计数 +1）
|
||||
ResourceHandle<Texture> tex2 = tex;
|
||||
|
||||
// 移动句柄
|
||||
ResourceHandle<Texture> tex3 = std::move(tex2);
|
||||
|
||||
// 句柄离开作用域时自动释放（引用计数 -1）
|
||||
tex.Reset(); // 手动释放
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
30
docs/api/resources/resourcehandle/swap.md
Normal file
30
docs/api/resources/resourcehandle/swap.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# ResourceHandle::Swap
|
||||
|
||||
```cpp
|
||||
void Swap(ResourceHandle& other)
|
||||
```
|
||||
|
||||
交换两个句柄持有的资源指针。使用 `std::swap` 交换内部指针，不会改变任何引用计数。此操作常用于在不影响引用计数的情况下安全地交换两个句柄的内容。
|
||||
|
||||
**参数：**
|
||||
- `other` - 要交换的另一个 ResourceHandle 引用
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex1 = ResourceManager::Get().Load<Texture>("a.png");
|
||||
ResourceHandle<Texture> tex2 = ResourceManager::Get().Load<Texture>("b.png");
|
||||
|
||||
// 交换后 tex1 持有 b.png，tex2 持有 a.png
|
||||
tex1.Swap(tex2);
|
||||
|
||||
// 引用计数不变
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceHandle 总览](resourcehandle.md) - 返回类总览
|
||||
28
docs/api/resources/resourcemanager/exists.md
Normal file
28
docs/api/resources/resourcemanager/exists.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# 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<Texture>("textures/player.png");
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
29
docs/api/resources/resourcemanager/find.md
Normal file
29
docs/api/resources/resourcemanager/find.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# 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<Texture*>(res);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
27
docs/api/resources/resourcemanager/getloader.md
Normal file
27
docs/api/resources/resourcemanager/getloader.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 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) - 返回类总览
|
||||
32
docs/api/resources/resourcemanager/load.md
Normal file
32
docs/api/resources/resourcemanager/load.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# ResourceManager::Load
|
||||
|
||||
```cpp
|
||||
template<typename T>
|
||||
ResourceHandle<T> Load(const Containers::String& path, ImportSettings* settings = nullptr)
|
||||
```
|
||||
|
||||
同步加载资源。模板方法，根据路径生成 GUID，先在缓存中查找是否已加载；若未加载则查找对应类型的加载器并同步加载，然后将结果加入缓存。
|
||||
|
||||
**参数：**
|
||||
- `path` - 资源路径
|
||||
- `settings` - 导入设置（可选）
|
||||
|
||||
**返回：** `ResourceHandle<T>`，持有加载的资源
|
||||
|
||||
**复杂度：** O(n)，取决于加载器实现
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
|
||||
ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
|
||||
|
||||
if (tex.IsValid()) {
|
||||
// 使用纹理...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
44
docs/api/resources/resourcemanager/loadasync.md
Normal file
44
docs/api/resources/resourcemanager/loadasync.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# ResourceManager::LoadAsync
|
||||
|
||||
```cpp
|
||||
void LoadAsync(const Containers::String& path, ResourceType type,
|
||||
std::function<void(LoadResult)> callback)
|
||||
void LoadAsync(const Containers::String& path, ResourceType type,
|
||||
ImportSettings* settings, std::function<void(LoadResult)> 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<Texture> 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> mesh(result.resource);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
35
docs/api/resources/resourcemanager/loadgroup.md
Normal file
35
docs/api/resources/resourcemanager/loadgroup.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# ResourceManager::LoadGroup
|
||||
|
||||
```cpp
|
||||
template<typename T>
|
||||
void LoadGroup(const Containers::Array<Containers::String>& paths,
|
||||
std::function<void(ResourceHandle<T>)> callback)
|
||||
```
|
||||
|
||||
批量异步加载同类资源。为路径数组中的每个路径提交一个异步加载请求，所有加载完成时通过回调通知。
|
||||
|
||||
**参数：**
|
||||
- `paths` - 资源路径数组
|
||||
- `callback` - 每个资源加载完成时的回调
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(k)，k 为路径数量（每个加载为 O(n)）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Containers::Array<Containers::String> texPaths = {
|
||||
"textures/a.png", "textures/b.png", "textures/c.png"
|
||||
};
|
||||
ResourceManager::Get().LoadGroup<Texture>(texPaths,
|
||||
[](ResourceHandle<Texture> tex) {
|
||||
if (tex.IsValid()) {
|
||||
printf("Loaded: %s\n", tex->GetPath().CStr());
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
26
docs/api/resources/resourcemanager/registerloader.md
Normal file
26
docs/api/resources/resourcemanager/registerloader.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 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) - 返回类总览
|
||||
101
docs/api/resources/resourcemanager/resourcemanager.md
Normal file
101
docs/api/resources/resourcemanager/resourcemanager.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 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<T> Load(const Containers::String& path, ImportSettings* settings = nullptr)` | 同步加载资源（模板方法） |
|
||||
| `void LoadAsync(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 异步加载资源 |
|
||||
| `void LoadAsync(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载 |
|
||||
| `void LoadGroup(const Containers::Array<Containers::String>& paths, std::function<void(ResourceHandle<T>)> 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<Containers::String> GetResourcePaths() const` | 获取所有已加载资源的路径列表 |
|
||||
| `void UnloadGroup(const Containers::Array<ResourceGUID>& 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<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
|
||||
|
||||
// 异步加载
|
||||
ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture,
|
||||
[](LoadResult result) {
|
||||
if (result.success) {
|
||||
ResourceHandle<Texture> tex(result.resource);
|
||||
// 使用纹理...
|
||||
}
|
||||
});
|
||||
|
||||
// 批量加载
|
||||
Containers::Array<Containers::String> paths = {"a.png", "b.png", "c.png"};
|
||||
ResourceManager::Get().LoadGroup<Texture>(paths,
|
||||
[](ResourceHandle<Texture> 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) - 返回模块总览
|
||||
24
docs/api/resources/resourcemanager/setmemorybudget.md
Normal file
24
docs/api/resources/resourcemanager/setmemorybudget.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# ResourceManager::SetMemoryBudget
|
||||
|
||||
```cpp
|
||||
void SetMemoryBudget(size_t bytes)
|
||||
```
|
||||
|
||||
设置资源管理的内存预算上限。当缓存中资源的总内存占用超过预算时，会触发 LRU 驱逐策略释放内存。
|
||||
|
||||
**参数：**
|
||||
- `bytes` - 内存预算大小（字节）
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceManager::Get().SetMemoryBudget(1024 * 1024 * 1024); // 1GB 预算
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
31
docs/api/resources/resourcemanager/unload.md
Normal file
31
docs/api/resources/resourcemanager/unload.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 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) - 返回类总览
|
||||
26
docs/api/resources/resourcemanager/unloadunused.md
Normal file
26
docs/api/resources/resourcemanager/unloadunused.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# ResourceManager::UnloadUnused
|
||||
|
||||
```cpp
|
||||
void UnloadUnused()
|
||||
```
|
||||
|
||||
卸载所有无引用的资源。遍历资源缓存，将引用计数为零的资源全部释放。常在场景切换或内存紧张时调用。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
// 切换场景时清理无用资源
|
||||
void OnSceneUnload() {
|
||||
ResourceManager::Get().UnloadUnused();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceManager 总览](resourcemanager.md) - 返回类总览
|
||||
161
docs/api/resources/resourcepackage/resourcepackage.md
Normal file
161
docs/api/resources/resourcepackage/resourcepackage.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# ResourcePackage
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 资源包读写工具，支持打包多个资源文件到单个包文件中，以及从包中读取资源。
|
||||
|
||||
## 概述
|
||||
|
||||
`ResourcePackage` 提供了资源打包功能，可以将多个资源文件打包成单个包文件，方便分发和加载。包文件包含文件清单和数据区域。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/ResourcePackage.h>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PackageFileEntry 结构体
|
||||
|
||||
打包文件条目信息。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `relativePath` | `Containers::String` | 相对路径 |
|
||||
| `size` | `size_t` | 文件大小 |
|
||||
| `checksum` | `Core::uint64` | 校验和 |
|
||||
| `offset` | `size_t` | 数据偏移量 |
|
||||
|
||||
---
|
||||
|
||||
## ResourcePackageBuilder
|
||||
|
||||
资源包构建器，用于创建新的资源包。
|
||||
|
||||
### 构造与析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourcePackageBuilder()` | 默认构造 |
|
||||
| `~ResourcePackageBuilder()` | 析构函数 |
|
||||
|
||||
### 包构建
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool AddFile(const Containers::String& sourcePath, const Containers::String& relativePath)` | 添加单个文件到包 |
|
||||
| `bool AddDirectory(const Containers::String& sourceDir, const Containers::String& relativeBase = "")` | 添加整个目录到包（当前为 stub，始终返回 true） |
|
||||
| `void SetOutputPath(const Containers::String& path)` | 设置输出包文件路径 |
|
||||
| `const Containers::String& GetOutputPath() const` | 获取输出路径 |
|
||||
| `bool Build()` | 构建包文件 |
|
||||
| `float GetProgress() const` | 获取构建进度（0.0f ~ 1.0f） |
|
||||
| `const Containers::String& GetError() const` | 获取错误信息 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `ResourcePackageBuilder::AddDirectory()` 当前为 stub，始终返回 true。
|
||||
|
||||
## 使用示例（构建）
|
||||
|
||||
```cpp
|
||||
ResourcePackageBuilder builder;
|
||||
|
||||
// 添加文件
|
||||
builder.AddFile("textures/player.png", "textures/player.png");
|
||||
builder.AddFile("textures/terrain.png", "textures/terrain.png");
|
||||
|
||||
// 添加目录
|
||||
builder.AddDirectory("shaders/", "shaders/");
|
||||
|
||||
// 设置输出
|
||||
builder.SetOutputPath("data/resources.pkg");
|
||||
|
||||
// 构建
|
||||
if (builder.Build()) {
|
||||
printf("Package built successfully!\n");
|
||||
} else {
|
||||
printf("Build failed: %s\n", builder.GetError().CStr());
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ResourcePackage
|
||||
|
||||
资源包读取器，用于从已打包的文件中读取资源。
|
||||
|
||||
### 构造与析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourcePackage()` | 默认构造 |
|
||||
| `~ResourcePackage()` | 析构函数，自动关闭包 |
|
||||
|
||||
### 包操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Open(const Containers::String& packagePath)` | 打开包文件 |
|
||||
| `void Close()` | 关闭包文件 |
|
||||
| `bool IsValid() const` | 检查包是否有效 |
|
||||
|
||||
### 文件操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Exists(const Containers::String& relativePath) const` | 检查文件是否存在于包中 |
|
||||
| `Containers::Array<Core::uint8> Read(const Containers::String& relativePath) const` | 读取包内文件 |
|
||||
| `size_t GetSize(const Containers::String& relativePath) const` | 获取包内文件大小 |
|
||||
| `void Enumerate(const Containers::String& pattern, Containers::Array<Containers::String>& outFiles) const` | 枚举包内匹配的文件 |
|
||||
|
||||
### 包信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `const PackageInfo& GetInfo() const` | 获取包信息 |
|
||||
|
||||
### PackageInfo 结构体
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `path` | `Containers::String` | 包文件路径 |
|
||||
| `version` | `Core::uint16` | 包格式版本 |
|
||||
| `fileCount` | `size_t` | 文件数量 |
|
||||
| `totalSize` | `size_t` | 总大小 |
|
||||
|
||||
## 使用示例（读取）
|
||||
|
||||
```cpp
|
||||
ResourcePackage package;
|
||||
if (package.Open("data/resources.pkg")) {
|
||||
// 检查文件
|
||||
if (package.Exists("textures/player.png")) {
|
||||
// 读取文件
|
||||
auto data = package.Read("textures/player.png");
|
||||
if (!data.Empty()) {
|
||||
// 使用数据...
|
||||
}
|
||||
}
|
||||
|
||||
// 获取文件大小
|
||||
size_t size = package.GetSize("textures/player.png");
|
||||
|
||||
// 枚举文件
|
||||
Containers::Array<Containers::String> files;
|
||||
package.Enumerate("textures/*.png", files);
|
||||
|
||||
// 获取包信息
|
||||
auto info = package.GetInfo();
|
||||
printf("Package: %s, Files: %zu\n", info.path.CStr(), info.fileCount);
|
||||
|
||||
package.Close();
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceFileSystem](../filesystem/filesystem.md) - 资源文件系统
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
87
docs/api/resources/resourcepath/resourcepath.md
Normal file
87
docs/api/resources/resourcepath/resourcepath.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# ResourcePath
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 资源路径封装类，提供路径解析、转换和 GUID 生成功能。
|
||||
|
||||
## 概述
|
||||
|
||||
`ResourcePath` 封装了资源路径字符串，提供了一系列便捷方法进行路径解析、扩展名检查和 GUID 转换。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/ResourcePath.h>
|
||||
```
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourcePath() = default` | 默认构造空路径 |
|
||||
| `ResourcePath(const char* path)` | 从 C 字符串构造 |
|
||||
| `ResourcePath(const Containers::String& path)` | 从 String 构造 |
|
||||
|
||||
### 路径解析
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `Containers::String GetExtension() const` | 获取文件扩展名 |
|
||||
| `Containers::String GetStem() const` | 获取文件名（不含扩展名） |
|
||||
| `Containers::String GetFullPath() const` | 获取完整路径 |
|
||||
| `Containers::String GetFileName() const` | 获取文件名（含扩展名） |
|
||||
| `Containers::String GetDirectory() const` | 获取目录部分 |
|
||||
| `Containers::String GetRelativePath() const` | 获取相对路径 |
|
||||
|
||||
### GUID 转换
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ResourceGUID ToGUID() const` | 将路径转换为 GUID |
|
||||
|
||||
### 扩展名检查
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool HasExtension(const char* ext) const` | 检查是否具有指定扩展名 |
|
||||
| `bool HasAnyExtension(const char* const* extensions, Core::uint32 count) const` | 检查是否具有任意指定扩展名 |
|
||||
|
||||
### 状态
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool IsValid() const` | 检查路径是否有效（非空） |
|
||||
| `const Containers::String& GetPath() const` | 获取原始路径字符串 |
|
||||
| `void SetPath(const Containers::String& path)` | 设置路径字符串 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
ResourcePath path("textures/player.png");
|
||||
|
||||
// 路径解析
|
||||
Containers::String ext = path.GetExtension(); // ".png"
|
||||
Containers::String name = path.GetFileName(); // "player.png"
|
||||
Containers::String dir = path.GetDirectory(); // "textures"
|
||||
|
||||
// 扩展名检查
|
||||
if (path.HasExtension(".png") || path.HasExtension(".jpg")) {
|
||||
// 是图像文件
|
||||
}
|
||||
|
||||
// 转换为 GUID
|
||||
ResourceGUID guid = path.ToGUID();
|
||||
|
||||
// 在 HashMap 中作为键使用
|
||||
Containers::HashMap<ResourcePath, ResourceHandle<Texture>> textures;
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceTypes](../resourcetypes/resourcetypes.md) - 资源类型定义
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
95
docs/api/resources/resources.md
Normal file
95
docs/api/resources/resources.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Resources 模块概览
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `module`
|
||||
|
||||
**描述**: XCEngine 的资源管理系统，提供资源的异步加载、缓存和依赖管理。
|
||||
|
||||
## 概述
|
||||
|
||||
Resources 模块提供了一套完整的资源管理解决方案，支持同步和异步加载、资源缓存、依赖图管理等功能。
|
||||
|
||||
## 模块内容
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [IResource](iresource/iresource.md) | `IResource.h` | 资源基类 |
|
||||
| [ResourceHandle](resourcehandle/resourcehandle.md) | `ResourceHandle.h` | 资源句柄模板 |
|
||||
| [IResourceLoader](iloader/iloader.md) | `IResourceLoader.h` | 资源加载器接口 |
|
||||
| [ResourceManager](resourcemanager/resourcemanager.md) | `ResourceManager.h` | 资源管理器 |
|
||||
| [ResourceCache](resourcecache/resourcecache.md) | `ResourceCache.h` | 资源缓存 |
|
||||
| [AsyncLoader](asyncloader/asyncloader.md) | `AsyncLoader.h` | 异步加载器 |
|
||||
| [ResourceDependencyGraph](dependencygraph/dependencygraph.md) | `ResourceDependencyGraph.h` | 依赖图 |
|
||||
| [ResourceTypes](resourcetypes/resourcetypes.md) | `ResourceTypes.h` | 资源类型定义 |
|
||||
| [ResourcePath](resourcepath/resourcepath.md) | `ResourcePath.h` | 资源路径封装 |
|
||||
| [ResourceFileSystem](filesystem/filesystem.md) | `ResourceFileSystem.h` | 虚拟文件系统 |
|
||||
| [ImportSettings](importsettings/importsettings.md) | `ImportSettings.h` | 导入设置基类 |
|
||||
|
||||
### 文件与打包
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [FileArchive](filearchive/filearchive.md) | `FileArchive.h` | 文件归档读取 |
|
||||
| [ResourcePackage](resourcepackage/resourcepackage.md) | `ResourcePackage.h` | 资源包打包/读取 |
|
||||
|
||||
### 具体资源类型
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Texture](texture/texture.md) | `Texture.h` | 纹理资源 |
|
||||
| [Mesh](mesh/mesh.md) | `Mesh.h` | 网格资源 |
|
||||
| [Material](material/material.md) | `Material.h` | 材质资源 |
|
||||
| [Shader](shader/shader.md) | `Shader.h` | 着色器资源 |
|
||||
| [AudioClip](audioclip/audioclip.md) | `AudioClip.h` | 音频资源 |
|
||||
|
||||
## 资源类型
|
||||
|
||||
| 类型 | 描述 |
|
||||
|------|------|
|
||||
| `Texture` | 纹理资源 |
|
||||
| `Mesh` | 网格/模型资源 |
|
||||
| `Material` | 材质资源 |
|
||||
| `Shader` | 着色器资源 |
|
||||
| `AudioClip` | 音频资源 |
|
||||
| `Binary` | 二进制数据 |
|
||||
| `AnimationClip` | 动画片段 |
|
||||
| `Skeleton` | 骨骼 |
|
||||
| `Font` | 字体 |
|
||||
| `ParticleSystem` | 粒子系统 |
|
||||
| `Scene` | 场景 |
|
||||
| `Prefab` | 预制体 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/ResourceManager.h>
|
||||
|
||||
// 初始化资源管理器
|
||||
ResourceManager::Get().Initialize();
|
||||
ResourceManager::Get().SetResourceRoot("resources/");
|
||||
|
||||
// 同步加载资源
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
|
||||
ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("models/player.fbx");
|
||||
ResourceHandle<Material> mat = ResourceManager::Get().Load<Material>("materials/player.mat");
|
||||
|
||||
// 异步加载
|
||||
ResourceManager::Get().LoadAsync("textures/terrain.png", ResourceType::Texture,
|
||||
[](LoadResult result) {
|
||||
if (result.success) {
|
||||
ResourceHandle<Texture> tex(result.resource);
|
||||
// 加载完成回调
|
||||
}
|
||||
});
|
||||
|
||||
// 释放资源
|
||||
tex.Reset();
|
||||
mesh.Reset();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [RHI 模块](../rhi/rhi.md) - GPU 资源创建
|
||||
26
docs/api/resources/resourcetypes/generate.md
Normal file
26
docs/api/resources/resourcetypes/generate.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# ResourceGUID::Generate
|
||||
|
||||
```cpp
|
||||
static ResourceGUID Generate(const char* path)
|
||||
static ResourceGUID Generate(const Containers::String& path)
|
||||
```
|
||||
|
||||
从资源路径生成唯一的全局标识符。通过哈希算法将路径字符串转换为唯一的 64 位整数。
|
||||
|
||||
**参数：**
|
||||
- `path` - 资源路径
|
||||
|
||||
**返回：** 生成的 `ResourceGUID`
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ResourceGUID guid = ResourceGUID::Generate("textures/player.png");
|
||||
ResourceGUID guid2 = ResourceGUID::Generate("models/player.fbx");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceTypes 总览](resourcetypes.md) - 返回类总览
|
||||
25
docs/api/resources/resourcetypes/getresourcetypename.md
Normal file
25
docs/api/resources/resourcetypes/getresourcetypename.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# GetResourceTypeName
|
||||
|
||||
```cpp
|
||||
constexpr const char* GetResourceTypeName(ResourceType type)
|
||||
```
|
||||
|
||||
获取资源类型的字符串名称。通过 switch 语句返回对应的类型名字符串。
|
||||
|
||||
**参数：**
|
||||
- `type` - 资源类型枚举值
|
||||
|
||||
**返回：** 类型名字符串（如 `"Texture"`、`"Mesh"` 等）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture"
|
||||
const char* name2 = GetResourceTypeName(ResourceType::Shader); // "Shader"
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ResourceTypes 总览](resourcetypes.md) - 返回类总览
|
||||
130
docs/api/resources/resourcetypes/resourcetypes.md
Normal file
130
docs/api/resources/resourcetypes/resourcetypes.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# ResourceTypes
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `enums` / `structs`
|
||||
|
||||
**描述**: 资源模块中使用的所有类型定义，包括资源类型枚举、GUID 结构体等。
|
||||
|
||||
## 概述
|
||||
|
||||
本文档汇总了 Resources 模块中的所有类型定义，包括资源类型枚举、GUID 结构体等基础类型。
|
||||
|
||||
---
|
||||
|
||||
## ResourceType
|
||||
|
||||
资源类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Unknown` | 未知类型 |
|
||||
| `Texture` | 纹理资源 |
|
||||
| `Mesh` | 网格/模型资源 |
|
||||
| `Material` | 材质资源 |
|
||||
| `Shader` | 着色器资源 |
|
||||
| `AudioClip` | 音频资源 |
|
||||
| `Binary` | 二进制数据 |
|
||||
| `AnimationClip` | 动画片段 |
|
||||
| `Skeleton` | 骨骼 |
|
||||
| `Font` | 字体 |
|
||||
| `ParticleSystem` | 粒子系统 |
|
||||
| `Scene` | 场景 |
|
||||
| `Prefab` | 预制体 |
|
||||
|
||||
---
|
||||
|
||||
## ResourceGUID
|
||||
|
||||
全局唯一标识符结构体，用于唯一标识每个资源。
|
||||
|
||||
```cpp
|
||||
struct ResourceGUID {
|
||||
Core::uint64 value;
|
||||
|
||||
ResourceGUID() : value(0) {}
|
||||
explicit ResourceGUID(Core::uint64 v) : value(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; }
|
||||
|
||||
static ResourceGUID Generate(const char* path);
|
||||
static ResourceGUID Generate(const Containers::String& path);
|
||||
|
||||
Containers::String ToString() const;
|
||||
};
|
||||
```
|
||||
|
||||
### 比较运算
|
||||
|
||||
| 运算符 | 描述 |
|
||||
|------|------|
|
||||
| `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` | 转换为字符串 |
|
||||
|
||||
### 辅助函数
|
||||
|
||||
| 函数 | 描述 |
|
||||
|------|------|
|
||||
| `constexpr const char* GetResourceTypeName(ResourceType type)` | 获取资源类型的字符串名称 |
|
||||
| `ResourceGUID MakeResourceGUID(const char* path)` | 从路径生成 GUID 的辅助函数 |
|
||||
|
||||
### 模板特化
|
||||
|
||||
```cpp
|
||||
template<> inline ResourceType GetResourceType<class Texture>() { return ResourceType::Texture; }
|
||||
template<> inline ResourceType GetResourceType<class Mesh>() { return ResourceType::Mesh; }
|
||||
template<> inline ResourceType GetResourceType<class Material>() { return ResourceType::Material; }
|
||||
template<> inline ResourceType GetResourceType<class Shader>() { return ResourceType::Shader; }
|
||||
template<> inline ResourceType GetResourceType<class AudioClip>() { return ResourceType::AudioClip; }
|
||||
template<> inline ResourceType GetResourceType<class BinaryResource>() { return ResourceType::Binary; }
|
||||
```
|
||||
|
||||
**注意**: `GetResourceType<T>()` 是模板特化函数，用于在编译时获取资源类型。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 使用 ResourceGUID
|
||||
ResourceGUID texGuid = ResourceGUID::Generate("textures/player.png");
|
||||
ResourceGUID meshGuid = ResourceGUID::Generate("models/player.fbx");
|
||||
|
||||
// GUID 比较
|
||||
if (texGuid == meshGuid) {
|
||||
// 相同资源
|
||||
}
|
||||
|
||||
// 有效性检查
|
||||
if (texGuid.IsValid()) {
|
||||
// GUID 有效
|
||||
}
|
||||
|
||||
// 在 HashMap 中使用
|
||||
Containers::HashMap<ResourceGUID, IResource*> cache;
|
||||
cache[texGuid] = texture;
|
||||
|
||||
// 获取类型名称
|
||||
const char* name = GetResourceTypeName(ResourceType::Texture); // "Texture"
|
||||
|
||||
// 使用模板获取类型
|
||||
ResourceType type = GetResourceType<Texture>(); // ResourceType::Texture
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
29
docs/api/resources/shader/addattribute.md
Normal file
29
docs/api/resources/shader/addattribute.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Shader::AddAttribute
|
||||
|
||||
```cpp
|
||||
void AddAttribute(const ShaderAttribute& attribute)
|
||||
```
|
||||
|
||||
添加顶点属性描述。
|
||||
|
||||
**参数：**
|
||||
- `attribute` - 属性描述结构体
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ShaderAttribute attr;
|
||||
attr.name = "position";
|
||||
attr.location = 0;
|
||||
attr.size = sizeof(float) * 3;
|
||||
attr.type = 0;
|
||||
vs->AddAttribute(attr);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Shader 总览](shader.md) - 返回类总览
|
||||
29
docs/api/resources/shader/adduniform.md
Normal file
29
docs/api/resources/shader/adduniform.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Shader::AddUniform
|
||||
|
||||
```cpp
|
||||
void AddUniform(const ShaderUniform& uniform)
|
||||
```
|
||||
|
||||
添加 Uniform 变量描述。
|
||||
|
||||
**参数：**
|
||||
- `uniform` - Uniform 描述结构体
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
ShaderUniform uniform;
|
||||
uniform.name = "modelMatrix";
|
||||
uniform.location = 0;
|
||||
uniform.size = sizeof(float) * 16;
|
||||
uniform.type = 0;
|
||||
vs->AddUniform(uniform);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Shader 总览](shader.md) - 返回类总览
|
||||
154
docs/api/resources/shader/shader.md
Normal file
154
docs/api/resources/shader/shader.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Shader
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 着色器资源类，管理着色器源码、编译后的二进制和 uniform/attribute 信息。
|
||||
|
||||
## 概述
|
||||
|
||||
`Shader` 是 XCEngine 中的着色器资源类，继承自 `IResource`。它管理着色器源码、编译后的二进制数据、着色器类型、语言类型、uniform 列表和 attribute 列表，并持有对应的 RHI 着色器资源指针。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/Shader.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### ShaderType
|
||||
|
||||
着色器类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Vertex` | 顶点着色器 |
|
||||
| `Fragment` | 片元着色器 |
|
||||
| `Geometry` | 几何着色器 |
|
||||
| `Compute` | 计算着色器 |
|
||||
| `Hull` | Hull 着色器（曲面细分控制） |
|
||||
| `Domain` | Domain 着色器（曲面细分评估） |
|
||||
|
||||
### ShaderLanguage
|
||||
|
||||
着色器语言枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `GLSL` | OpenGL Shading Language |
|
||||
| `HLSL` | High-Level Shading Language |
|
||||
| `SPIRV` | SPIR-V 二进制格式 |
|
||||
|
||||
## 结构体
|
||||
|
||||
### ShaderUniform
|
||||
|
||||
Uniform 变量描述。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | `Containers::String` | Uniform 名称 |
|
||||
| `location` | `Core::uint32` | 位置/绑定点 |
|
||||
| `size` | `Core::uint32` | 大小（字节） |
|
||||
| `type` | `Core::uint32` | 类型标识 |
|
||||
|
||||
### ShaderAttribute
|
||||
|
||||
顶点属性描述。
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | `Containers::String` | 属性名称 |
|
||||
| `location` | `Core::uint32` | 位置索引 |
|
||||
| `size` | `Core::uint32` | 大小（字节） |
|
||||
| `type` | `Core::uint32` | 类型标识 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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()` | 释放着色器引用 |
|
||||
|
||||
## 实现说明
|
||||
|
||||
**注意**: `ShaderLoader::DetectShaderType()` 对于非标准扩展名始终返回 `ShaderType::Fragment`。`ShaderLoader::ParseShaderSource()` 为 stub，始终返回 true。
|
||||
|
||||
### 类型与语言
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetShaderType(ShaderType type)` | 设置着色器类型 |
|
||||
| `ShaderType GetShaderType() const` | 获取着色器类型 |
|
||||
| `void SetShaderLanguage(ShaderLanguage lang)` | 设置着色器语言 |
|
||||
| `ShaderLanguage GetShaderLanguage() const` | 获取着色器语言 |
|
||||
|
||||
### 源码与编译
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetSourceCode(const Containers::String& source)` | 设置源码 |
|
||||
| `const Containers::String& GetSourceCode() const` | 获取源码 |
|
||||
| `void SetCompiledBinary(const Containers::Array<Core::uint8>& binary)` | 设置编译后二进制 |
|
||||
| `const Containers::Array<Core::uint8>& GetCompiledBinary() const` | 获取编译后二进制 |
|
||||
|
||||
### Uniform 和 Attribute
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void AddUniform(const ShaderUniform& uniform)` | 添加 Uniform 描述 |
|
||||
| `const Containers::Array<ShaderUniform>& GetUniforms() const` | 获取 Uniform 列表 |
|
||||
| `void AddAttribute(const ShaderAttribute& attribute)` | 添加 Attribute 描述 |
|
||||
| `const Containers::Array<ShaderAttribute>& GetAttributes() const` | 获取 Attribute 列表 |
|
||||
|
||||
### RHI 资源
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `class IRHIShader* GetRHIResource() const` | 获取 RHI 着色器资源 |
|
||||
| `void SetRHIResource(class IRHIShader* resource)` | 设置 RHI 着色器资源 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载着色器
|
||||
ResourceHandle<Shader> vs = ResourceManager::Get().Load<Shader>("shaders/vertex.glsl");
|
||||
ResourceHandle<Shader> fs = ResourceManager::Get().Load<Shader>("shaders/fragment.glsl");
|
||||
|
||||
// 设置类型
|
||||
vs->SetShaderType(ShaderType::Vertex);
|
||||
fs->SetShaderType(ShaderType::Fragment);
|
||||
|
||||
// 设置语言
|
||||
vs->SetShaderLanguage(ShaderLanguage::GLSL);
|
||||
|
||||
// 设置编译后二进制
|
||||
vs->SetCompiledBinary(compiledSpirv);
|
||||
|
||||
// 添加 Uniform
|
||||
ShaderUniform uniform;
|
||||
uniform.name = "modelMatrix";
|
||||
uniform.location = 0;
|
||||
uniform.size = sizeof(float) * 16;
|
||||
uniform.type = 0;
|
||||
vs->AddUniform(uniform);
|
||||
|
||||
// 访问 RHI 资源
|
||||
RHIShader* rhiShader = vs->GetRHIResource();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IResource](../iresource/iresource.md) - 资源基类
|
||||
- [RHIShader](../../rhi/shader/shader.md) - RHI 着色器接口
|
||||
- [Material](../material/material.md) - 材质资源
|
||||
- [Resources 总览](../resources.md) - 返回模块总览
|
||||
39
docs/api/resources/texture/create.md
Normal file
39
docs/api/resources/texture/create.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Texture::Create
|
||||
|
||||
```cpp
|
||||
bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth,
|
||||
Core::uint32 mipLevels, TextureType type, TextureFormat format,
|
||||
const void* data, size_t dataSize)
|
||||
```
|
||||
|
||||
创建纹理资源。设置纹理的尺寸、格式和像素数据，并分配 GPU 资源。
|
||||
|
||||
**参数：**
|
||||
- `width` - 纹理宽度（像素）
|
||||
- `height` - 纹理高度（像素）
|
||||
- `depth` - 纹理深度（3D 纹理设为 1）
|
||||
- `mipLevels` - Mipmap 级别数
|
||||
- `type` - 纹理类型
|
||||
- `format` - 纹理格式
|
||||
- `data` - 像素数据指针
|
||||
- `dataSize` - 像素数据大小
|
||||
|
||||
**返回：** 创建成功返回 true
|
||||
|
||||
**复杂度：** O(n)，n 为像素数量
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Texture tex;
|
||||
bool ok = tex.Create(
|
||||
1024, 1024, 1, 0,
|
||||
TextureType::Texture2D,
|
||||
TextureFormat::RGBA8_UNORM,
|
||||
pixelData, pixelDataSize
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Texture 总览](texture.md) - 返回类总览
|
||||
24
docs/api/resources/texture/generatemipmaps.md
Normal file
24
docs/api/resources/texture/generatemipmaps.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# Texture::GenerateMipmaps
|
||||
|
||||
```cpp
|
||||
bool GenerateMipmaps()
|
||||
```
|
||||
|
||||
生成纹理的 Mipmap 链。根据基础级别纹理自动生成所有下采样级别，用于纹理在缩小渲染时避免闪烁。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 生成成功返回 true
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
tex.Create(1024, 1024, 1, 1, TextureType::Texture2D, TextureFormat::RGBA8_UNORM, data, size);
|
||||
tex.GenerateMipmaps();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Texture 总览](texture.md) - 返回类总览
|
||||
161
docs/api/resources/texture/texture.md
Normal file
161
docs/api/resources/texture/texture.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Texture
|
||||
|
||||
**命名空间**: `XCEngine::Resources`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 纹理资源类，管理 2D/3D 纹理和立方体贴图的像素数据。
|
||||
|
||||
## 概述
|
||||
|
||||
`Texture` 是 XCEngine 中的纹理资源类，继承自 `IResource`。它管理纹理的尺寸、格式、像素数据，并支持 mipmap 生成等功能。
|
||||
|
||||
## 头文件
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Resources/Texture.h>
|
||||
```
|
||||
|
||||
## 枚举类型
|
||||
|
||||
### TextureType
|
||||
|
||||
纹理类型枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Texture2D` | 2D 纹理 |
|
||||
| `Texture3D` | 3D 体积纹理 |
|
||||
| `TextureCube` | 立方体贴图 |
|
||||
| `Texture2DArray` | 2D 纹理数组 |
|
||||
| `TextureCubeArray` | 立方体贴图数组 |
|
||||
|
||||
### TextureFormat
|
||||
|
||||
纹理像素格式枚举。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `Unknown` | 未知格式 |
|
||||
| `R8_UNORM` | 单通道 8 位归一化 |
|
||||
| `RG8_UNORM` | 双通道 8 位归一化 |
|
||||
| `RGBA8_UNORM` | 四通道 8 位归一化 |
|
||||
| `RGBA8_SRGB` | 四通道 8 位 sRGB |
|
||||
| `R16_FLOAT` | 单通道 16 位浮点 |
|
||||
| `RG16_FLOAT` | 双通道 16 位浮点 |
|
||||
| `RGBA16_FLOAT` | 四通道 16 位浮点 |
|
||||
| `R32_FLOAT` | 单通道 32 位浮点 |
|
||||
| `RG32_FLOAT` | 双通道 32 位浮点 |
|
||||
| `RGBA32_FLOAT` | 四通道 32 位浮点 |
|
||||
| `D16_UNORM` | 16 位深度 |
|
||||
| `D24_UNORM_S8_UINT` | 24 位深度 + 8 位模板 |
|
||||
| `D32_FLOAT` | 32 位深度 |
|
||||
| `D32_FLOAT_S8_X24_UINT` | 32 位深度 + 8+24 位模板 |
|
||||
| `BC1_UNORM` | BC1 压缩 (DXT1) |
|
||||
| `BC1_UNORM_SRGB` | BC1 sRGB |
|
||||
| `BC2_UNORM` | BC2 压缩 (DXT3) |
|
||||
| `BC2_UNORM_SRGB` | BC2 sRGB |
|
||||
| `BC3_UNORM` | BC3 压缩 (DXT5) |
|
||||
| `BC3_UNORM_SRGB` | BC3 sRGB |
|
||||
| `BC4_UNORM` | BC4 压缩 |
|
||||
| `BC5_UNORM` | BC5 压缩 |
|
||||
| `BC6H_UF16` | BC6H 压缩 |
|
||||
| `BC7_UNORM` | BC7 压缩 |
|
||||
| `BC7_UNORM_SRGB` | BC7 sRGB |
|
||||
|
||||
### TextureUsage
|
||||
|
||||
纹理用途标志枚举（可组合）。
|
||||
|
||||
| 值 | 描述 |
|
||||
|----|------|
|
||||
| `None` | 无特殊用途 |
|
||||
| `ShaderResource` | 着色器资源 |
|
||||
| `RenderTarget` | 渲染目标 |
|
||||
| `DepthStencil` | 深度模板 |
|
||||
| `UnorderedAccess` | 无序访问 |
|
||||
| `TransferSrc` | 传输源 |
|
||||
| `TransferDst` | 传输目标 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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()` | 释放纹理引用 |
|
||||
|
||||
### 纹理属性
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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` | 获取纹理用途标志 |
|
||||
|
||||
### 像素数据
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `const void* GetPixelData() const` | 获取像素数据指针 |
|
||||
| `size_t GetPixelDataSize() const` | 获取像素数据大小 |
|
||||
|
||||
### 创建与操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `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 实现。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 加载纹理
|
||||
ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
|
||||
|
||||
// 手动创建纹理
|
||||
Texture tex;
|
||||
bool created = tex.Create(
|
||||
1024, // 宽度
|
||||
1024, // 高度
|
||||
1, // 深度
|
||||
0, // Mipmap 级别（0=全部）
|
||||
TextureType::Texture2D, // 类型
|
||||
TextureFormat::RGBA8_UNORM, // 格式
|
||||
pixelData, // 像素数据
|
||||
pixelDataSize // 数据大小
|
||||
);
|
||||
|
||||
// 生成 Mipmap
|
||||
tex.GenerateMipmaps();
|
||||
|
||||
// 访问纹理属性
|
||||
uint32_t w = tex.GetWidth();
|
||||
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 等格式的实际图像数据，仅创建空纹理对象。
|
||||
Reference in New Issue
Block a user