Microsoft Docs

ID3D12Heap

The ID3D12Heap interface represents a contiguous memory allocation that can be used as a backing store for resources, command allocators, and other objects in Direct3D 12.

Overview
Syntax
Methods
Properties
Example

Heaps are created by calling ID3D12Device::CreateHeap. They provide flexible memory management and can be bound to multiple resources, allowing for efficient memory reuse and sub-allocation strategies.

When to use a heap

  • When you need fine‑grained control over memory placement.
  • To enable sub‑allocation patterns for many small resources.
  • When you want to share memory among multiple resources or command allocators.
struct ID3D12Heap : public ID3D12Pageable
{
    // Inherited from IUnknown
    virtual HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void **ppvObject) = 0;
    virtual ULONG   STDMETHODCALLTYPE AddRef(void) = 0;
    virtual ULONG   STDMETHODCALLTYPE Release(void) = 0;

    // Inherited from ID3D12Object
    virtual HRESULT STDMETHODCALLTYPE GetPrivateData(REFGUID guid, UINT *pDataSize, void *pData) = 0;
    virtual HRESULT STDMETHODCALLTYPE SetPrivateData(REFGUID guid, UINT DataSize, const void *pData) = 0;
    virtual HRESULT STDMETHODCALLTYPE SetPrivateDataInterface(REFGUID guid, const IUnknown *pData) = 0;
    virtual HRESULT STDMETHODCALLTYPE SetName(LPCWSTR Name) = 0;

    // Inherited from ID3D12DeviceChild
    virtual ID3D12Device* STDMETHODCALLTYPE GetDevice(REFIID riid, void **ppvDevice) = 0;

    // ID3D12Heap specific
    virtual D3D12_HEAP_DESC STDMETHODCALLTYPE GetDesc(void) = 0;
};
MethodDescription
GetDesc() Retrieves the D3D12_HEAP_DESC structure describing the heap's properties.
GetDevice() Gets the ID3D12Device that created the heap.
PropertyTypeDescription
Desc D3D12_HEAP_DESC The heap description returned by GetDesc.

Creating and using a heap

#include <d3d12.h>
#include <wrl/client.h>
using Microsoft::WRL::ComPtr;

void CreateHeapExample(ID3D12Device* device)
{
    D3D12_HEAP_DESC heapDesc = {};
    heapDesc.SizeInBytes = 64 * 1024 * 1024; // 64 MiB
    heapDesc.Properties.Type = D3D12_HEAP_TYPE_DEFAULT;
    heapDesc.Alignment = D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT;

    ComPtr<ID3D12Heap> heap;
    HRESULT hr = device->CreateHeap(&heapDesc, IID_PPV_ARGS(&heap));
    if (FAILED(hr))
    {
        // Handle error
        return;
    }

    // Create a buffer resource placed on the heap
    D3D12_RESOURCE_DESC bufferDesc = {};
    bufferDesc.Dimension = D3D12_RESOURCE_DIMENSION_BUFFER;
    bufferDesc.Alignment = 0;
    bufferDesc.Width = 1024; // 1 KB
    bufferDesc.Height = 1;
    bufferDesc.DepthOrArraySize = 1;
    bufferDesc.MipLevels = 1;
    bufferDesc.Format = DXGI_FORMAT_UNKNOWN;
    bufferDesc.SampleDesc.Count = 1;
    bufferDesc.Layout = D3D12_TEXTURE_LAYOUT_ROW_MAJOR;

    D3D12_RESOURCE_ALLOCATION_INFO allocInfo = device->GetResourceAllocationInfo(0, 1, &bufferDesc);
    D3D12_HEAP_PROPERTIES heapProps = {};
    heapProps.Type = D3D12_HEAP_TYPE_DEFAULT;

    ComPtr<ID3D12Resource> buffer;
    hr = device->CreatePlacedResource(
        heap.Get(),
        0, // offset within the heap
        &bufferDesc,
        D3D12_RESOURCE_STATE_COMMON,
        nullptr,
        IID_PPV_ARGS(&buffer));
    // Use the buffer...
}