# 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) - 资源缓存