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

Texture

命名空间: XCEngine::Resources

类型: class

描述: 纹理资源类，管理 2D/3D 纹理和立方体贴图的像素数据。

概述

Texture 是 XCEngine 中的纹理资源类，继承自 IResource。它管理纹理的尺寸、格式、像素数据，并支持 mipmap 生成等功能。

头文件

#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

使用示例

// 加载纹理
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 - 资源基类
• ResourceManager - 资源管理器
• RHITexture - RHI 纹理接口