75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
# 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) - 返回模块总览
|