- Generated on Mon Oct 9 2023 13:49:04 for Open 3D Engine Atom Gem API Reference by
1.9.6
This is a small, standalone C++ library. It consists of a pair of 2 files: "D3D12MemAlloc.h" header file with public interface and "D3D12MemAlloc.cpp" with internal implementation. The only external dependencies are WinAPI, Direct3D 12, and parts of C/C++ standard library (but STL containers, exceptions, or RTTI are not used).
The library is developed and tested using Microsoft Visual Studio 2019, but it should work with other compilers as well. It is designed for 64-bit code.
To use the library in your project:
(1.) Copy files D3D12MemAlloc.cpp, D3D12MemAlloc.h to your project.
(2.) Make D3D12MemAlloc.cpp compiling as part of the project, as C++ code.
(3.) Include library header in each CPP file that needs to use the library.
(4.) Right after you created ID3D12Device, fill D3D12MA::ALLOCATOR_DESC structure and call function D3D12MA::CreateAllocator to create the main D3D12MA::Allocator object.
Please note that all symbols of the library are declared inside #D3D12MA namespace.
(5.) Right before destroying the D3D12 device, destroy the allocator object.
Objects of this library must be destroyed by calling Release method. They are somewhat compatible with COM: they implement IUnknown interface with its virtual methods: AddRef, Release, QueryInterface, and they are reference-counted internally. You can use smart pointers designed for COM with objects of this library - e.g. CComPtr or Microsoft::WRL::ComPtr. The reference counter is thread-safe. QueryInterface method supports only IUnknown, as classes of this library don't define their own GUIDs.
To use the library for creating resources (textures and buffers), call method D3D12MA::Allocator::CreateResource in the place where you would previously call ID3D12Device::CreateCommittedResource.
The function has similar syntax, but it expects structure D3D12MA::ALLOCATION_DESC to be passed along with D3D12_RESOURCE_DESC and other parameters for created resource. This structure describes parameters of the desired memory allocation, including choice of D3D12_HEAP_TYPE.
The function returns a new object of type D3D12MA::Allocation. It represents allocated memory and can be queried for size, offset, ID3D12Heap. It also holds a reference to the ID3D12Resource, which can be accessed by calling D3D12MA::Allocation::GetResource().
You need to release the allocation object when no longer needed. This will also release the D3D12 resource.
The advantage of using the allocator instead of creating committed resource, and the main purpose of this library, is that it can decide to allocate bigger memory heap internally using ID3D12Device::CreateHeap and place multiple resources in it, at different offsets, using ID3D12Device::CreatePlacedResource. The library manages its own collection of allocated memory blocks (heaps) and remembers which parts of them are occupied and which parts are free to be used for new resources.
It is important to remember that resources created as placed don't have their memory initialized to zeros, but may contain garbage data, so they need to be fully initialized before usage, e.g. using Clear (ClearRenderTargetView), Discard (DiscardResource), or copy (CopyResource).
The library also automatically handles resource heap tier. When D3D12_FEATURE_DATA_D3D12_OPTIONS::ResourceHeapTier equals D3D12_RESOURCE_HEAP_TIER_1, resources of 3 types: buffers, textures that are render targets or depth-stencil, and other textures must be kept in separate heaps. When D3D12_RESOURCE_HEAP_TIER_2, they can be kept together. By using this library, you don't need to handle this manually.
ID3D12Resource and other interfaces of Direct3D 12 use COM, so they are reference-counted. Objects of this library are reference-counted as well. An object of type D3D12MA::Allocation remembers the resource (buffer or texture) that was created together with this memory allocation and holds a reference to the ID3D12Resource object. (Note this is a difference to Vulkan Memory Allocator, where a VmaAllocation object has no connection with the buffer or image that was created with it.) Thus, it is important to manage the resource reference counter properly.
The simplest use case is shown in the code snippet above. When only D3D12MA::Allocation object is obtained from a function call like D3D12MA::Allocator::CreateResource, it remembers the ID3D12Resource that was created with it and holds a reference to it. The resource can be obtained by calling allocation->GetResource(), which doesn't increment the resource reference counter. Calling allocation->Release() will decrease the resource reference counter, which is = 1 in this case, so the resource will be released.
Second option is to retrieve a pointer to the resource along with D3D12MA::Allocation. Last parameters of the resource creation function can be used for this purpose.
In this case, returned pointer resource is equal to allocation->GetResource(), but the creation function additionally increases resource reference counter for the purpose of returning it from this call (it actually calls QueryInterface internally), so the resource will have the counter = 2. The resource then need to be released along with the allocation, in this particular order, to make sure the resource is destroyed before its memory heap can potentially be freed.
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.
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.
Mapping happens on the level of particular resources, not entire memory heaps, and so it is out of scope of this library. Just as the documentation of the Map function says:
When using this library, you can map and use your resources normally without considering whether they are created as committed resources or placed resources in one large heap.
Example for buffer created and filled in UPLOAD heap type:
Vulkan Memory Allocator comes in form of a "stb-style" single header file. You don't need to build it as a separate library project. You can add this file directly to your project and submit it to code repository next to your other source files.
"Single header" doesn't mean that everything is contained in C/C++ declarations, like it tends to be in case of inline functions or C++ templates. It means that implementation is bundled with interface in a single file and needs to be extracted using preprocessor macro. If you don't do it properly, you will get linker errors.
To do it properly:
It may be a good idea to create dedicated CPP file just for this purpose.
This library includes header <vulkan/vulkan.h>, which in turn includes <windows.h> on Windows. If you need some specific macros defined before including these headers (like WIN32_LEAN_AND_MEAN or WINVER for Windows, VK_USE_PLATFORM_WIN32_KHR for Vulkan), you must define them before every #include of this library.
This library is written in C++, but has C-compatible interface. Thus you can include and use vk_mem_alloc.h in C or C++ code, but full implementation with VMA_IMPLEMENTATION macro must be compiled as C++, NOT as C. Some features of C++14 are used. STL containers, RTTI, or C++ exceptions are not used.
At program startup:
VkPhysicalDevice, VkDevice and VkInstance object.Only members physicalDevice, device, instance are required. However, you should inform the library which Vulkan version do you use by setting VmaAllocatorCreateInfo::vulkanApiVersion and which extensions did you enable by setting VmaAllocatorCreateInfo::flags (like VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT for VK_KHR_buffer_device_address). Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions.
VMA supports Vulkan version down to 1.0, for backward compatibility. If you want to use higher version, you need to inform the library about it. This is a two-step process.
Step 1: Compile time. By default, VMA compiles with code supporting the highest Vulkan version found in the included <vulkan/vulkan.h> that is also supported by the library. If this is OK, you don't need to do anything. However, if you want to compile VMA as if only some lower Vulkan version was available, define macro VMA_VULKAN_VERSION before every #include "vk_mem_alloc.h". It should have decimal numeric value in form of ABBBCCC, where A = major, BBB = minor, CCC = patch Vulkan version. For example, to compile against Vulkan 1.2:
Step 2: Runtime. Even when compiled with higher Vulkan version available, VMA can use only features of a lower version, which is configurable during creation of the VmaAllocator object. By default, only Vulkan 1.0 is used. To initialize the allocator with support for higher Vulkan version, you need to set member VmaAllocatorCreateInfo::vulkanApiVersion to an appropriate value, e.g. using constants like VK_API_VERSION_1_2. See code sample below.
You may need to configure importing Vulkan functions. There are 3 ways to do this:
VMA_STATIC_VULKAN_FUNCTIONS is defined to 1 by default.vkGetInstanceProcAddr, vkGetDeviceProcAddr (this is the option presented in the example below):VMA_STATIC_VULKAN_FUNCTIONS to 0, VMA_DYNAMIC_VULKAN_FUNCTIONS to 1.VMA_STATIC_VULKAN_FUNCTIONS and VMA_DYNAMIC_VULKAN_FUNCTIONS to 0.Example for case 2:
When you want to create a buffer or image:
VkBufferCreateInfo / VkImageCreateInfo structure.VkBuffer/VkImage with memory already allocated and bound to it, plus VmaAllocation objects that represents its underlying memory.Don't forget to destroy your objects when no longer needed:
1.9.6