Custom memory pools

A "pool" is a collection of memory blocks that share certain properties. Allocator creates 3 default pools: for D3D12_HEAP_TYPE_DEFAULT, UPLOAD, READBACK. A default pool automatically grows in size. Size of allocated blocks is also variable and managed automatically. Typical allocations are created in these pools. You can also create custom pools.

Usage

To create a custom pool, fill in structure D3D12MA::POOL_DESC and call function D3D12MA::Allocator::CreatePool to obtain object D3D12MA::Pool. Example:

POOL_DESC poolDesc = {};
poolDesc.HeapProperties.Type = D3D12_HEAP_TYPE_DEFAULT;
 
Pool* pool;
HRESULT hr = allocator->CreatePool(&poolDesc, &pool);

To allocate resources out of a custom pool, only set member D3D12MA::ALLOCATION_DESC::CustomPool. Example:

ALLOCATION_DESC allocDesc = {};
allocDesc.CustomPool = pool;
 
D3D12_RESOURCE_DESC resDesc = ...
Allocation* alloc;
hr = allocator->CreateResource(&allocDesc, &resDesc,
    D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &alloc, IID_NULL, NULL);

All allocations must be released before releasing the pool. The pool must be released before relasing the allocator.

alloc->Release();
pool->Release();

Features and benefits

While it is recommended to use default pools whenever possible for simplicity and to give the allocator more opportunities for internal optimizations, custom pools may be useful in following cases:

• To keep some resources separate from others in memory.
• To keep track of memory usage of just a specific group of resources. Statistics can be queried using D3D12MA::Pool::CalculateStatistics.
• To use specific size of a memory block (ID3D12Heap). To set it, use member D3D12MA::POOL_DESC::BlockSize. When set to 0, the library uses automatically determined, variable block sizes.
• To reserve some minimum amount of memory allocated. To use it, set member D3D12MA::POOL_DESC::MinBlockCount.
• To limit maximum amount of memory allocated. To use it, set member D3D12MA::POOL_DESC::MaxBlockCount.
• To use extended parameters of the D3D12 memory allocation. While resources created from default pools can only specify D3D12_HEAP_TYPE_DEFAULT, UPLOAD, READBACK, a custom pool may use non-standard D3D12_HEAP_PROPERTIES (member D3D12MA::POOL_DESC::HeapProperties) and D3D12_HEAP_FLAGS (D3D12MA::POOL_DESC::HeapFlags), which is useful e.g. for cross-adapter sharing or UMA (see also D3D12MA::Allocator::IsUMA).

New versions of this library support creating committed allocations in custom pools. It is supported only when D3D12MA::POOL_DESC::BlockSize = 0. To use this feature, set D3D12MA::ALLOCATION_DESC::CustomPool to the pointer to your custom pool and D3D12MA::ALLOCATION_DESC::Flags to D3D12MA::ALLOCATION_FLAG_COMMITTED. Example:

ALLOCATION_DESC allocDesc = {};
allocDesc.CustomPool = pool;
allocDesc.Flags = ALLOCATION_FLAG_COMMITTED;
 
D3D12_RESOURCE_DESC resDesc = ...
Allocation* alloc;
ID3D12Resource* res;
hr = allocator->CreateResource(&allocDesc, &resDesc,
    D3D12_RESOURCE_STATE_GENERIC_READ, NULL, &alloc, IID_PPV_ARGS(&res));

This feature may seem unnecessary, but creating committed allocations from custom pools may be useful in some cases, e.g. to have separate memory usage statistics for some group of resources or to use extended allocation parameters, like custom D3D12_HEAP_PROPERTIES, which are available only in custom pools.