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

#include <D3D12MemAlloc.h>

Inheritance diagram for D3D12MA::Allocator:

Public Member Functions
const D3D12_FEATURE_DATA_D3D12_OPTIONS &	GetD3D12Options () const
	Returns cached options retrieved from D3D12 device.

BOOL	IsUMA () const
	Returns true if `D3D12_FEATURE_DATA_ARCHITECTURE1::UMA` was found to be true.

BOOL	IsCacheCoherentUMA () const
	Returns true if `D3D12_FEATURE_DATA_ARCHITECTURE1::CacheCoherentUMA` was found to be true.

BOOL	IsGPUUploadHeapSupported () const
	Returns true if GPU Upload Heaps are supported on the current system.

UINT64	GetMemoryCapacity (UINT memorySegmentGroup) const
	Returns total amount of memory of specific segment group, in bytes.

HRESULT	CreateResource (const ALLOCATION_DESC pAllocDesc, const D3D12_RESOURCE_DESC pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE pOptimizedClearValue, Allocation ppAllocation, REFIID riidResource, void *ppvResource)
	Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation function.

HRESULT	CreateResource2 (const ALLOCATION_DESC pAllocDesc, const D3D12_RESOURCE_DESC1 pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE pOptimizedClearValue, Allocation ppAllocation, REFIID riidResource, void *ppvResource)
	Similar to Allocator::CreateResource, but supports new structure `D3D12_RESOURCE_DESC1`.

HRESULT	CreateResource3 (const ALLOCATION_DESC pAllocDesc, const D3D12_RESOURCE_DESC1 pResourceDesc, D3D12_BARRIER_LAYOUT InitialLayout, const D3D12_CLEAR_VALUE pOptimizedClearValue, UINT32 NumCastableFormats, DXGI_FORMAT pCastableFormats, Allocation ppAllocation, REFIID riidResource, void ppvResource)
	Similar to Allocator::CreateResource2, but there are initial layout instead of state and castable formats list.

HRESULT	AllocateMemory (const ALLOCATION_DESC pAllocDesc, const D3D12_RESOURCE_ALLOCATION_INFO pAllocInfo, Allocation **ppAllocation)
	Allocates memory without creating any resource placed in it.

HRESULT	CreateAliasingResource (Allocation pAllocation, UINT64 AllocationLocalOffset, const D3D12_RESOURCE_DESC pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE pOptimizedClearValue, REFIID riidResource, void *ppvResource)
	Creates a new resource in place of an existing allocation. This is useful for memory aliasing.

HRESULT	CreateAliasingResource1 (Allocation pAllocation, UINT64 AllocationLocalOffset, const D3D12_RESOURCE_DESC1 pResourceDesc, D3D12_RESOURCE_STATES InitialResourceState, const D3D12_CLEAR_VALUE pOptimizedClearValue, REFIID riidResource, void *ppvResource)
	Similar to Allocator::CreateAliasingResource, but supports new structure `D3D12_RESOURCE_DESC1`.

HRESULT	CreateAliasingResource2 (Allocation pAllocation, UINT64 AllocationLocalOffset, const D3D12_RESOURCE_DESC1 pResourceDesc, D3D12_BARRIER_LAYOUT InitialLayout, const D3D12_CLEAR_VALUE pOptimizedClearValue, UINT32 NumCastableFormats, DXGI_FORMAT pCastableFormats, REFIID riidResource, void **ppvResource)
	Similar to Allocator::CreateAliasingResource1, but there are initial layout instead of state and castable formats list.

HRESULT	CreatePool (const POOL_DESC pPoolDesc, Pool *ppPool)
	Creates custom pool.

void	SetCurrentFrameIndex (UINT frameIndex)
	Sets the index of the current frame.

void	GetBudget (Budget pLocalBudget, Budget pNonLocalBudget)
	Retrieves information about current memory usage and budget.

void	CalculateStatistics (TotalStatistics *pStats)
	Retrieves statistics from current state of the allocator.

void	BuildStatsString (WCHAR **ppStatsString, BOOL DetailedMap) const
	Builds and returns statistics as a string in JSON format.

void	FreeStatsString (WCHAR *pStatsString) const
	Frees memory of a string returned from Allocator::BuildStatsString.

void	BeginDefragmentation (const DEFRAGMENTATION_DESC pDesc, DefragmentationContext *ppContext)
	Begins defragmentation process of the default pools.

Detailed Description

Represents main object of this library initialized for particular ID3D12Device.

Fill structure D3D12MA::ALLOCATOR_DESC and call function CreateAllocator() to create it. Call method Release() to destroy it.

It is recommended to create just one object of this type per ID3D12Device object, right after Direct3D 12 is initialized and keep it alive until before Direct3D device is destroyed.

Member Function Documentation

◆ AllocateMemory()

HRESULT D3D12MA::Allocator::AllocateMemory	(	const ALLOCATION_DESC *	pAllocDesc,
		const D3D12_RESOURCE_ALLOCATION_INFO *	pAllocInfo,
		Allocation **	ppAllocation )

Allocates memory without creating any resource placed in it.

This function is similar to ID3D12Device::CreateHeap, but it may really assign part of a larger, existing heap to the allocation.

pAllocDesc->heapFlags should contain one of these values, depending on type of resources you are going to create in this memory: D3D12_HEAP_FLAG_ALLOW_ONLY_BUFFERS, D3D12_HEAP_FLAG_ALLOW_ONLY_NON_RT_DS_TEXTURES, D3D12_HEAP_FLAG_ALLOW_ONLY_RT_DS_TEXTURES. Except if you validate that ResourceHeapTier = 2 - then heapFlags may be D3D12_HEAP_FLAG_ALLOW_ALL_BUFFERS_AND_TEXTURES = 0. Additional flags in heapFlags are allowed as well.

pAllocInfo->SizeInBytes must be multiply of 64KB. pAllocInfo->Alignment must be one of the legal values as described in documentation of D3D12_HEAP_DESC.

If you use D3D12MA::ALLOCATION_FLAG_COMMITTED you will get a separate memory block - a heap that always has offset 0.

◆ BeginDefragmentation()

void D3D12MA::Allocator::BeginDefragmentation	(	const DEFRAGMENTATION_DESC *	pDesc,
		DefragmentationContext **	ppContext )

Begins defragmentation process of the default pools.

Parameters

	pDesc	Structure filled with parameters of defragmentation.
[out]	ppContext	Context object that will manage defragmentation.

For more information about defragmentation, see documentation chapter: Defragmentation.

◆ BuildStatsString()

void D3D12MA::Allocator::BuildStatsString	(	WCHAR **	ppStatsString,
		BOOL	DetailedMap ) const

Builds and returns statistics as a string in JSON format.

Parameters

[out]	ppStatsString	Must be freed using Allocator::FreeStatsString.
	DetailedMap	`TRUE` to include full list of allocations (can make the string quite long), `FALSE` to only return statistics.

◆ CalculateStatistics()

void D3D12MA::Allocator::CalculateStatistics ( TotalStatistics * pStats )

Retrieves statistics from current state of the allocator.

This function is called "calculate" not "get" because it has to traverse all internal data structures, so it may be quite slow. Use it for debugging purposes. For faster but more brief statistics suitable to be called every frame or every allocation, use GetBudget().

Note that when using allocator from multiple threads, returned information may immediately become outdated.

◆ CreateAliasingResource()

HRESULT D3D12MA::Allocator::CreateAliasingResource	(	Allocation *	pAllocation,
		UINT64	AllocationLocalOffset,
		const D3D12_RESOURCE_DESC *	pResourceDesc,
		D3D12_RESOURCE_STATES	InitialResourceState,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		REFIID	riidResource,
		void **	ppvResource )

Creates a new resource in place of an existing allocation. This is useful for memory aliasing.

Parameters

	pAllocation	Existing allocation indicating the memory where the new resource should be created. It can be created using D3D12MA::Allocator::CreateResource and already have a resource bound to it, or can be a raw memory allocated with D3D12MA::Allocator::AllocateMemory. It must not be created as committed so that `ID3D12Heap` is available and not implicit.
	AllocationLocalOffset	Additional offset in bytes to be applied when allocating the resource. Local from the start of `pAllocation`, not the beginning of the whole `ID3D12Heap`! If the new resource should start from the beginning of the `pAllocation` it should be 0.
	pResourceDesc	Description of the new resource to be created.
	InitialResourceState
	pOptimizedClearValue
	riidResource
[out]	ppvResource	Returns pointer to the new resource. The resource is not bound with `pAllocation`. This pointer must not be null - you must get the resource pointer and `Release` it when no longer needed.

Memory requirements of the new resource are checked for validation. If its size exceeds the end of pAllocation or required alignment is not fulfilled considering pAllocation->GetOffset() + AllocationLocalOffset, the function returns E_INVALIDARG.

◆ CreateAliasingResource1()

HRESULT D3D12MA::Allocator::CreateAliasingResource1	(	Allocation *	pAllocation,
		UINT64	AllocationLocalOffset,
		const D3D12_RESOURCE_DESC1 *	pResourceDesc,
		D3D12_RESOURCE_STATES	InitialResourceState,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		REFIID	riidResource,
		void **	ppvResource )

Similar to Allocator::CreateAliasingResource, but supports new structure D3D12_RESOURCE_DESC1.

It internally uses ID3D12Device8::CreatePlacedResource1.

To work correctly, ID3D12Device8 interface must be available in the current system. Otherwise, E_NOINTERFACE is returned.

◆ CreateAliasingResource2()

HRESULT D3D12MA::Allocator::CreateAliasingResource2	(	Allocation *	pAllocation,
		UINT64	AllocationLocalOffset,
		const D3D12_RESOURCE_DESC1 *	pResourceDesc,
		D3D12_BARRIER_LAYOUT	InitialLayout,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		UINT32	NumCastableFormats,
		DXGI_FORMAT *	pCastableFormats,
		REFIID	riidResource,
		void **	ppvResource )

Similar to Allocator::CreateAliasingResource1, but there are initial layout instead of state and castable formats list.

It internally uses ID3D12Device10::CreatePlacedResource2.

To work correctly, ID3D12Device10 interface must be available in the current system. Otherwise, E_NOINTERFACE is returned.

◆ CreatePool()

HRESULT D3D12MA::Allocator::CreatePool	(	const POOL_DESC *	pPoolDesc,
		Pool **	ppPool )

Creates custom pool.

◆ CreateResource()

HRESULT D3D12MA::Allocator::CreateResource	(	const ALLOCATION_DESC *	pAllocDesc,
		const D3D12_RESOURCE_DESC *	pResourceDesc,
		D3D12_RESOURCE_STATES	InitialResourceState,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		Allocation **	ppAllocation,
		REFIID	riidResource,
		void **	ppvResource )

Allocates memory and creates a D3D12 resource (buffer or texture). This is the main allocation function.

The function is similar to ID3D12Device::CreateCommittedResource, but it may really call ID3D12Device::CreatePlacedResource to assign part of a larger, existing memory heap to the new resource, which is the main purpose of this whole library.

If ppvResource is null, you receive only ppAllocation object from this function. It holds pointer to ID3D12Resource that can be queried using function D3D12MA::Allocation::GetResource(). Reference count of the resource object is 1. It is automatically destroyed when you destroy the allocation object.

If ppvResource is not null, you receive pointer to the resource next to allocation object. Reference count of the resource object is then increased by calling QueryInterface, so you need to manually Release it along with the allocation.

Parameters

	pAllocDesc	Parameters of the allocation.
	pResourceDesc	Description of created resource.
	InitialResourceState	Initial resource state.
	pOptimizedClearValue	Optional. Either null or optimized clear value.
[out]	ppAllocation	Filled with pointer to new allocation object created.
	riidResource	IID of a resource to be returned via `ppvResource`.
[out]	ppvResource	Optional. If not null, filled with pointer to new resouce created.

Note: This function creates a new resource. Sub-allocation of parts of one large buffer, although recommended as a good practice, is out of scope of this library and could be implemented by the user as a higher-level logic on top of it, e.g. using the Virtual allocator feature.

◆ CreateResource2()

HRESULT D3D12MA::Allocator::CreateResource2	(	const ALLOCATION_DESC *	pAllocDesc,
		const D3D12_RESOURCE_DESC1 *	pResourceDesc,
		D3D12_RESOURCE_STATES	InitialResourceState,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		Allocation **	ppAllocation,
		REFIID	riidResource,
		void **	ppvResource )

Similar to Allocator::CreateResource, but supports new structure D3D12_RESOURCE_DESC1.

It internally uses ID3D12Device8::CreateCommittedResource2 or ID3D12Device8::CreatePlacedResource1.

To work correctly, ID3D12Device8 interface must be available in the current system. Otherwise, E_NOINTERFACE is returned.

◆ CreateResource3()

HRESULT D3D12MA::Allocator::CreateResource3	(	const ALLOCATION_DESC *	pAllocDesc,
		const D3D12_RESOURCE_DESC1 *	pResourceDesc,
		D3D12_BARRIER_LAYOUT	InitialLayout,
		const D3D12_CLEAR_VALUE *	pOptimizedClearValue,
		UINT32	NumCastableFormats,
		DXGI_FORMAT *	pCastableFormats,
		Allocation **	ppAllocation,
		REFIID	riidResource,
		void **	ppvResource )

Similar to Allocator::CreateResource2, but there are initial layout instead of state and castable formats list.

It internally uses ID3D12Device10::CreateCommittedResource3 or ID3D12Device10::CreatePlacedResource2.

To work correctly, ID3D12Device10 interface must be available in the current system. Otherwise, E_NOINTERFACE is returned.

◆ FreeStatsString()

void D3D12MA::Allocator::FreeStatsString ( WCHAR * pStatsString ) const

Frees memory of a string returned from Allocator::BuildStatsString.

◆ GetBudget()

void D3D12MA::Allocator::GetBudget	(	Budget *	pLocalBudget,
		Budget *	pNonLocalBudget )

Retrieves information about current memory usage and budget.

Parameters

[out]	pLocalBudget	Optional, can be null.
[out]	pNonLocalBudget	Optional, can be null.

When IsUMA() == FALSE (discrete graphics card):
- pLocalBudget returns the budget of the video memory.
- pNonLocalBudget returns the budget of the system memory available for D3D12 resources.
When IsUMA() == TRUE (integrated graphics chip):
- pLocalBudget returns the budget of the shared memory available for all D3D12 resources. All memory is considered "local".
- pNonLocalBudget is not applicable and returns zeros.

This function is called "get" not "calculate" because it is very fast, suitable to be called every frame or every allocation. For more detailed statistics use CalculateStatistics().

Note that when using allocator from multiple threads, returned information may immediately become outdated.

◆ GetD3D12Options()

const D3D12_FEATURE_DATA_D3D12_OPTIONS & D3D12MA::Allocator::GetD3D12Options ( ) const

Returns cached options retrieved from D3D12 device.

◆ GetMemoryCapacity()

UINT64 D3D12MA::Allocator::GetMemoryCapacity ( UINT memorySegmentGroup ) const

Returns total amount of memory of specific segment group, in bytes.

Parameters

memorySegmentGroup use DXGI_MEMORY_SEGMENT_GROUP_LOCAL or DXGI_MEMORY_SEGMENT_GROUP_NON_LOCAL`.

This information is taken from DXGI_ADAPTER_DESC. It is not recommended to use this number. You should preferably call GetBudget() and limit memory usage to D3D12MA::Budget::BudgetBytes instead.

When IsUMA() == FALSE (discrete graphics card):
- GetMemoryCapacity(DXGI_MEMORY_SEGMENT_GROUP_LOCAL) returns the size of the video memory.
- GetMemoryCapacity(DXGI_MEMORY_SEGMENT_GROUP_NON_LOCAL) returns the size of the system memory available for D3D12 resources.
When IsUMA() == TRUE (integrated graphics chip):
- GetMemoryCapacity(DXGI_MEMORY_SEGMENT_GROUP_LOCAL) returns the size of the shared memory available for all D3D12 resources. All memory is considered "local".
- GetMemoryCapacity(DXGI_MEMORY_SEGMENT_GROUP_NON_LOCAL) is not applicable and returns 0.

◆ IsCacheCoherentUMA()

BOOL D3D12MA::Allocator::IsCacheCoherentUMA ( ) const

Returns true if D3D12_FEATURE_DATA_ARCHITECTURE1::CacheCoherentUMA was found to be true.

For more information about how to use it, see articles in Microsoft Docs articles:

"UMA Optimizations: CPU Accessible Textures and Standard Swizzle"
"D3D12_FEATURE_DATA_ARCHITECTURE structure (d3d12.h)"
"ID3D12Device::GetCustomHeapProperties method (d3d12.h)"

◆ IsGPUUploadHeapSupported()

BOOL D3D12MA::Allocator::IsGPUUploadHeapSupported ( ) const

Returns true if GPU Upload Heaps are supported on the current system.

When true, you can use D3D12_HEAP_TYPE_GPU_UPLOAD.

This flag is fetched from D3D12_FEATURE_D3D12_OPTIONS16::GPUUploadHeapSupported.

#define D3D12MA_OPTIONS16_SUPPORTED 1 is needed for the compilation of this library. Otherwise the flag is always false.

◆ IsUMA()

BOOL D3D12MA::Allocator::IsUMA ( ) const

Returns true if D3D12_FEATURE_DATA_ARCHITECTURE1::UMA was found to be true.

For more information about how to use it, see articles in Microsoft Docs articles:

"UMA Optimizations: CPU Accessible Textures and Standard Swizzle"
"D3D12_FEATURE_DATA_ARCHITECTURE structure (d3d12.h)"
"ID3D12Device::GetCustomHeapProperties method (d3d12.h)"

◆ SetCurrentFrameIndex()

void D3D12MA::Allocator::SetCurrentFrameIndex ( UINT frameIndex )

Sets the index of the current frame.

This function is used to set the frame index in the allocator when a new game frame begins.

The documentation for this class was generated from the following file:

D:/PROJECTS/D3D12 Memory Allocator/REPO/include/D3D12MemAlloc.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ AllocateMemory()

◆ BeginDefragmentation()

◆ BuildStatsString()

◆ CalculateStatistics()

◆ CreateAliasingResource()

◆ CreateAliasingResource1()

◆ CreateAliasingResource2()

◆ CreatePool()

◆ CreateResource()

◆ CreateResource2()

◆ CreateResource3()

◆ FreeStatsString()

◆ GetBudget()

◆ GetD3D12Options()

◆ GetMemoryCapacity()

◆ IsCacheCoherentUMA()

◆ IsGPUUploadHeapSupported()

◆ IsUMA()

◆ SetCurrentFrameIndex()