Configuration

Please check file D3D12MemAlloc.cpp lines between "Configuration Begin" and "Configuration End" to find macros that you can define to change the behavior of the library, primarily for debugging purposes.

Custom CPU memory allocator

If you use custom allocator for CPU memory rather than default C++ operator new and delete or malloc and free functions, you can make this library using your allocator as well by filling structure D3D12MA::ALLOCATION_CALLBACKS and passing it as optional member D3D12MA::ALLOCATOR_DESC::pAllocationCallbacks. Functions pointed there will be used by the library to make any CPU-side allocations. Example:

#include <malloc.h>
 
void* CustomAllocate(size_t Size, size_t Alignment, void* pPrivateData)
{
    void* memory = _aligned_malloc(Size, Alignment);
    // Your extra bookkeeping here...
    return memory;
}
 
void CustomFree(void* pMemory, void* pPrivateData)
{
    // Your extra bookkeeping here...
    _aligned_free(pMemory);
}
 
(...)
 
D3D12MA::ALLOCATION_CALLBACKS allocationCallbacks = {};
allocationCallbacks.pAllocate = &CustomAllocate;
allocationCallbacks.pFree = &CustomFree;
 
D3D12MA::ALLOCATOR_DESC allocatorDesc = {};
allocatorDesc.pDevice = device;
allocatorDesc.pAdapter = adapter;
allocatorDesc.pAllocationCallbacks = &allocationCallbacks;
 
D3D12MA::Allocator* allocator;
HRESULT hr = D3D12MA::CreateAllocator(&allocatorDesc, &allocator);

Debug margins

By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment returned by ID3D12Device::GetResourceAllocationInfo).

Define macro D3D12MA_DEBUG_MARGIN to some non-zero value (e.g. 16) inside "D3D12MemAlloc.cpp" to enforce specified number of bytes as a margin after every allocation.

If your bug goes away after enabling margins, it means it may be caused by memory being overwritten outside of allocation boundaries. It is not 100% certain though. Change in application behavior may also be caused by different order and distribution of allocations across memory blocks after margins are applied.

Margins work with all memory heap types.

Margin is applied only to placed allocations made out of memory heaps and not to committed allocations, which have their own, implicit memory heap of specific size. It is thus not applied to allocations made using D3D12MA::ALLOCATION_FLAG_COMMITTED flag or those automatically decided to put into committed allocations, e.g. due to its large size.

Margins appear in JSON dump as part of free space.

Note that enabling margins increases memory usage and fragmentation.

Margins do not apply to Virtual allocator.