diff --git a/CHANGELOG.md b/CHANGELOG.md index f8ae061..f26d5f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +# 3.1.0 (2026-02-23) + +- Added supported for resource tight alignment (feature added in Agility SDK 1.618.1). It is used automatically when available. + - Added function `Allocator::IsTightAlignmentSupported`. + - Added `ALLOCATOR_FLAG_DONT_USE_TIGHT_ALIGNMENT`. +- Fixes and improvements in the internal function `AllocatorPimpl::GetResourceAllocationInfo` (which decides when to use small alignment or tight alignment), including: + - Added support for 1D and 3D textures when `D3D12MA_USE_SMALL_RESOURCE_PLACEMENT_ALIGNMENT = 2` (#78, #79). + - Fix for cases when `D3D12_TEXTURE_LAYOUT_64KB_*_SWIZZLE` is used (#86). +- Fixes for build errors in MinGW (#77). +- Fixes and improvements in documentation and tests. + # 3.0.1 (2025-05-08) - Fixed macros `D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS`, `D3D12MA_RECOMMENDED_POOL_FLAGS` (#73). diff --git a/CMakeLists.txt b/CMakeLists.txt index 831d43f..6d61b21 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.25) -project(D3D12MemoryAllocator VERSION 3.0.2) +project(D3D12MemoryAllocator VERSION 3.1.0) set_property(GLOBAL PROPERTY USE_FOLDERS ON) diff --git a/LICENSE.txt b/LICENSE.txt index eb08d9e..3d5a69a 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (c) 2019-2025 Advanced Micro Devices, Inc. All rights reserved. +Copyright (c) 2019-2026 Advanced Micro Devices, Inc. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/bin/D3D12Sample.exe b/bin/D3D12Sample.exe index 628c38d..8b4bb3d 100644 Binary files a/bin/D3D12Sample.exe and b/bin/D3D12Sample.exe differ diff --git a/docs/html/_d3_d12_mem_alloc_8h.html b/docs/html/_d3_d12_mem_alloc_8h.html index 36f1863..2a34c7a 100644 --- a/docs/html/_d3_d12_mem_alloc_8h.html +++ b/docs/html/_d3_d12_mem_alloc_8h.html @@ -3,7 +3,7 @@
- +Classes | |
| struct | D3D12MA::ALLOCATION_CALLBACKS |
| struct | D3D12MA::ALLOCATION_CALLBACKS |
| Custom callbacks to CPU memory allocation functions. More... | |
| struct | D3D12MA::ALLOCATION_DESC |
| struct | D3D12MA::ALLOCATION_DESC |
| Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource. More... | |
| struct | D3D12MA::Statistics |
| struct | D3D12MA::Statistics |
| Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group, custom pool, or total. More... | |
| struct | D3D12MA::DetailedStatistics |
| struct | D3D12MA::DetailedStatistics |
| More detailed statistics than D3D12MA::Statistics. More... | |
| struct | D3D12MA::TotalStatistics |
| struct | D3D12MA::TotalStatistics |
| General statistics from current state of the allocator - total memory usage across all memory heaps and segments. More... | |
| struct | D3D12MA::Budget |
| struct | D3D12MA::Budget |
| Statistics of current memory usage and available budget for a specific memory segment group. More... | |
| struct | D3D12MA::VirtualAllocation |
| struct | D3D12MA::VirtualAllocation |
| Represents single memory allocation done inside VirtualBlock. More... | |
| class | D3D12MA::Allocation |
| class | D3D12MA::Allocation |
| Represents single memory allocation. More... | |
| struct | D3D12MA::DEFRAGMENTATION_DESC |
| struct | D3D12MA::DEFRAGMENTATION_DESC |
| Parameters for defragmentation. More... | |
| struct | D3D12MA::DEFRAGMENTATION_MOVE |
| struct | D3D12MA::DEFRAGMENTATION_MOVE |
| Single move of an allocation to be done for defragmentation. More... | |
| struct | D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO |
| struct | D3D12MA::DEFRAGMENTATION_PASS_MOVE_INFO |
| Parameters for incremental defragmentation steps. More... | |
| struct | D3D12MA::DEFRAGMENTATION_STATS |
| struct | D3D12MA::DEFRAGMENTATION_STATS |
| Statistics returned for defragmentation process by function DefragmentationContext::GetStats(). More... | |
| class | D3D12MA::DefragmentationContext |
| class | D3D12MA::DefragmentationContext |
| Represents defragmentation process in progress. More... | |
| struct | D3D12MA::POOL_DESC |
| struct | D3D12MA::POOL_DESC |
| Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool. More... | |
| class | D3D12MA::Pool |
| class | D3D12MA::Pool |
| Custom memory pool. More... | |
| struct | D3D12MA::ALLOCATOR_DESC |
| struct | D3D12MA::ALLOCATOR_DESC |
| Parameters of created Allocator object. To be used with CreateAllocator(). More... | |
| class | D3D12MA::Allocator |
| class | D3D12MA::Allocator |
| Represents main object of this library initialized for particular ID3D12Device. More... | |
| struct | D3D12MA::VIRTUAL_BLOCK_DESC |
| struct | D3D12MA::VIRTUAL_BLOCK_DESC |
| Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock(). More... | |
| struct | D3D12MA::VIRTUAL_ALLOCATION_DESC |
| struct | D3D12MA::VIRTUAL_ALLOCATION_DESC |
| Parameters of created virtual allocation to be passed to VirtualBlock::Allocate(). More... | |
| struct | D3D12MA::VIRTUAL_ALLOCATION_INFO |
| struct | D3D12MA::VIRTUAL_ALLOCATION_INFO |
| Parameters of an existing virtual allocation, returned by VirtualBlock::GetAllocationInfo(). More... | |
| class | D3D12MA::VirtualBlock |
| class | D3D12MA::VirtualBlock |
| Represents pure allocation algorithm and a data structure with allocations in some memory block, without actually allocating any GPU memory. More... | |
| struct | D3D12MA::CALLOCATION_DESC |
| struct | D3D12MA::CALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC structure. More... | |
| struct | D3D12MA::CPOOL_DESC |
| struct | D3D12MA::CPOOL_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC structure. More... | |
| struct | D3D12MA::CVIRTUAL_BLOCK_DESC |
| struct | D3D12MA::CVIRTUAL_BLOCK_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_DESC structure. More... | |
| struct | D3D12MA::CVIRTUAL_ALLOCATION_DESC |
| struct | D3D12MA::CVIRTUAL_ALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCATION_DESC structure. More... | |
Namespaces | |
| namespace | D3D12MA |
| namespace | D3D12MA |
Macros | |
| #define | D3D12MA_DXGI_1_4 1 |
| #define | D3D12MA_DXGI_1_4 1 |
| Define this macro to 0 to disable usage of DXGI 1.4 (which is used for IDXGIAdapter3 and query for memory budget). | |
| #define | D3D12MA_CREATE_NOT_ZEROED_AVAILABLE 1 |
| #define | D3D12MA_CREATE_NOT_ZEROED_AVAILABLE 1 |
| This macro is defined to 0 or 1 automatically. Define it to 0 to disable support for D3D12_HEAP_FLAG_CREATE_NOT_ZEROED. | |
| #define | D3D12MA_USE_SMALL_RESOURCE_PLACEMENT_ALIGNMENT 1 |
| #define | D3D12MA_USE_SMALL_RESOURCE_PLACEMENT_ALIGNMENT 1 |
| When defined to value other than 0, the library will try to use D3D12_SMALL_RESOURCE_PLACEMENT_ALIGNMENT or D3D12_SMALL_MSAA_RESOURCE_PLACEMENT_ALIGNMENT for created textures when possible, which can save memory because some small textures may get their alignment 4 KB and their size a multiply of 4 KB instead of 64 KB. | |
| #define | D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS (D3D12MA::ALLOCATOR_FLAG_DEFAULT_POOLS_NOT_ZEROED | D3D12MA::ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED) |
| #define | D3D12MA_RECOMMENDED_ALLOCATOR_FLAGS (D3D12MA::ALLOCATOR_FLAG_DEFAULT_POOLS_NOT_ZEROED | D3D12MA::ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED) |
| Set of flags recommended for use in D3D12MA::ALLOCATOR_DESC::Flags for optimal performance. | |
| #define | D3D12MA_RECOMMENDED_HEAP_FLAGS (D3D12_HEAP_FLAG_NONE) |
| #define | D3D12MA_RECOMMENDED_HEAP_FLAGS (D3D12_HEAP_FLAG_NONE) |
| Set of flags recommended for use in D3D12MA::POOL_DESC::HeapFlags for optimal performance. | |
| #define | D3D12MA_RECOMMENDED_POOL_FLAGS (D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED) |
| #define | D3D12MA_RECOMMENDED_POOL_FLAGS (D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED) |
| Set of flags recommended for use in D3D12MA::POOL_DESC::Flags for optimal performance. | |
Typedefs | |
| typedef UINT64 | D3D12MA::AllocHandle |
| typedef UINT64 | D3D12MA::AllocHandle |
| Unique identifier of single allocation done inside the memory heap. | |
| using | D3D12MA::ALLOCATE_FUNC_PTR = void* (*)(size_t Size, size_t Alignment, void* pPrivateData) |
| using | D3D12MA::ALLOCATE_FUNC_PTR = void* (*)(size_t Size, size_t Alignment, void* pPrivateData) |
| Pointer to custom callback function that allocates CPU memory. | |
| using | D3D12MA::FREE_FUNC_PTR = void (*)(void* pMemory, void* pPrivateData) |
| using | D3D12MA::FREE_FUNC_PTR = void (*)(void* pMemory, void* pPrivateData) |
| Pointer to custom callback function that deallocates CPU memory. | |
Functions | |
| D3D12MA_API HRESULT | D3D12MA::CreateAllocator (const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator) |
| D3D12MA_API HRESULT | D3D12MA::CreateAllocator (const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator) |
| Creates new main D3D12MA::Allocator object and returns it through ppAllocator. | |
| D3D12MA_API HRESULT | D3D12MA::CreateVirtualBlock (const VIRTUAL_BLOCK_DESC *pDesc, VirtualBlock **ppVirtualBlock) |
| D3D12MA_API HRESULT | D3D12MA::CreateVirtualBlock (const VIRTUAL_BLOCK_DESC *pDesc, VirtualBlock **ppVirtualBlock) |
| Creates new D3D12MA::VirtualBlock object and returns it through ppVirtualBlock. | |
| ND3D12MA | |
| CAllocation | Represents single memory allocation |
| CALLOCATION_CALLBACKS | Custom callbacks to CPU memory allocation functions |
| CALLOCATION_DESC | Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource |
| CAllocator | Represents main object of this library initialized for particular ID3D12Device |
| CALLOCATOR_DESC | Parameters of created Allocator object. To be used with CreateAllocator() |
| CALLOCATION_CALLBACKS | Custom callbacks to CPU memory allocation functions |
| CALLOCATION_DESC | Parameters of created D3D12MA::Allocation object. To be used with Allocator::CreateResource |
| CStatistics | Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group, custom pool, or total |
| CDetailedStatistics | More detailed statistics than D3D12MA::Statistics |
| CTotalStatistics | General statistics from current state of the allocator - total memory usage across all memory heaps and segments |
| CBudget | Statistics of current memory usage and available budget for a specific memory segment group |
| CCALLOCATION_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC structure |
| CCPOOL_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC structure |
| CCVIRTUAL_ALLOCATION_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCATION_DESC structure |
| CCVIRTUAL_BLOCK_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_DESC structure |
| CDEFRAGMENTATION_DESC | Parameters for defragmentation |
| CDEFRAGMENTATION_MOVE | Single move of an allocation to be done for defragmentation |
| CDEFRAGMENTATION_PASS_MOVE_INFO | Parameters for incremental defragmentation steps |
| CDEFRAGMENTATION_STATS | Statistics returned for defragmentation process by function DefragmentationContext::GetStats() |
| CDefragmentationContext | Represents defragmentation process in progress |
| CDetailedStatistics | More detailed statistics than D3D12MA::Statistics |
| CPool | Custom memory pool |
| CPOOL_DESC | Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool |
| CStatistics | Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group, custom pool, or total |
| CTotalStatistics | General statistics from current state of the allocator - total memory usage across all memory heaps and segments |
| CVIRTUAL_ALLOCATION_DESC | Parameters of created virtual allocation to be passed to VirtualBlock::Allocate() |
| CVIRTUAL_ALLOCATION_INFO | Parameters of an existing virtual allocation, returned by VirtualBlock::GetAllocationInfo() |
| CVIRTUAL_BLOCK_DESC | Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock() |
| CVirtualAllocation | Represents single memory allocation done inside VirtualBlock |
| CVirtualBlock | Represents pure allocation algorithm and a data structure with allocations in some memory block, without actually allocating any GPU memory |
| CVirtualAllocation | Represents single memory allocation done inside VirtualBlock |
| CAllocation | Represents single memory allocation |
| CDEFRAGMENTATION_DESC | Parameters for defragmentation |
| CDEFRAGMENTATION_MOVE | Single move of an allocation to be done for defragmentation |
| CDEFRAGMENTATION_PASS_MOVE_INFO | Parameters for incremental defragmentation steps |
| CDEFRAGMENTATION_STATS | Statistics returned for defragmentation process by function DefragmentationContext::GetStats() |
| CDefragmentationContext | Represents defragmentation process in progress |
| CPOOL_DESC | Parameters of created D3D12MA::Pool object. To be used with D3D12MA::Allocator::CreatePool |
| CPool | Custom memory pool |
| CALLOCATOR_DESC | Parameters of created Allocator object. To be used with CreateAllocator() |
| CAllocator | Represents main object of this library initialized for particular ID3D12Device |
| CVIRTUAL_BLOCK_DESC | Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock() |
| CVIRTUAL_ALLOCATION_DESC | Parameters of created virtual allocation to be passed to VirtualBlock::Allocate() |
| CVIRTUAL_ALLOCATION_INFO | Parameters of an existing virtual allocation, returned by VirtualBlock::GetAllocationInfo() |
| CVirtualBlock | Represents pure allocation algorithm and a data structure with allocations in some memory block, without actually allocating any GPU memory |
| CCALLOCATION_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC structure |
| CCPOOL_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC structure |
| CCVIRTUAL_BLOCK_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_DESC structure |
| CCVIRTUAL_ALLOCATION_DESC | Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCATION_DESC structure |
Public Member Functions | |
| UINT64 | GetOffset () const |
| UINT64 | GetOffset () const |
| Returns offset in bytes from the start of memory heap. | |
| UINT64 | GetAlignment () const |
| UINT64 | GetAlignment () const |
| Returns alignment that resource was created with. | |
| UINT64 | GetSize () const |
| UINT64 | GetSize () const |
| Returns size in bytes of the allocation. | |
| ID3D12Resource * | GetResource () const |
| ID3D12Resource * | GetResource () const |
| Returns D3D12 resource associated with this object. | |
| void | SetResource (ID3D12Resource *pResource) |
| void | SetResource (ID3D12Resource *pResource) |
| Releases the resource currently pointed by the allocation (if not null), sets it to new one, incrementing its reference counter (if not null). | |
| ID3D12Heap * | GetHeap () const |
| ID3D12Heap * | GetHeap () const |
| Returns memory heap that the resource is created in. | |
| void | SetPrivateData (void *pPrivateData) |
| void | SetPrivateData (void *pPrivateData) |
| Changes custom pointer for an allocation to a new value. | |
| void * | GetPrivateData () const |
| void * | GetPrivateData () const |
| Get custom pointer associated with the allocation. | |
| void | SetName (LPCWSTR Name) |
| void | SetName (LPCWSTR Name) |
| Associates a name with the allocation object. This name is for use in debug diagnostics and tools. | |
| LPCWSTR | GetName () const |
| LPCWSTR | GetName () const |
| Returns the name associated with the allocation object. | |
Releases the resource currently pointed by the allocation (if not null), sets it to new one, incrementing its reference counter (if not null).
-| Allocation* D3D12MA::Allocation::next | +Allocation* D3D12MA::Allocation::next |
| Allocation* D3D12MA::Allocation::prev | +Allocation* D3D12MA::Allocation::prev |
Public Member Functions | |
| const D3D12_FEATURE_DATA_D3D12_OPTIONS & | GetD3D12Options () const |
| const D3D12_FEATURE_DATA_D3D12_OPTIONS & | GetD3D12Options () const |
| Returns cached options retrieved from D3D12 device. | |
| BOOL | IsUMA () const |
| BOOL | IsUMA () const |
| Returns true if D3D12_FEATURE_DATA_ARCHITECTURE1::UMA was found to be true. | |
| BOOL | IsCacheCoherentUMA () const |
| BOOL | IsCacheCoherentUMA () const |
| Returns true if D3D12_FEATURE_DATA_ARCHITECTURE1::CacheCoherentUMA was found to be true. | |
| BOOL | IsGPUUploadHeapSupported () const |
| BOOL | IsGPUUploadHeapSupported () const |
| Returns true if GPU Upload Heaps are supported on the current system. | |
| BOOL | IsTightAlignmentSupported () const |
| BOOL | IsTightAlignmentSupported () const |
| Returns true if resource tight alignment is supported on the current system. When supported, it is automatically used by the library, unless ALLOCATOR_FLAG_DONT_USE_TIGHT_ALIGNMENT flag was specified on allocator creation. This flag is fetched from D3D12_FEATURE_DATA_TIGHT_ALIGNMENT::SupportTier. | |
| UINT64 | GetMemoryCapacity (UINT memorySegmentGroup) const |
| 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) |
| 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) |
| 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, const DXGI_FORMAT *pCastableFormats, Allocation **ppAllocation, REFIID riidResource, void **ppvResource) |
| HRESULT | CreateResource3 (const ALLOCATION_DESC *pAllocDesc, const D3D12_RESOURCE_DESC1 *pResourceDesc, D3D12_BARRIER_LAYOUT InitialLayout, const D3D12_CLEAR_VALUE *pOptimizedClearValue, UINT32 NumCastableFormats, const 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) |
| 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) |
| 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) |
| 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, const DXGI_FORMAT *pCastableFormats, REFIID riidResource, void **ppvResource) |
| HRESULT | CreateAliasingResource2 (Allocation *pAllocation, UINT64 AllocationLocalOffset, const D3D12_RESOURCE_DESC1 *pResourceDesc, D3D12_BARRIER_LAYOUT InitialLayout, const D3D12_CLEAR_VALUE *pOptimizedClearValue, UINT32 NumCastableFormats, const 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) |
| HRESULT | CreatePool (const POOL_DESC *pPoolDesc, Pool **ppPool) |
| Creates custom pool. | |
| void | SetCurrentFrameIndex (UINT frameIndex) |
| void | SetCurrentFrameIndex (UINT frameIndex) |
| Sets the index of the current frame. | |
| void | GetBudget (Budget *pLocalBudget, Budget *pNonLocalBudget) |
| void | GetBudget (Budget *pLocalBudget, Budget *pNonLocalBudget) |
| Retrieves information about current memory usage and budget. | |
| void | CalculateStatistics (TotalStatistics *pStats) |
| void | CalculateStatistics (TotalStatistics *pStats) |
| Retrieves statistics from current state of the allocator. | |
| void | BuildStatsString (WCHAR **ppStatsString, BOOL DetailedMap) const |
| void | BuildStatsString (WCHAR **ppStatsString, BOOL DetailedMap) const |
| Builds and returns statistics as a string in JSON format. | |
| void | FreeStatsString (WCHAR *pStatsString) const |
| void | FreeStatsString (WCHAR *pStatsString) const |
| Frees memory of a string returned from Allocator::BuildStatsString. | |
| void | BeginDefragmentation (const DEFRAGMENTATION_DESC *pDesc, DefragmentationContext **ppContext) |
| void | BeginDefragmentation (const DEFRAGMENTATION_DESC *pDesc, DefragmentationContext **ppContext) |
| Begins defragmentation process of the default pools. | |
For more information about defragmentation, see documentation chapter: Defragmentation.
Public Member Functions | |
| HRESULT | BeginPass (DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo) |
| HRESULT | BeginPass (DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo) |
| Starts single defragmentation pass. | |
| HRESULT | EndPass (DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo) |
| HRESULT | EndPass (DEFRAGMENTATION_PASS_MOVE_INFO *pPassInfo) |
| Ends single defragmentation pass. | |
| void | GetStats (DEFRAGMENTATION_STATS *pStats) |
| void | GetStats (DEFRAGMENTATION_STATS *pStats) |
| Returns statistics of the defragmentation performed so far. | |
Public Member Functions | |
| POOL_DESC | GetDesc () const |
| POOL_DESC | GetDesc () const |
| Returns copy of parameters of the pool. | |
| void | GetStatistics (Statistics *pStats) |
| void | GetStatistics (Statistics *pStats) |
| Retrieves basic statistics of the custom pool that are fast to calculate. | |
| void | CalculateStatistics (DetailedStatistics *pStats) |
| void | CalculateStatistics (DetailedStatistics *pStats) |
| Retrieves detailed statistics of the custom pool that are slower to calculate. | |
| void | SetName (LPCWSTR Name) |
| void | SetName (LPCWSTR Name) |
| Associates a name with the pool. This name is for use in debug diagnostics and tools. | |
| LPCWSTR | GetName () const |
| LPCWSTR | GetName () const |
| Returns the name associated with the pool object. | |
| HRESULT | BeginDefragmentation (const DEFRAGMENTATION_DESC *pDesc, DefragmentationContext **ppContext) |
| HRESULT | BeginDefragmentation (const DEFRAGMENTATION_DESC *pDesc, DefragmentationContext **ppContext) |
| Begins defragmentation process of the current pool. | |
For more information about defragmentation, see documentation chapter: Defragmentation.
+For more information about defragmentation, see documentation chapter: Defragmentation.
@@ -267,7 +267,7 @@Public Member Functions | |
| BOOL | IsEmpty () const |
| BOOL | IsEmpty () const |
| Returns true if the block is empty - contains 0 allocations. | |
| void | GetAllocationInfo (VirtualAllocation allocation, VIRTUAL_ALLOCATION_INFO *pInfo) const |
| void | GetAllocationInfo (VirtualAllocation allocation, VIRTUAL_ALLOCATION_INFO *pInfo) const |
| Returns information about an allocation - its offset, size and custom pointer. | |
| HRESULT | Allocate (const VIRTUAL_ALLOCATION_DESC *pDesc, VirtualAllocation *pAllocation, UINT64 *pOffset) |
| HRESULT | Allocate (const VIRTUAL_ALLOCATION_DESC *pDesc, VirtualAllocation *pAllocation, UINT64 *pOffset) |
| Creates new allocation. | |
| void | FreeAllocation (VirtualAllocation allocation) |
| void | FreeAllocation (VirtualAllocation allocation) |
| Frees the allocation. | |
| void | Clear () |
| void | Clear () |
| Frees all the allocations. | |
| void | SetAllocationPrivateData (VirtualAllocation allocation, void *pPrivateData) |
| void | SetAllocationPrivateData (VirtualAllocation allocation, void *pPrivateData) |
| Changes custom pointer for an allocation to a new value. | |
| void | GetStatistics (Statistics *pStats) const |
| void | GetStatistics (Statistics *pStats) const |
| Retrieves basic statistics of the virtual block that are fast to calculate. | |
| void | CalculateStatistics (DetailedStatistics *pStats) const |
| void | CalculateStatistics (DetailedStatistics *pStats) const |
| Retrieves detailed statistics of the virtual block that are slower to calculate. | |
| void | BuildStatsString (WCHAR **ppStatsString) const |
| void | BuildStatsString (WCHAR **ppStatsString) const |
| Builds and returns statistics as a string in JSON format, including the list of allocations with their parameters. | |
| void | FreeStatsString (WCHAR *pStatsString) const |
| void | FreeStatsString (WCHAR *pStatsString) const |
| Frees memory of a string returned from VirtualBlock::BuildStatsString. | |
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.
+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.
+Margins do not apply to Virtual allocator.
Files | |
| D3D12MemAlloc.h | |
| D3D12MemAlloc.h | |
D3D12MA helps with handling one aspect of DX12 usage, which is GPU memory management - allocation of ID3D12Heap objects and creation of ID3D12Resource objects - buffers and textures.
Do I need to use D3D12MA?
You don't need to, but it may be beneficial in many cases. DX12 is a complex and low-level API, so libraries like this that abstract certain aspects of the API and bring them to a higher level are useful. When developing any non-trivial graphics application, you may benefit from using a memory allocator. Using D3D12MA can save time compared to implementing your own.
-In DX12 you can create each resource separately with its own implicit memory heap by calling CreateCommittedResource, but this may not be the optimal solution. For more information, see Committed versus placed resources.
+In DX12 you can create each resource separately with its own implicit memory heap by calling CreateCommittedResource, but this may not be the optimal solution. For more information, see Committed versus placed resources.
When should I not use D3D12MA?
While D3D12MA is useful for many applications that use the DX12 API, there are cases when it may be a better choice not to use it. For example, if the application is very simple, e.g. serving as a sample or a learning exercise to help you understand or teach others the basics of DX12, and it creates only a small number of buffers and textures, then including D3D12MA may be an overkill. Developing your own memory allocator may also be a good learning exercise.
What are the benefits of using D3D12MA?
@@ -145,13 +145,13 @@I found some compilation warnings. How can we fix them?
-Seeing compiler warnings may be annoying to some developers, but it is a design decision to not fix all of them. Due to the nature of the C++ language, certain preprocessor macros can make some variables unused, function parameters unreferenced, or conditional expressions constant in some configurations. The code of this library should not be bigger or more complicated just to silence these warnings. It is recommended to disable such warnings instead. For more information, see Features not supported.
+Seeing compiler warnings may be annoying to some developers, but it is a design decision to not fix all of them. Due to the nature of the C++ language, certain preprocessor macros can make some variables unused, function parameters unreferenced, or conditional expressions constant in some configurations. The code of this library should not be bigger or more complicated just to silence these warnings. It is recommended to disable such warnings instead. For more information, see Features not supported.
However, if you observe a warning that is really dangerous, e.g., about an implicit conversion from a larger to a smaller integer type, please report it and it will be fixed ASAP.
Version 3.1.0-development (2025-XX-XX)
-Copyright (c) 2019-2025 Advanced Micro Devices, Inc. All rights reserved.
+
Version 3.1.0 (2026-02-23)
+Copyright (c) 2019-2026 Advanced Micro Devices, Inc. All rights reserved.
License: MIT
Documentation of all members: D3D12MemAlloc.h
+Documentation of all members: D3D12MemAlloc.h
Ring buffer is available only in pools with one memory block - D3D12MA::POOL_DESC::MaxBlockCount must be 1. Otherwise behavior is undefined.
Linear algorithm can also be used with Virtual allocator. See flag D3D12MA::VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR.
+Linear algorithm can also be used with Virtual allocator. See flag D3D12MA::VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR.
Classes | |
| class | Allocation |
| Represents single memory allocation. More... | |
| struct | ALLOCATION_CALLBACKS |
| struct | ALLOCATION_CALLBACKS |
| Custom callbacks to CPU memory allocation functions. More... | |
| struct | ALLOCATION_DESC |
| 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 |
| struct | Statistics |
| Calculated statistics of memory usage e.g. in a specific memory heap type, memory segment group, custom pool, or total. More... | |
| struct | DetailedStatistics |
| More detailed statistics than D3D12MA::Statistics. More... | |
| struct | TotalStatistics |
| General statistics from current state of the allocator - total memory usage across all memory heaps and segments. More... | |
| struct | Budget |
| Statistics of current memory usage and available budget for a specific memory segment group. More... | |
| struct | CALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC structure. More... | |
| struct | CPOOL_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC structure. More... | |
| struct | CVIRTUAL_ALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCATION_DESC structure. More... | |
| struct | CVIRTUAL_BLOCK_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_DESC structure. More... | |
| struct | DEFRAGMENTATION_DESC |
| struct | VirtualAllocation |
| Represents single memory allocation done inside VirtualBlock. More... | |
| class | Allocation |
| Represents single memory allocation. More... | |
| struct | DEFRAGMENTATION_DESC |
| Parameters for defragmentation. More... | |
| struct | DEFRAGMENTATION_MOVE |
| struct | DEFRAGMENTATION_MOVE |
| Single move of an allocation to be done for defragmentation. More... | |
| struct | DEFRAGMENTATION_PASS_MOVE_INFO |
| struct | DEFRAGMENTATION_PASS_MOVE_INFO |
| Parameters for incremental defragmentation steps. More... | |
| struct | DEFRAGMENTATION_STATS |
| struct | DEFRAGMENTATION_STATS |
| Statistics returned for defragmentation process by function DefragmentationContext::GetStats(). More... | |
| class | DefragmentationContext |
| 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 |
| 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 |
| class | Pool |
| Custom memory pool. More... | |
| struct | ALLOCATOR_DESC |
| Parameters of created Allocator object. To be used with CreateAllocator(). More... | |
| class | Allocator |
| Represents main object of this library initialized for particular ID3D12Device. More... | |
| struct | VIRTUAL_BLOCK_DESC |
| Parameters of created D3D12MA::VirtualBlock object to be passed to CreateVirtualBlock(). More... | |
| struct | VIRTUAL_ALLOCATION_DESC |
| Parameters of created virtual allocation to be passed to VirtualBlock::Allocate(). More... | |
| struct | VIRTUAL_ALLOCATION_INFO |
| 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 |
| class | VirtualBlock |
| Represents pure allocation algorithm and a data structure with allocations in some memory block, without actually allocating any GPU memory. More... | |
| struct | CALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::ALLOCATION_DESC structure. More... | |
| struct | CPOOL_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::POOL_DESC structure. More... | |
| struct | CVIRTUAL_BLOCK_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_BLOCK_DESC structure. More... | |
| struct | CVIRTUAL_ALLOCATION_DESC |
| Helper structure that helps with complete and conscise initialization of the D3D12MA::VIRTUAL_ALLOCATION_DESC structure. More... | |
Typedefs | |
| typedef UINT64 | AllocHandle |
| 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) |
| 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) |
| using | FREE_FUNC_PTR = void (*)(void* pMemory, void* pPrivateData) |
| Pointer to custom callback function that deallocates CPU memory. | |
Functions | |
| D3D12MA_API HRESULT | CreateAllocator (const ALLOCATOR_DESC *pDesc, Allocator **ppAllocator) |
| 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) |
| D3D12MA_API HRESULT | CreateVirtualBlock (const VIRTUAL_BLOCK_DESC *pDesc, VirtualBlock **ppVirtualBlock) |
| Creates new D3D12MA::VirtualBlock object and returns it through ppVirtualBlock. | |
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:
+Only affects default pools. To use the flag with Custom memory pools, you need to add it manually:
Only avaiable if ID3D12Device8 is present. Otherwise, the flag is ignored.
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.
+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.
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.
@@ -495,7 +495,7 @@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.
+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.
Because of this, the recommended way of fetching the memory budget available to the application is using function D3D12MA::Allocator::GetBudget. Preventing value D3D12MA::Budget::UsageBytes from exceeding the D3D12MA::Budget::BudgetBytes is probably the best we can do in trying to avoid the consequences of over-commitment. For more information, see also: Statistics.
+Because of this, the recommended way of fetching the memory budget available to the application is using function D3D12MA::Allocator::GetBudget. Preventing value D3D12MA::Budget::UsageBytes from exceeding the D3D12MA::Budget::BudgetBytes is probably the best we can do in trying to avoid the consequences of over-commitment. For more information, see also: Statistics.
Example:
When a large number of small buffers needs to be created, the overhead of creating separate ID3D12Resource objects can be significant. It can also cause a significant waste of memory, as placed buffers need to be aligned to D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT = 64 KB by default. These problems can be avoided by creating one or few larger buffers and manually sub-allocating parts of them for specific needs.
-It requires implementing a custom allocator for the data inside the buffer and using offsets to individual regions. When all the regions can be allocated linearly and freed all at once, implementing such allocator is trivial. When every region has the same size, implementing an allocator is also quite simple when using a "free list" algorithm. However, when regions can have different sizes and can be allocated and freed in random order, it requires a full allocation algorithm. D3D12MA can help with it by exposing its core allocation algorithm for custom usages. For more details and example code, see chapter: Virtual allocator. It can be used for all the cases mentioned above without too much performance overhead, because the D3D12MA::VirtualAllocation object is just a lightweight handle.
+It requires implementing a custom allocator for the data inside the buffer and using offsets to individual regions. When all the regions can be allocated linearly and freed all at once, implementing such allocator is trivial. When every region has the same size, implementing an allocator is also quite simple when using a "free list" algorithm. However, when regions can have different sizes and can be allocated and freed in random order, it requires a full allocation algorithm. D3D12MA can help with it by exposing its core allocation algorithm for custom usages. For more details and example code, see chapter: Virtual allocator. It can be used for all the cases mentioned above without too much performance overhead, because the D3D12MA::VirtualAllocation object is just a lightweight handle.
When sub-allocating a buffer, you need to remember to explicitly request proper alignment required for each region. For example, data used as a constant buffer must be aligned to D3D12_CONSTANT_BUFFER_DATA_PLACEMENT_ALIGNMENT = 256 B.
When creating resources with the help of D3D12MA using function D3D12MA::Allocator::CreateResource, you typically don't need to care about all this. The library automatically makes the choice of creating the new resource as committed or placed. However, in cases when you need the information or the control over this choice between committed and placed, the library offers facilities to do that, described below.
You can check whether an allocation was created as a committed resource by checking if its heap is null. Committed resources have an implicit heap that is not directly accessible.
You can request a new resource to be created as committed by using D3D12MA::ALLOCATION_FLAG_COMMITTED. Note that committed resources can also be created out of Custom memory pools.
+You can request a new resource to be created as committed by using D3D12MA::ALLOCATION_FLAG_COMMITTED. Note that committed resources can also be created out of Custom memory pools.
You can also request all resources to be created as committed globally for the entire allocator by using D3D12MA::ALLOCATOR_FLAG_ALWAYS_COMMITTED. However, this contradicts the main purpose of using this library. It can also prevent certain other features of the library to be used. This flag should be used only for debugging purposes.
You can create a custom pool with an explicit block size by specifying non-zero D3D12MA::POOL_DESC::BlockSize. When doing this, all resources created in such pool are placed in those blocks (heaps) and never created as committed. Example:
With DirectX 12 Agility SDK 1.618.1, Microsoft added a new feature called "tight alignment". Note this is a separate feature than the "small alignment" described earlier. When using this new SDK and a compatible graphics driver, the API exposes support for this new feature. Then, a new flag D3D12_RESOURCE_FLAG_USE_TIGHT_ALIGNMENT can be added when creating a resource. D3D12 can then return the alignment required for the resource smaller than the default ones described above. This library automatically makes use of the tight alignment feature when available and adds that new resource flag. When the tight alignment is enabled, the heuristics that creates small buffers as committed described above is deactivated, as it is no longer needed.
You can check if the tight alignment it is available in the current system by calling D3D12MA::Allocator::IsTightAlignmentSupported(). You can tell the library to not use it by specifying D3D12MA::ALLOCATOR_FLAG_DONT_USE_TIGHT_ALIGNMENT. Typically, you don't need to do any of those.
-The library automatically aligns all buffers to at least 256 B, even when the system supports smaller alignment. This is the alignment required for constant buffers, expressed by D3D12_CONSTANT_BUFFER_DATA_PLACEMENT_ALIGNMENT constant. You can override this logic for Custom memory pools with a specific D3D12MA::POOL_DESC::MinAllocationAlignment.
+The library automatically aligns all buffers to at least 256 B, even when the system supports smaller alignment. This is the alignment required for constant buffers, expressed by D3D12_CONSTANT_BUFFER_DATA_PLACEMENT_ALIGNMENT constant. You can override this logic for Custom memory pools with a specific D3D12MA::POOL_DESC::MinAllocationAlignment.
More advanced use cases are possible when we consider that an D3D12MA::Allocation object can just hold a reference to any resource. It can be changed by calling D3D12MA::Allocation::SetResource. This function releases the old resource and calls AddRef on the new one.
-Special care must be taken when performing defragmentation. The new resource created at the destination place should be set as pass.pMoves[i].pDstTmpAllocation->SetResource(newRes), but it is moved to the source allocation at end of the defragmentation pass, while the old resource accessible through pass.pMoves[i].pSrcAllocation->GetResource() is then released. For more information, see documentation chapter Defragmentation.
+Special care must be taken when performing defragmentation. The new resource created at the destination place should be set as pass.pMoves[i].pDstTmpAllocation->SetResource(newRes), but it is moved to the source allocation at end of the defragmentation pass, while the old resource accessible through pass.pMoves[i].pSrcAllocation->GetResource() is then released. For more information, see documentation chapter Defragmentation.
The process of getting regular CPU-side pointer to the memory of a resource in Direct3D is called "mapping". There are rules and restrictions to this process, as described in D3D12 documentation of ID3D12Resource::Map method.
@@ -278,7 +278,7 @@Public Attributes | |
| ALLOCATE_FUNC_PTR | pAllocate |
| ALLOCATE_FUNC_PTR | pAllocate |
| Allocation function. | |
| FREE_FUNC_PTR | pFree |
| FREE_FUNC_PTR | pFree |
| Dellocation function. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom data that will be passed to allocation and deallocation functions as pUserData parameter. | |
Public Attributes | |
| ALLOCATION_FLAGS | Flags |
| ALLOCATION_FLAGS | Flags |
| Flags for the allocation. | |
| D3D12_HEAP_TYPE | HeapType |
| D3D12_HEAP_TYPE | HeapType |
| The type of memory heap where the new allocation should be placed. | |
| D3D12_HEAP_FLAGS | ExtraHeapFlags |
| D3D12_HEAP_FLAGS | ExtraHeapFlags |
| Additional heap flags to be used when allocating memory. | |
| Pool * | CustomPool |
| Pool * | CustomPool |
| Custom pool to place the new resource in. Optional. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom general-purpose pointer that will be stored in D3D12MA::Allocation. | |
Custom pool to place the new resource in. Optional.
-When not null, the resource will be created inside specified custom pool. Members HeapType, ExtraHeapFlags are then ignored.
+When not null, the resource will be created inside specified custom pool. Members HeapType, ExtraHeapFlags are then ignored.
@@ -208,7 +208,7 @@Public Attributes | |
| ALLOCATOR_FLAGS | Flags |
| ALLOCATOR_FLAGS | Flags |
| Flags for the entire allocator. | |
| ID3D12Device * | pDevice |
| UINT64 | PreferredBlockSize |
| ID3D12Device * | pDevice |
| UINT64 | PreferredBlockSize |
| Preferred size of a single ID3D12Heap block to be allocated. | |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| Custom CPU memory allocation callbacks. Optional. | |
| IDXGIAdapter * | pAdapter |
| IDXGIAdapter * | pAdapter |
Parameters of created Allocator object. To be used with CreateAllocator().
@@ -190,7 +190,7 @@Public Attributes | |
| Statistics | Stats |
| Statistics | Stats |
| Statistics fetched from the library. | |
| UINT64 | UsageBytes |
| UINT64 | UsageBytes |
| Estimated current memory usage of the program. | |
| UINT64 | BudgetBytes |
| UINT64 | BudgetBytes |
| Estimated amount of memory available to the program. | |
It might be different (most probably smaller) than memory capacity returned by D3D12MA::Allocator::GetMemoryCapacity() due to factors external to the program, decided by the operating system. Difference BudgetBytes - UsageBytes is the amount of additional memory that can probably be allocated without problems. Exceeding the budget may result in various problems.
+It might be different (most probably smaller) than memory capacity returned by D3D12MA::Allocator::GetMemoryCapacity() due to factors external to the program, decided by the operating system. Difference BudgetBytes - UsageBytes is the amount of additional memory that can probably be allocated without problems. Exceeding the budget may result in various problems.
@@ -158,7 +158,7 @@Public Member Functions | |
| CALLOCATION_DESC ()=default | |
| CALLOCATION_DESC ()=default | |
| Default constructor. Leaves the structure uninitialized. | |
| CALLOCATION_DESC (const ALLOCATION_DESC &o) noexcept | |
| CALLOCATION_DESC (const ALLOCATION_DESC &o) noexcept | |
| Constructor initializing from the base D3D12MA::ALLOCATION_DESC structure. | |
| CALLOCATION_DESC (Pool *customPool, ALLOCATION_FLAGS flags=ALLOCATION_FLAG_NONE, void *privateData=NULL) noexcept | |
| CALLOCATION_DESC (Pool *customPool, ALLOCATION_FLAGS flags=ALLOCATION_FLAG_NONE, void *privateData=NULL) noexcept | |
| Constructor initializing description of an allocation to be created in a specific custom pool. | |
| CALLOCATION_DESC (D3D12_HEAP_TYPE heapType, ALLOCATION_FLAGS flags=ALLOCATION_FLAG_NONE, void *privateData=NULL, D3D12_HEAP_FLAGS extraHeapFlags=D3D12MA_RECOMMENDED_HEAP_FLAGS) noexcept | |
| CALLOCATION_DESC (D3D12_HEAP_TYPE heapType, ALLOCATION_FLAGS flags=ALLOCATION_FLAG_NONE, void *privateData=NULL, D3D12_HEAP_FLAGS extraHeapFlags=D3D12MA_RECOMMENDED_HEAP_FLAGS) noexcept | |
| Constructor initializing description of an allocation to be created in a default pool of a specific D3D12_HEAP_TYPE. | |
Additional Inherited Members | |
| Public Attributes inherited from D3D12MA::ALLOCATION_DESC | |
| ALLOCATION_FLAGS | Flags |
| ALLOCATION_FLAGS | Flags |
| Flags for the allocation. | |
| D3D12_HEAP_TYPE | HeapType |
| D3D12_HEAP_TYPE | HeapType |
| The type of memory heap where the new allocation should be placed. | |
| D3D12_HEAP_FLAGS | ExtraHeapFlags |
| D3D12_HEAP_FLAGS | ExtraHeapFlags |
| Additional heap flags to be used when allocating memory. | |
| Pool * | CustomPool |
| Pool * | CustomPool |
| Custom pool to place the new resource in. Optional. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom general-purpose pointer that will be stored in D3D12MA::Allocation. | |
Public Member Functions | |
| CPOOL_DESC ()=default | |
| CPOOL_DESC ()=default | |
| Default constructor. Leaves the structure uninitialized. | |
| CPOOL_DESC (const POOL_DESC &o) noexcept | |
| CPOOL_DESC (const POOL_DESC &o) noexcept | |
| Constructor initializing from the base D3D12MA::POOL_DESC structure. | |
| CPOOL_DESC (D3D12_HEAP_TYPE heapType, D3D12_HEAP_FLAGS heapFlags, POOL_FLAGS flags=D3D12MA_RECOMMENDED_POOL_FLAGS, UINT64 blockSize=0, UINT minBlockCount=0, UINT maxBlockCount=UINT_MAX, D3D12_RESIDENCY_PRIORITY residencyPriority=D3D12_RESIDENCY_PRIORITY_NORMAL) noexcept | |
| CPOOL_DESC (D3D12_HEAP_TYPE heapType, D3D12_HEAP_FLAGS heapFlags, POOL_FLAGS flags=D3D12MA_RECOMMENDED_POOL_FLAGS, UINT64 blockSize=0, UINT minBlockCount=0, UINT maxBlockCount=UINT_MAX, D3D12_RESIDENCY_PRIORITY residencyPriority=D3D12_RESIDENCY_PRIORITY_NORMAL) noexcept | |
| Constructor initializing description of a custom pool created in one of the standard D3D12_HEAP_TYPE. | |
| CPOOL_DESC (const D3D12_HEAP_PROPERTIES heapProperties, D3D12_HEAP_FLAGS heapFlags, POOL_FLAGS flags=D3D12MA_RECOMMENDED_POOL_FLAGS, UINT64 blockSize=0, UINT minBlockCount=0, UINT maxBlockCount=UINT_MAX, D3D12_RESIDENCY_PRIORITY residencyPriority=D3D12_RESIDENCY_PRIORITY_NORMAL) noexcept | |
| CPOOL_DESC (const D3D12_HEAP_PROPERTIES heapProperties, D3D12_HEAP_FLAGS heapFlags, POOL_FLAGS flags=D3D12MA_RECOMMENDED_POOL_FLAGS, UINT64 blockSize=0, UINT minBlockCount=0, UINT maxBlockCount=UINT_MAX, D3D12_RESIDENCY_PRIORITY residencyPriority=D3D12_RESIDENCY_PRIORITY_NORMAL) noexcept | |
| Constructor initializing description of a custom pool created with custom D3D12_HEAP_PROPERTIES. | |
Additional Inherited Members | |
| Public Attributes inherited from D3D12MA::POOL_DESC | |
| POOL_FLAGS | Flags |
| POOL_FLAGS | Flags |
| Flags for the heap. | |
| D3D12_HEAP_PROPERTIES | HeapProperties |
| D3D12_HEAP_PROPERTIES | HeapProperties |
| The parameters of memory heap where allocations of this pool should be placed. | |
| D3D12_HEAP_FLAGS | HeapFlags |
| D3D12_HEAP_FLAGS | HeapFlags |
| Heap flags to be used when allocating heaps of this pool. | |
| UINT64 | BlockSize |
| UINT64 | BlockSize |
| Size of a single heap (memory block) to be allocated as part of this pool, in bytes. Optional. | |
| UINT | MinBlockCount |
| UINT | MinBlockCount |
| Minimum number of heaps (memory blocks) to be always allocated in this pool, even if they stay empty. Optional. | |
| UINT | MaxBlockCount |
| UINT | MaxBlockCount |
| Maximum number of heaps (memory blocks) that can be allocated in this pool. Optional. | |
| UINT64 | MinAllocationAlignment |
| UINT64 | MinAllocationAlignment |
| Additional minimum alignment to be used for all allocations created from this pool. Can be 0. | |
| ID3D12ProtectedResourceSession * | pProtectedSession |
| ID3D12ProtectedResourceSession * | pProtectedSession |
| Additional parameter allowing pool to create resources with passed protected session. | |
| D3D12_RESIDENCY_PRIORITY | ResidencyPriority |
| D3D12_RESIDENCY_PRIORITY | ResidencyPriority |
| Residency priority to be set for all allocations made in this pool. Optional. | |
Public Member Functions | |
| CVIRTUAL_ALLOCATION_DESC ()=default | |
| CVIRTUAL_ALLOCATION_DESC ()=default | |
| Default constructor. Leaves the structure uninitialized. | |
| CVIRTUAL_ALLOCATION_DESC (const VIRTUAL_ALLOCATION_DESC &o) noexcept | |
| CVIRTUAL_ALLOCATION_DESC (const VIRTUAL_ALLOCATION_DESC &o) noexcept | |
| Constructor initializing from the base D3D12MA::VIRTUAL_ALLOCATION_DESC structure. | |
| CVIRTUAL_ALLOCATION_DESC (UINT64 size, UINT64 alignment, VIRTUAL_ALLOCATION_FLAGS flags=VIRTUAL_ALLOCATION_FLAG_NONE, void *privateData=NULL) noexcept | |
| CVIRTUAL_ALLOCATION_DESC (UINT64 size, UINT64 alignment, VIRTUAL_ALLOCATION_FLAGS flags=VIRTUAL_ALLOCATION_FLAG_NONE, void *privateData=NULL) noexcept | |
| Constructor initializing description of a virtual allocation with given parameters. | |
Additional Inherited Members | |
| Public Attributes inherited from D3D12MA::VIRTUAL_ALLOCATION_DESC | |
| VIRTUAL_ALLOCATION_FLAGS | Flags |
| VIRTUAL_ALLOCATION_FLAGS | Flags |
| Flags for the virtual allocation. | |
| UINT64 | Size |
| UINT64 | Size |
| Size of the allocation. | |
| UINT64 | Alignment |
| UINT64 | Alignment |
| Required alignment of the allocation. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom pointer to be associated with the allocation. | |
Public Member Functions | |
| CVIRTUAL_BLOCK_DESC ()=default | |
| CVIRTUAL_BLOCK_DESC ()=default | |
| Default constructor. Leaves the structure uninitialized. | |
| CVIRTUAL_BLOCK_DESC (const VIRTUAL_BLOCK_DESC &o) noexcept | |
| CVIRTUAL_BLOCK_DESC (const VIRTUAL_BLOCK_DESC &o) noexcept | |
| Constructor initializing from the base D3D12MA::VIRTUAL_BLOCK_DESC structure. | |
| CVIRTUAL_BLOCK_DESC (UINT64 size, VIRTUAL_BLOCK_FLAGS flags=VIRTUAL_BLOCK_FLAG_NONE, const ALLOCATION_CALLBACKS *allocationCallbacks=NULL) noexcept | |
| CVIRTUAL_BLOCK_DESC (UINT64 size, VIRTUAL_BLOCK_FLAGS flags=VIRTUAL_BLOCK_FLAG_NONE, const ALLOCATION_CALLBACKS *allocationCallbacks=NULL) noexcept | |
| Constructor initializing description of a virtual block with given parameters. | |
Additional Inherited Members | |
| Public Attributes inherited from D3D12MA::VIRTUAL_BLOCK_DESC | |
| VIRTUAL_BLOCK_FLAGS | Flags |
| VIRTUAL_BLOCK_FLAGS | Flags |
| Flags. | |
| UINT64 | Size |
| UINT64 | Size |
| Total size of the block. | |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| Custom CPU memory allocation callbacks. Optional. | |
Public Attributes | |
| DEFRAGMENTATION_FLAGS | Flags |
| DEFRAGMENTATION_FLAGS | Flags |
| Flags. | |
| UINT64 | MaxBytesPerPass |
| UINT64 | MaxBytesPerPass |
| Maximum numbers of bytes that can be copied during single pass, while moving allocations to different places. | |
| UINT32 | MaxAllocationsPerPass |
| UINT32 | MaxAllocationsPerPass |
| Maximum number of allocations that can be moved during single pass to a different place. | |
Public Attributes | |
| DEFRAGMENTATION_MOVE_OPERATION | Operation |
| DEFRAGMENTATION_MOVE_OPERATION | Operation |
| Operation to be performed on the allocation by DefragmentationContext::EndPass(). Default value is DEFRAGMENTATION_MOVE_OPERATION_COPY. You can modify it. | |
| Allocation * | pSrcAllocation |
| Allocation * | pSrcAllocation |
| Allocation that should be moved. | |
| Allocation * | pDstTmpAllocation |
| Temporary allocation pointing to destination memory that will replace pSrcAllocation. | |
| Allocation * | pDstTmpAllocation |
| Temporary allocation pointing to destination memory that will replace pSrcAllocation. | |
Single move of an allocation to be done for defragmentation.
@@ -127,9 +127,9 @@Temporary allocation pointing to destination memory that will replace pSrcAllocation.
+Temporary allocation pointing to destination memory that will replace pSrcAllocation.
Use it to retrieve new ID3D12Heap and offset to create new ID3D12Resource and then store it here via Allocation::SetResource().
-Public Attributes | |
| UINT32 | MoveCount |
| Number of elements in the pMoves array. | |
| DEFRAGMENTATION_MOVE * | pMoves |
| UINT32 | MoveCount |
| Number of elements in the pMoves array. | |
| DEFRAGMENTATION_MOVE * | pMoves |
| Array of moves to be performed by the user in the current defragmentation pass. | |
Number of elements in the pMoves array.
+Number of elements in the pMoves array.
@@ -127,12 +127,12 @@Array of moves to be performed by the user in the current defragmentation pass.
-Pointer to an array of MoveCount elements, owned by D3D12MA, created in DefragmentationContext::BeginPass(), destroyed in DefragmentationContext::EndPass().
+Pointer to an array of MoveCount elements, owned by D3D12MA, created in DefragmentationContext::BeginPass(), destroyed in DefragmentationContext::EndPass().
For each element, you should:
Only then you can finish defragmentation pass by calling DefragmentationContext::EndPass(). After this call, the allocation will point to the new place in memory.
@@ -147,7 +147,7 @@Public Attributes | |
| UINT64 | BytesMoved |
| UINT64 | BytesMoved |
| Total number of bytes that have been copied while moving allocations to different places. | |
| UINT64 | BytesFreed |
| UINT64 | BytesFreed |
| Total number of bytes that have been released to the system by freeing empty heaps. | |
| UINT32 | AllocationsMoved |
| UINT32 | AllocationsMoved |
| Number of allocations that have been moved to different places. | |
| UINT32 | HeapsFreed |
| UINT32 | HeapsFreed |
| Number of empty ID3D12Heap objects that have been released to the system. | |
Public Attributes | |
| Statistics | Stats |
| Statistics | Stats |
| Basic statistics. | |
| UINT | UnusedRangeCount |
| UINT | UnusedRangeCount |
| Number of free ranges of memory between allocations. | |
| UINT64 | AllocationSizeMin |
| UINT64 | AllocationSizeMin |
| Smallest allocation size. UINT64_MAX if there are 0 allocations. | |
| UINT64 | AllocationSizeMax |
| UINT64 | AllocationSizeMax |
| Largest allocation size. 0 if there are 0 allocations. | |
| UINT64 | UnusedRangeSizeMin |
| UINT64 | UnusedRangeSizeMin |
| Smallest empty range size. UINT64_MAX if there are 0 empty ranges. | |
| UINT64 | UnusedRangeSizeMax |
| UINT64 | UnusedRangeSizeMax |
| Largest empty range size. 0 if there are 0 empty ranges. | |
Public Attributes | |
| POOL_FLAGS | Flags |
| POOL_FLAGS | Flags |
| Flags for the heap. | |
| D3D12_HEAP_PROPERTIES | HeapProperties |
| D3D12_HEAP_PROPERTIES | HeapProperties |
| The parameters of memory heap where allocations of this pool should be placed. | |
| D3D12_HEAP_FLAGS | HeapFlags |
| D3D12_HEAP_FLAGS | HeapFlags |
| Heap flags to be used when allocating heaps of this pool. | |
| UINT64 | BlockSize |
| UINT64 | BlockSize |
| Size of a single heap (memory block) to be allocated as part of this pool, in bytes. Optional. | |
| UINT | MinBlockCount |
| UINT | MinBlockCount |
| Minimum number of heaps (memory blocks) to be always allocated in this pool, even if they stay empty. Optional. | |
| UINT | MaxBlockCount |
| UINT | MaxBlockCount |
| Maximum number of heaps (memory blocks) that can be allocated in this pool. Optional. | |
| UINT64 | MinAllocationAlignment |
| UINT64 | MinAllocationAlignment |
| Additional minimum alignment to be used for all allocations created from this pool. Can be 0. | |
| ID3D12ProtectedResourceSession * | pProtectedSession |
| ID3D12ProtectedResourceSession * | pProtectedSession |
| Additional parameter allowing pool to create resources with passed protected session. | |
| D3D12_RESIDENCY_PRIORITY | ResidencyPriority |
| D3D12_RESIDENCY_PRIORITY | ResidencyPriority |
| Residency priority to be set for all allocations made in this pool. Optional. | |
Public Attributes | |
| UINT | BlockCount |
| UINT | BlockCount |
| Number of D3D12 memory blocks allocated - ID3D12Heap objects and committed resources. | |
| UINT | AllocationCount |
| UINT | AllocationCount |
| Number of D3D12MA::Allocation objects allocated. | |
| UINT64 | BlockBytes |
| UINT64 | BlockBytes |
| Number of bytes allocated in memory blocks. | |
| UINT64 | AllocationBytes |
| UINT64 | AllocationBytes |
| Total number of bytes occupied by all D3D12MA::Allocation objects. | |
Total number of bytes occupied by all D3D12MA::Allocation objects.
-Always less or equal than BlockBytes. Difference (BlockBytes - AllocationBytes) is the amount of memory allocated from D3D12 but unused by any D3D12MA::Allocation.
+Always less or equal than BlockBytes. Difference (BlockBytes - AllocationBytes) is the amount of memory allocated from D3D12 but unused by any D3D12MA::Allocation.
@@ -132,7 +132,7 @@Number of D3D12MA::Allocation objects allocated.
-Committed allocations have their own blocks, so each one adds 1 to AllocationCount as well as BlockCount.
+Committed allocations have their own blocks, so each one adds 1 to AllocationCount as well as BlockCount.
@@ -174,7 +174,7 @@Public Attributes | |
| DetailedStatistics | HeapType [5] |
| DetailedStatistics | HeapType [5] |
| One element for each type of heap located at the following indices: | |
| DetailedStatistics | MemorySegmentGroup [2] |
| DetailedStatistics | MemorySegmentGroup [2] |
| One element for each memory segment group located at the following indices: | |
| DetailedStatistics | Total |
| DetailedStatistics | Total |
| Total statistics from all memory allocated from D3D12. | |
Public Attributes | |
| VIRTUAL_ALLOCATION_FLAGS | Flags |
| VIRTUAL_ALLOCATION_FLAGS | Flags |
| Flags for the virtual allocation. | |
| UINT64 | Size |
| UINT64 | Size |
| Size of the allocation. | |
| UINT64 | Alignment |
| UINT64 | Alignment |
| Required alignment of the allocation. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom pointer to be associated with the allocation. | |
Public Attributes | |
| UINT64 | Offset |
| UINT64 | Offset |
| Offset of the allocation. | |
| UINT64 | Size |
| UINT64 | Size |
| Size of the allocation. | |
| void * | pPrivateData |
| void * | pPrivateData |
| Custom pointer associated with the allocation. | |
Public Attributes | |
| VIRTUAL_BLOCK_FLAGS | Flags |
| VIRTUAL_BLOCK_FLAGS | Flags |
| Flags. | |
| UINT64 | Size |
| UINT64 | Size |
| Total size of the block. | |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| const ALLOCATION_CALLBACKS * | pAllocationCallbacks |
| Custom CPU memory allocation callbacks. Optional. | |
Public Attributes | |
| AllocHandle | AllocHandle |
| AllocHandle | AllocHandle |
| Unique idenitfier of current allocation. 0 means null/invalid. | |
You can also request a full list of allocations and free regions as a string in JSON format by calling D3D12MA::VirtualBlock::BuildStatsString. Returned string must be later freed using D3D12MA::VirtualBlock::FreeStatsString. The format of this string may differ from the one returned by the main D3D12 allocator, but it is similar.
Alternative, linear algorithm can be used with virtual allocator - see flag D3D12MA::VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR and documentation: Linear allocation algorithm.
+Alternative, linear algorithm can be used with virtual allocator - see flag D3D12MA::VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR and documentation: Linear allocation algorithm.
Note that the "virtual allocator" functionality is implemented on a level of individual memory blocks. Keeping track of a whole collection of blocks, allocating new ones when out of free space, deleting empty ones, and deciding which one to try first for a new allocation must be implemented by the user.