ssdfasd
dc850d7739
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
# 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) - 返回模块总览
|