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

# Texture

**命名空间**: `XCEngine::Resources`

**类型**: `class` (inherits from `IResource`)

**头文件**: `XCEngine/Resources/Texture.h`

**描述**: 纹理资源类，管理 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` | 传输目标 |

## 公共方法

### 构造与析构

| 方法 | 描述 |
|------|------|
| [`Texture`](constructor.md) | 默认构造函数 |
| [`~Texture`](destructor.md) | 析构函数 |

### IResource 实现

继承自 `IResource` 接口。

| 方法 | 描述 |
|------|------|
| [`GetType`](../iresource/gettype.md) | 返回 `ResourceType::Texture` |
| [`GetName`](../iresource/getname.md) | 获取纹理名称 |
| [`GetPath`](../iresource/getpath.md) | 获取纹理路径 |
| [`GetGUID`](../iresource/getguid.md) | 获取全局唯一标识符 |
| [`IsValid`](../iresource/isvalid.md) | 检查纹理是否有效 |
| [`GetMemorySize`](../iresource/getmemorysize.md) | 获取内存大小 |
| [`Release`](../iresource/release.md) | 释放纹理引用 |

### 纹理属性

| 方法 | 描述 |
|------|------|
| [`GetWidth`](getwidth.md) | 获取纹理宽度（像素） |
| [`GetHeight`](getheight.md) | 获取纹理高度（像素） |
| [`GetDepth`](getdepth.md) | 获取纹理深度（3D 纹理） |
| [`GetMipLevels`](getmiplevels.md) | 获取 Mipmap 级别数 |
| [`GetArraySize`](getarraysize.md) | 获取数组大小 |
| [`GetTextureType`](gettexturetype.md) | 获取纹理类型 |
| [`GetFormat`](getformat.md) | 获取纹理格式 |
| [`GetUsage`](getusage.md) | 获取纹理用途标志 |

### 像素数据

| 方法 | 描述 |
|------|------|
| [`GetPixelData`](getpixeldata.md) | 获取像素数据指针 |
| [`GetPixelDataSize`](getpixeldatasize.md) | 获取像素数据大小 |

### 创建与操作

| 方法 | 描述 |
|------|------|
| [`Create`](create.md) | 创建纹理 |
| [`GenerateMipmaps`](generatemipmaps.md) | 生成 Mipmap 链 |

## 使用示例

```cpp
// 手动创建纹理
Texture tex;
bool created = tex.Create(
    1024,                          // 宽度
    1024,                          // 高度
    1,                             // 深度
    1,                             // Mipmap 级别数
    TextureType::Texture2D,        // 类型
    TextureFormat::RGBA8_UNORM,    // 格式
    pixelData,                     // 像素数据
    pixelDataSize                  // 数据大小
);

// 访问纹理属性
uint32_t w = tex.GetWidth();
uint32_t h = tex.GetHeight();
auto format = tex.GetFormat();
```

## 相关文档

- [IResource](../iresource/iresource.md) - 资源基类
- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
- [RHITexture](../../rhi/texture/texture.md) - RHI 纹理接口
- [Resources 总览](../resources.md) - 返回模块总览