170 lines
4.2 KiB
Markdown
170 lines
4.2 KiB
Markdown
# 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`
|