XCEngine/docs/api/resources/texture/texture.md

# 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 |

## 使用示例

```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) - 返回模块总览