Direct3D 12 Memory Allocator
Loading...
Searching...
No Matches
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);
Represents main object of this library initialized for particular ID3D12Device.
Definition: D3D12MemAlloc.h:1067
D3D12MA_API HRESULT CreateAllocator(const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator)
Creates new main D3D12MA::Allocator object and returns it through ppAllocator.
Custom callbacks to CPU memory allocation functions.
Definition: D3D12MemAlloc.h:188
FREE_FUNC_PTR pFree
Dellocation function.
Definition: D3D12MemAlloc.h:192
ALLOCATE_FUNC_PTR pAllocate
Allocation function.
Definition: D3D12MemAlloc.h:190
Parameters of created Allocator object. To be used with CreateAllocator().
Definition: D3D12MemAlloc.h:1028
const ALLOCATION_CALLBACKS * pAllocationCallbacks
Custom CPU memory allocation callbacks. Optional.
Definition: D3D12MemAlloc.h:1048
IDXGIAdapter * pAdapter
Definition: D3D12MemAlloc.h:1054
ID3D12Device * pDevice
Definition: D3D12MemAlloc.h:1036

Debug margins

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

Allocations without margin

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.

Allocations with margin

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.