101 lines
2.9 KiB
Markdown
101 lines
2.9 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` | 隐式布尔转换 |
|
|||
|
|
|
|||
|
|
### GUID 和类型
|
|||
|
|
|
|||
|
|
| 方法 | 描述 |
|
|||
|
|
|------|------|
|
|||
|
|
| `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](./resources-iresource.md) - 资源基类
|
|||
|
|
- [ResourceManager](./resources-resourcemanager.md) - 资源管理器
|
|||
|
|
- [ResourceCache](./resources-resourcecache.md) - 资源缓存
|