Classes
class	Allocation
	Represents single memory allocation. More...

struct	ALLOCATION_CALLBACKS
	Custom callbacks to CPU memory allocation functions. More...

struct	ALLOCATION_DESC
	Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource. More...

class	Allocator
	Represents main object of this library initialized for particular `ID3D12Device`. More...

struct	ALLOCATOR_DESC
	Parameters of created Allocator object. To be used with CreateAllocator(). More...

struct	Budget
	Statistics of current memory usage and available budget for a specific memory segment group. More...

struct	DEFRAGMENTATION_DESC
	Parameters for defragmentation. More...

struct	DEFRAGMENTATION_MOVE
	Single move of an allocation to be done for defragmentation. More...

struct	DEFRAGMENTATION_PASS_MOVE_INFO
	Parameters for incremental defragmentation steps. More...

struct	DEFRAGMENTATION_STATS
	Statistics returned for defragmentation process by function DefragmentationContext::GetStats(). More...

class	DefragmentationContext
	Represents defragmentation process in progress. More...

struct	DetailedStatistics
	More detailed statistics than D3D12MA::Statistics. More...

class	Pool
	Custom memory pool. More...

struct	POOL_DESC
	Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool. More...

struct	Statistics
	Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group, custom pool, or total. More...

struct	TotalStatistics
	General statistics from current state of the allocator - total memory usage across all memory heaps and segments. More...

struct	VIRTUAL_ALLOCATION_DESC
	Parameters of created virtual allocation to be passed to VirtualBlock::Allocate(). More...

struct	VIRTUAL_ALLOCATION_INFO
	Parameters of an existing virtual allocation, returned by VirtualBlock::GetAllocationInfo(). More...

struct	VIRTUAL_BLOCK_DESC
	Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock(). More...

struct	VirtualAllocation
	Represents single memory allocation done inside VirtualBlock. More...

class	VirtualBlock
	Represents pure allocation algorithm and a data structure with allocations in some memory block, without actually allocating any GPU memory. More...

Typedefs
typedef UINT64	AllocHandle
	Unique identifier of single allocation done inside the memory heap.

using	ALLOCATE_FUNC_PTR = void* ()(size_t Size, size_t Alignment, void pPrivateData)
	Pointer to custom callback function that allocates CPU memory.

using	FREE_FUNC_PTR = void ()(void pMemory, void* pPrivateData)
	Pointer to custom callback function that deallocates CPU memory.

Enumerations
enum	ALLOCATION_FLAGS { ALLOCATION_FLAG_NONE = 0 , ALLOCATION_FLAG_COMMITTED = 0x1 , ALLOCATION_FLAG_NEVER_ALLOCATE = 0x2 , ALLOCATION_FLAG_WITHIN_BUDGET = 0x4 , ALLOCATION_FLAG_UPPER_ADDRESS = 0x8 , ALLOCATION_FLAG_CAN_ALIAS = 0x10 , ALLOCATION_FLAG_STRATEGY_MIN_MEMORY = 0x00010000 , ALLOCATION_FLAG_STRATEGY_MIN_TIME = 0x00020000 , ALLOCATION_FLAG_STRATEGY_MIN_OFFSET = 0x0004000 , ALLOCATION_FLAG_STRATEGY_BEST_FIT = ALLOCATION_FLAG_STRATEGY_MIN_MEMORY , ALLOCATION_FLAG_STRATEGY_FIRST_FIT = ALLOCATION_FLAG_STRATEGY_MIN_TIME , ALLOCATION_FLAG_STRATEGY_MASK }
	Bit flags to be used with ALLOCATION_DESC::Flags. More...

enum	DEFRAGMENTATION_FLAGS { DEFRAGMENTATION_FLAG_ALGORITHM_FAST = 0x1 , DEFRAGMENTATION_FLAG_ALGORITHM_BALANCED = 0x2 , DEFRAGMENTATION_FLAG_ALGORITHM_FULL = 0x4 , DEFRAGMENTATION_FLAG_ALGORITHM_MASK }
	Flags to be passed as DEFRAGMENTATION_DESC::Flags. More...

enum	DEFRAGMENTATION_MOVE_OPERATION { DEFRAGMENTATION_MOVE_OPERATION_COPY = 0 , DEFRAGMENTATION_MOVE_OPERATION_IGNORE = 1 , DEFRAGMENTATION_MOVE_OPERATION_DESTROY = 2 }
	Operation performed on single defragmentation move. More...

enum	POOL_FLAGS { POOL_FLAG_NONE = 0 , POOL_FLAG_ALGORITHM_LINEAR = 0x1 , POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED = 0x2 , POOL_FLAG_ALGORITHM_MASK = POOL_FLAG_ALGORITHM_LINEAR }
	Bit flags to be used with POOL_DESC::Flags. More...

enum	ALLOCATOR_FLAGS { ALLOCATOR_FLAG_NONE = 0 , ALLOCATOR_FLAG_SINGLETHREADED = 0x1 , ALLOCATOR_FLAG_ALWAYS_COMMITTED = 0x2 , ALLOCATOR_FLAG_DEFAULT_POOLS_NOT_ZEROED = 0x4 , ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED = 0x8 , ALLOCATOR_FLAG_DONT_PREFER_SMALL_BUFFERS_COMMITTED = 0x10 }
	Bit flags to be used with ALLOCATOR_DESC::Flags. More...

enum	VIRTUAL_BLOCK_FLAGS { VIRTUAL_BLOCK_FLAG_NONE = 0 , VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR = POOL_FLAG_ALGORITHM_LINEAR , VIRTUAL_BLOCK_FLAG_ALGORITHM_MASK = POOL_FLAG_ALGORITHM_MASK }
	Bit flags to be used with VIRTUAL_BLOCK_DESC::Flags. More...

enum	VIRTUAL_ALLOCATION_FLAGS { VIRTUAL_ALLOCATION_FLAG_NONE = 0 , VIRTUAL_ALLOCATION_FLAG_UPPER_ADDRESS = ALLOCATION_FLAG_UPPER_ADDRESS , VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_MEMORY = ALLOCATION_FLAG_STRATEGY_MIN_MEMORY , VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_TIME = ALLOCATION_FLAG_STRATEGY_MIN_TIME , VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_OFFSET = ALLOCATION_FLAG_STRATEGY_MIN_OFFSET , VIRTUAL_ALLOCATION_FLAG_STRATEGY_MASK = ALLOCATION_FLAG_STRATEGY_MASK }
	Bit flags to be used with VIRTUAL_ALLOCATION_DESC::Flags. More...

Functions
D3D12MA_API HRESULT	CreateAllocator (const ALLOCATOR_DESC pDesc, Allocator *ppAllocator)
	Creates new main D3D12MA::Allocator object and returns it through `ppAllocator`.

D3D12MA_API HRESULT	CreateVirtualBlock (const VIRTUAL_BLOCK_DESC pDesc, VirtualBlock *ppVirtualBlock)
	Creates new D3D12MA::VirtualBlock object and returns it through `ppVirtualBlock`.

Typedef Documentation

◆ ALLOCATE_FUNC_PTR

using D3D12MA::ALLOCATE_FUNC_PTR = void* (*)(size_t Size, size_t Alignment, void* pPrivateData)

Pointer to custom callback function that allocates CPU memory.

◆ AllocHandle

typedef UINT64 D3D12MA::AllocHandle

Unique identifier of single allocation done inside the memory heap.

◆ FREE_FUNC_PTR

using D3D12MA::FREE_FUNC_PTR = void (*)(void* pMemory, void* pPrivateData)

Pointer to custom callback function that deallocates CPU memory.

pMemory = null should be accepted and ignored.

Enumeration Type Documentation

◆ ALLOCATION_FLAGS

enum D3D12MA::ALLOCATION_FLAGS

Bit flags to be used with ALLOCATION_DESC::Flags.

Enumerator
ALLOCATION_FLAG_NONE	Zero.
ALLOCATION_FLAG_COMMITTED	Set this flag if the allocation should have its own dedicated memory allocation (committed resource with implicit heap). Use it for special, big resources, like fullscreen textures used as render targets. When used with functions like D3D12MA::Allocator::CreateResource, it will use `ID3D12Device::CreateCommittedResource`, so the created allocation will contain a resource (D3D12MA::Allocation::GetResource() `!= NULL`) but will not have a heap (D3D12MA::Allocation::GetHeap() `== NULL`), as the heap is implicit. When used with raw memory allocation like D3D12MA::Allocator::AllocateMemory, it will use `ID3D12Device::CreateHeap`, so the created allocation will contain a heap (D3D12MA::Allocation::GetHeap() `!= NULL`) and its offset will always be 0.
ALLOCATION_FLAG_NEVER_ALLOCATE	Set this flag to only try to allocate from existing memory heaps and never create new such heap. If new allocation cannot be placed in any of the existing heaps, allocation fails with `E_OUTOFMEMORY` error. You should not use D3D12MA::ALLOCATION_FLAG_COMMITTED and D3D12MA::ALLOCATION_FLAG_NEVER_ALLOCATE at the same time. It makes no sense.
ALLOCATION_FLAG_WITHIN_BUDGET	Create allocation only if additional memory required for it, if any, won't exceed memory budget. Otherwise return `E_OUTOFMEMORY`.
ALLOCATION_FLAG_UPPER_ADDRESS	Allocation will be created from upper stack in a double stack pool. This flag is only allowed for custom pools created with POOL_FLAG_ALGORITHM_LINEAR flag.
ALLOCATION_FLAG_CAN_ALIAS	Set this flag if the allocated memory will have aliasing resources. Use this when calling D3D12MA::Allocator::CreateResource() and similar to guarantee creation of explicit heap for desired allocation and prevent it from using `CreateCommittedResource`, so that new allocation object will always have `allocation->GetHeap() != NULL`.
ALLOCATION_FLAG_STRATEGY_MIN_MEMORY	Allocation strategy that chooses smallest possible free range for the allocation to minimize memory usage and fragmentation, possibly at the expense of allocation time.
ALLOCATION_FLAG_STRATEGY_MIN_TIME	Allocation strategy that chooses first suitable free range for the allocation - not necessarily in terms of the smallest offset but the one that is easiest and fastest to find to minimize allocation time, possibly at the expense of allocation quality.
ALLOCATION_FLAG_STRATEGY_MIN_OFFSET	Allocation strategy that chooses always the lowest offset in available space. This is not the most efficient strategy but achieves highly packed data. Used internally by defragmentation, not recomended in typical usage.
ALLOCATION_FLAG_STRATEGY_BEST_FIT	Alias to ALLOCATION_FLAG_STRATEGY_MIN_MEMORY.
ALLOCATION_FLAG_STRATEGY_FIRST_FIT	Alias to ALLOCATION_FLAG_STRATEGY_MIN_TIME.
ALLOCATION_FLAG_STRATEGY_MASK	A bit mask to extract only `STRATEGY` bits from entire set of flags.

◆ ALLOCATOR_FLAGS

enum D3D12MA::ALLOCATOR_FLAGS

Bit flags to be used with ALLOCATOR_DESC::Flags.

Enumerator
ALLOCATOR_FLAG_NONE	Zero.
ALLOCATOR_FLAG_SINGLETHREADED	Allocator and all objects created from it will not be synchronized internally, so you must guarantee they are used from only one thread at a time or synchronized by you. Using this flag may increase performance because internal mutexes are not used.
ALLOCATOR_FLAG_ALWAYS_COMMITTED	Every allocation will have its own memory block. To be used for debugging purposes.
ALLOCATOR_FLAG_DEFAULT_POOLS_NOT_ZEROED	Heaps created for the default pools will be created with flag `D3D12_HEAP_FLAG_CREATE_NOT_ZEROED`, allowing for their memory to be not zeroed by the system if possible, which can speed up allocation. Only affects default pools. To use the flag with Custom memory pools, you need to add it manually: poolDesc.heapFlags \|= D3D12_HEAP_FLAG_CREATE_NOT_ZEROED; Only avaiable if `ID3D12Device8` is present. Otherwise, the flag is ignored.
ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED	Optimization, allocate MSAA textures as committed resources always. Specify this flag to create MSAA textures with implicit heaps, as if they were created with flag D3D12MA::ALLOCATION_FLAG_COMMITTED. Usage of this flags enables all default pools to create its heaps on smaller alignment not suitable for MSAA textures.
ALLOCATOR_FLAG_DONT_PREFER_SMALL_BUFFERS_COMMITTED	Disable optimization that prefers creating small buffers as committed to avoid 64 KB alignment. By default, the library prefers creating small buffers <= 32 KB as committed, because drivers tend to pack them better, while placed buffers require 64 KB alignment. This, however, may decrease performance, as creating committed resources involves allocation of implicit heaps, which may take longer than creating placed resources in existing heaps. Passing this flag will disable this committed preference globally for the allocator. It can also be disabled for a single allocation by using ALLOCATION_FLAG_STRATEGY_MIN_TIME.

◆ DEFRAGMENTATION_FLAGS

enum D3D12MA::DEFRAGMENTATION_FLAGS

Flags to be passed as DEFRAGMENTATION_DESC::Flags.

Enumerator
DEFRAGMENTATION_FLAG_ALGORITHM_FAST	Use simple but fast algorithm for defragmentation. May not achieve best results but will require least time to compute and least allocations to copy.
DEFRAGMENTATION_FLAG_ALGORITHM_BALANCED	Default defragmentation algorithm, applied also when no `ALGORITHM` flag is specified. Offers a balance between defragmentation quality and the amount of allocations and bytes that need to be moved.
DEFRAGMENTATION_FLAG_ALGORITHM_FULL	Perform full defragmentation of memory. Can result in notably more time to compute and allocations to copy, but will achieve best memory packing.
DEFRAGMENTATION_FLAG_ALGORITHM_MASK	A bit mask to extract only `ALGORITHM` bits from entire set of flags.

◆ DEFRAGMENTATION_MOVE_OPERATION

enum D3D12MA::DEFRAGMENTATION_MOVE_OPERATION

Operation performed on single defragmentation move.

Enumerator
DEFRAGMENTATION_MOVE_OPERATION_COPY	Resource has been recreated at `pDstTmpAllocation`, data has been copied, old resource has been destroyed. `pSrcAllocation` will be changed to point to the new place. This is the default value set by DefragmentationContext::BeginPass().
DEFRAGMENTATION_MOVE_OPERATION_IGNORE	Set this value if you cannot move the allocation. New place reserved at `pDstTmpAllocation` will be freed. `pSrcAllocation` will remain unchanged.
DEFRAGMENTATION_MOVE_OPERATION_DESTROY	Set this value if you decide to abandon the allocation and you destroyed the resource. New place reserved `pDstTmpAllocation` will be freed, along with `pSrcAllocation`.

◆ POOL_FLAGS

enum D3D12MA::POOL_FLAGS

Bit flags to be used with POOL_DESC::Flags.

Enumerator
POOL_FLAG_NONE	Zero.
POOL_FLAG_ALGORITHM_LINEAR	Enables alternative, linear allocation algorithm in this pool. Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata. By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.
POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED	Optimization, allocate MSAA textures as committed resources always. Specify this flag to create MSAA textures with implicit heaps, as if they were created with flag D3D12MA::ALLOCATION_FLAG_COMMITTED. Usage of this flags enables pool to create its heaps on smaller alignment not suitable for MSAA textures.
POOL_FLAG_ALGORITHM_MASK

◆ VIRTUAL_ALLOCATION_FLAGS

enum D3D12MA::VIRTUAL_ALLOCATION_FLAGS

Bit flags to be used with VIRTUAL_ALLOCATION_DESC::Flags.

Enumerator
VIRTUAL_ALLOCATION_FLAG_NONE	Zero.
VIRTUAL_ALLOCATION_FLAG_UPPER_ADDRESS	Allocation will be created from upper stack in a double stack pool. This flag is only allowed for virtual blocks created with VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR flag.
VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_MEMORY	Allocation strategy that tries to minimize memory usage.
VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_TIME	Allocation strategy that tries to minimize allocation time.
VIRTUAL_ALLOCATION_FLAG_STRATEGY_MIN_OFFSET	Allocation strategy that chooses always the lowest offset in available space. This is not the most efficient strategy but achieves highly packed data.
VIRTUAL_ALLOCATION_FLAG_STRATEGY_MASK	A bit mask to extract only `STRATEGY` bits from entire set of flags. These strategy flags are binary compatible with equivalent flags in ALLOCATION_FLAGS.

◆ VIRTUAL_BLOCK_FLAGS

enum D3D12MA::VIRTUAL_BLOCK_FLAGS

Bit flags to be used with VIRTUAL_BLOCK_DESC::Flags.

Enumerator

VIRTUAL_BLOCK_FLAG_NONE

Zero.

VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR

Enables alternative, linear allocation algorithm in this virtual block.

Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata.

By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.

VIRTUAL_BLOCK_FLAG_ALGORITHM_MASK

Function Documentation

◆ CreateAllocator()

D3D12MA_API HRESULT D3D12MA::CreateAllocator	(	const ALLOCATOR_DESC *	pDesc,
		Allocator **	ppAllocator )

Creates new main D3D12MA::Allocator object and returns it through ppAllocator.

You normally only need to call it once and keep a single Allocator object for your ID3D12Device.

◆ CreateVirtualBlock()

D3D12MA_API HRESULT D3D12MA::CreateVirtualBlock	(	const VIRTUAL_BLOCK_DESC *	pDesc,
		VirtualBlock **	ppVirtualBlock )

Creates new D3D12MA::VirtualBlock object and returns it through ppVirtualBlock.

Note you don't need to create D3D12MA::Allocator to use virtual blocks.

Classes

Typedefs

Enumerations

Functions