ssdfasd
7e4c48d4f9
Fixed discrepancies between source code and documentation: - AsyncLoader: Document Initialize() ignores workerThreadCount, Submit() doesn't do actual async loading, Update() is stub - ResourceManager: Document UnloadUnused() and ReloadResource() are stubs - ResourceCache: Document OnZeroRefCount() and Flush() are stubs - ResourceDependencyGraph: Document TopologicalSort() returns empty (stub) - ResourceFileSystem: Document GetResourceInfo() doesn't fill modifiedTime, EnumerateResources() is stub - FileArchive: Document Enumerate() is stub - ResourcePackageBuilder: Document AddDirectory() is stub - ImportSettings: Document LoadFromJSON/SaveToJSON are stubs - TextureImportSettings/MeshImportSettings: Document JSON methods are stubs - TextureLoader/MeshLoader/MaterialLoader/ShaderLoader/AudioLoader: Document GetDefaultSettings() returns nullptr - AudioLoader: Document ParseWAVData() is stub, Load() doesn't parse WAV headers - ShaderLoader: Document DetectShaderType/ParseShaderSource are stubs - MaterialLoader: Document ParseMaterialData() is stub - Texture: Document Create() mipLevels=0 behavior, GenerateMipmaps() returns false - Mesh: Document MeshLoader::Load() is example only - IResourceLoader: Document GetDefaultSettings() returns nullptr for all loaders
162 lines
4.8 KiB
Markdown
162 lines
4.8 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（当前返回 false - stub） |
|
||
|
||
## 实现说明
|
||
|
||
**注意**: `Create()` 方法中 `mipLevels` 参数为 0 时不会自动计算所有级别。`GenerateMipmaps()` 当前返回 false，为 stub 实现。
|
||
|
||
## 使用示例
|
||
|
||
```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) - 返回模块总览
|
||
|
||
## 实现说明
|
||
|
||
**注意**: `TextureLoader::Load()` 仅为示例实现，不解析 PNG/JPG 等格式的实际图像数据，仅创建空纹理对象。
|