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

D3D12Texture

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

头文件

#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 纹理

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);

创建深度模板纹理

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

创建并初始化纹理数据

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