XCEngine/docs/api/rhi/d3d12/d3d12-descriptor-heap.md

D3D12DescriptorHeap

DirectX 12 描述符堆的 D3D12 实现，封装了 ID3D12DescriptorHeap。

头文件

#include <XCEngine/RHI/D3D12/D3D12DescriptorHeap.h>

继承关系

RHIDescriptorPool (interface)
└── D3D12DescriptorHeap (implementation)

公共成员函数

构造函数与析构函数

D3D12DescriptorHeap()

默认构造函数。

~D3D12DescriptorHeap() override

析构函数，确保调用 Shutdown()。

初始化

bool Initialize(ID3D12Device* device, DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false)

使用参数初始化。

• device: D3D12 设备
• type: 描述符堆类型
• numDescriptors: 描述符数量
• shaderVisible: 是否对 GPU 可见（CBV_SRV_UAV 和 Sampler 堆需要）
• 返回: 初始化是否成功

bool Initialize(const DescriptorPoolDesc& desc) override

使用统一描述符初始化。

void Shutdown() override

释放描述符堆。

描述符句柄

ID3D12DescriptorHeap* GetDescriptorHeap() const

获取底层 ID3D12DescriptorHeap 指针。

CPUDescriptorHandle GetCPUDescriptorHandle(uint32_t index)

获取指定索引的 CPU 描述符句柄。

GPUDescriptorHandle GetGPUDescriptorHandle(uint32_t index)

获取指定索引的 GPU 描述符句柄。

D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const

获取堆起始 CPU 句柄。

D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const

获取堆起始 GPU 句柄。

属性

uint32_t GetDescriptorCount() const override

获取描述符总数。

DescriptorHeapType GetType() const override

获取描述符堆类型。

uint32_t GetDescriptorSize() const

获取单个描述符大小（增量大小）。

void* GetNativeHandle() override

返回原生句柄。

静态辅助函数

static D3D12_DESCRIPTOR_HEAP_DESC CreateDesc(DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false)

创建 D3D12 描述符堆描述。

内部成员

成员	类型	描述
m_descriptorHeap	ComPtr<ID3D12DescriptorHeap>	D3D12 描述符堆
m_type	DescriptorHeapType	堆类型
m_numDescriptors	uint32_t	描述符数量
m_descriptorSize	uint32_t	增量大小
m_shaderVisible	bool	是否 shader visible

使用示例

// Create RTV heap
D3D12DescriptorHeap rtvHeap;
rtvHeap.Initialize(device->GetDevice(), DescriptorHeapType::RTV, 10, false);

// Create SRV/CBV/UAV heap
D3D12DescriptorHeap cbvHeap;
cbvHeap.Initialize(device->GetDevice(), DescriptorHeapType::CBV_SRV_UAV, 100, true);

// Get handle for creating views
D3D12_CPU_DESCRIPTOR_HANDLE rtvHandle = rtvHeap.GetCPUDescriptorHandle(0);

// Create RTV
D3D12RenderTargetView rtv;
rtv.InitializeAt(device->GetDevice(), texture->GetResource(), rtvHandle, nullptr);

备注

• 四种描述符堆类型: CBV_SRV_UAV, Sampler, RTV, DSV
• RTV 和 DSV 堆通常不需要 shader visible
• CBV_SRV_UAV 和 Sampler 堆如需在 shader 中访问必须 shader visible
• 描述符堆创建后大小固定，不能调整