This flag is fetched from D3D12_FEATURE_D3D12_OPTIONS16::GPUUploadHeapSupported.
+ + + +| BOOL D3D12MA::Allocator::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.
+By default, allocations are laid out in memory blocks next to each other if possible (considering required alignment returned by ID3D12Device::GetResourceAllocationInfo).
diff --git a/docs/html/doxygen_crawl.html b/docs/html/doxygen_crawl.html index 6b8ae0b..c4ffff1 100644 --- a/docs/html/doxygen_crawl.html +++ b/docs/html/doxygen_crawl.html @@ -53,6 +53,7 @@ + @@ -187,6 +188,7 @@ + diff --git a/docs/html/functions.html b/docs/html/functions.html index e1beea4..de18e05 100644 --- a/docs/html/functions.html +++ b/docs/html/functions.html @@ -170,6 +170,7 @@Version 3.0.2 (2025-XX-XX)
+Version 3.1.0-development (2025-XX-XX)
Copyright (c) 2019-2025 Advanced Micro Devices, Inc. All rights reserved.
License: MIT
Documentation of all members: D3D12MemAlloc.h
diff --git a/docs/html/namespace_d3_d12_m_a.html b/docs/html/namespace_d3_d12_m_a.html index b4ae5de..d801b62 100644 --- a/docs/html/namespace_d3_d12_m_a.html +++ b/docs/html/namespace_d3_d12_m_a.html @@ -191,6 +191,7 @@ ,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.
+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.
+If the tight resource alignment feature is used by the library (which happens automatically whenever supported, unless you use flag ALLOCATOR_FLAG_DONT_USE_TIGHT_ALIGNMENT), then small buffers are not preferred as committed. Long story short, you don't need to specify any of these flags. The library chooses the most optimal method automatically.
+Disables the use of the tight alignment feature even when it is supported on the current system. By default, the feature is used whenever available.
+Support can be checked by D3D12MA::Allocator::IsTightAlignmentSupported() regardless of using this flag.
When you have a committed allocation created, you can also set the residency priority of its resource using the D3D12 function:
Because the alignment required for buffers is 64 KB, small buffers can waste a lot of memory in between when created as placed. When such small buffers are created as committed, some graphics drivers are able to pack them better. D3D12MA automatically takes advantage of this by preferring to create small buffers as committed. This heuristics is enabled by default. It is also a tradeoff - it can make the allocation of these buffers slower. It can be disabled for an individual resource by using D3D12MA::ALLOCATION_FLAG_STRATEGY_MIN_TIME and for the entire allocator by using D3D12MA::ALLOCATOR_FLAG_DONT_PREFER_SMALL_BUFFERS_COMMITTED.
For certain textures that meet a complex set of requirements, special "small alignment" can be applied. Details can be found in Microsoft documentation of the D3D12_RESOURCE_DESC structure. For MSAA textures, the small alignment is D3D12_SMALL_MSAA_RESOURCE_PLACEMENT_ALIGNMENT = 64 KB. For other textures, the small alignment is D3D12_SMALL_RESOURCE_PLACEMENT_ALIGNMENT = 4 KB. D3D12MA uses this feature automatically. Detailed behavior can be disabled or controlled by predefining macro D3D12MA_USE_SMALL_RESOURCE_PLACEMENT_ALIGNMENT.
-D3D12 also has a concept of alignment of the entire heap, passed through D3D12_HEAP_DESC::Alignment. This library automatically sets the alignment as small as possible. Unfortunately, any heap that has a chance of hosting an MSAA texture needs to have the alignment set to 4 MB. This problem can be overcome by passing D3D12MA::ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED on the creation of the main allocator object and D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED on the creation of any custom heap that supports textures, not only buffers. With those flags, the alignment of the heaps created by D3D12MA can be lower, but any MSAA textures are created as committed. You should always use these flags in your code unless you really need to create some MSAA textures as placed.
+D3D12 also has a concept of alignment of the entire heap, passed through D3D12_HEAP_DESC::Alignment. This library automatically sets the alignment as small as possible. Unfortunately, any heap that has a chance of hosting an MSAA texture needs to have the alignment set to 4 MB. This problem can be overcome by passing D3D12MA::ALLOCATOR_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED on the creation of the main allocator object and D3D12MA::POOL_FLAG_MSAA_TEXTURES_ALWAYS_COMMITTED on the creation of any custom heap that supports textures, not only buffers. With those flags, the alignment of the heaps created by D3D12MA can be lower, but any MSAA textures are created as committed. You should always use these flags in your code unless you really need to create some MSAA textures as placed.
+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.
(5.) Right before destroying the D3D12 device, destroy the allocator object.
D3D12MA::VirtualBlock object contains internal data structure that keeps track of free and occupied regions using the same code as the main D3D12 memory allocator. A single allocation is identified by a lightweight structure D3D12MA::VirtualAllocation. You will also likely want to know the offset at which the allocation was made in the block.
@@ -119,8 +119,8 @@Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places: