XCEngine/docs/api/rhi/d3d12/d3d12-texture.md

# D3D12Texture

DirectX 12 纹理的 D3D12 实现，封装了 `ID3D12Resource` (texture 类型)。

## 头文件

```cpp
#include <XCEngine/RHI/D3D12/D3D12Texture.h>
```

## 继承关系

```
RHITexture (interface)
└── D3D12Texture (implementation)
```

## 公共成员函数

### 构造函数与析构函数

#### `D3D12Texture()`
默认构造函数。

#### `~D3D12Texture() override`
析构函数，确保调用 `Shutdown()`。

### 初始化

#### `bool Initialize(ID3D12Device* device, const D3D12_RESOURCE_DESC& desc, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON)`
使用资源描述创建纹理。
- `device`: D3D12 设备
- `desc`: D3D12 资源描述
- `initialState`: 初始资源状态
- 返回: 初始化是否成功

#### `bool InitializeFromExisting(ID3D12Resource* resource)`
从现有 `ID3D12Resource` 初始化。

#### `bool InitializeFromData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* pixelData, uint32_t width, uint32_t height, DXGI_FORMAT format)`
创建纹理并从像素数据初始化。
- `device`: D3D12 设备
- `commandList`: 命令列表
- `pixelData`: 像素数据指针
- `width` / `height`: 纹理尺寸
- `format`: 像素格式
- 返回: 初始化是否成功

#### `bool InitializeDepthStencil(ID3D12Device* device, uint32_t width, uint32_t height, DXGI_FORMAT format = DXGI_FORMAT_D24_UNORM_S8_UINT)`
创建深度模板纹理。
- `device`: D3D12 设备
- `width` / `height`: 纹理尺寸
- `format`: 深度格式 (D16, D24S8, D32F)
- 返回: 初始化是否成功

#### `void Shutdown() override`
释放纹理资源。

### 资源信息

#### `ID3D12Resource* GetResource() const`
获取底层 `ID3D12Resource` 指针。

#### `D3D12_RESOURCE_DESC GetDesc() const`
获取资源描述。

#### `uint32_t GetWidth() const override`
获取纹理宽度。

#### `uint32_t GetHeight() const override`
获取纹理高度。

#### `uint32_t GetDepth() const override`
获取纹理深度（3D 纹理）或数组大小。

#### `uint32_t GetMipLevels() const override`
获取 Mipmap 级别数量。

#### `uint32_t GetArraySize() const`
获取数组大小。

#### `uint64_t GetGPUAddress() const`
获取 GPU 虚拟地址。

#### `size_t GetSize() const`
获取纹理大小（字节估算）。

### 状态管理

#### `void* GetNativeHandle() override { return m_resource.Get(); }`
返回原生句柄。

#### `ResourceStates GetState() const override`
获取当前资源状态。

#### `void SetState(ResourceStates state) override`
设置资源状态。

### 接口实现

#### `Format GetFormat() const override`
获取纹理格式。

#### `TextureType GetTextureType() const override`
获取纹理类型（当前固定返回 `TextureType::Texture2D`）。

#### `const std::string& GetName() const override`
获取对象名称。

#### `void SetName(const std::string& name) override`
设置对象名称。

## 内部成员

| 成员 | 类型 | 描述 |
|------|------|------|
| `m_resource` | `ComPtr<ID3D12Resource>` | D3D12 纹理资源 |
| `m_state` | `ResourceStates` | 当前资源状态 |
| `m_name` | `std::string` | 对象名称 |

## 使用示例

### 创建 2D 纹理

```cpp
D3D12Texture texture;
D3D12_RESOURCE_DESC texDesc = {};
texDesc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D;
texDesc.Width = 1024;
texDesc.Height = 1024;
texDesc.MipLevels = 1;
texDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM;
texDesc.SampleDesc.Count = 1;
texDesc.Flags = D3D12_RESOURCE_FLAG_NONE;

texture.Initialize(device->GetDevice(), texDesc);
```

### 创建深度模板纹理

```cpp
D3D12Texture depthTexture;
depthTexture.InitializeDepthStencil(
    device->GetDevice(),
    1920, 1080,
    DXGI_FORMAT_D24_UNORM_S8_UINT);
```

### 创建并初始化纹理数据

```cpp
D3D12Texture texture;
std::vector<uint8_t> pixels(width * height * 4);
FillPixelData(pixels.data(), width, height);

texture.InitializeFromData(
    device->GetDevice(),
    cmdList->GetCommandList(),
    pixels.data(),
    width, height,
    DXGI_FORMAT_R8G8B8A8_UNORM);
```

## 备注

- 纹理通常创建在 `D3D12_HEAP_TYPE_DEFAULT` 堆上
- 需要上传数据时，先创建 UPLOAD 堆缓冲区，再通过命令列表复制
- 深度纹理需要设置 `D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL`
- 渲染目标纹理需要设置 `D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET`