<p>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.</p>
<p>"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.</p>
<p>This library includes header <code><vulkan/vulkan.h></code>, which in turn includes <code><windows.h></code> on Windows. If you need some specific macros defined before including these headers (like <code>WIN32_LEAN_AND_MEAN</code> or <code>WINVER</code> for Windows, <code>VK_USE_PLATFORM_WIN32_KHR</code> for Vulkan), you must define them before every <code>#include</code> of this library.</p>
<p>This library is written in C++, but has C-compatible interface. Thus you can include and use <aclass="el"href="vk__mem__alloc_8h.html">vk_mem_alloc.h</a> in C or C++ code, but full implementation with <code>VMA_IMPLEMENTATION</code> 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.</p>
<li>Fill <aclass="el"href="struct_vma_allocator_create_info.html"title="Description of a Allocator to be created.">VmaAllocatorCreateInfo</a> structure and create <aclass="el"href="struct_vma_allocator.html"title="Represents main object of this library initialized.">VmaAllocator</a> object by calling <aclass="el"href="group__group__init.html#ga200692051ddb34240248234f5f4c17bb"title="Creates VmaAllocator object.">vmaCreateAllocator()</a>.</li>
<p>Only members <code>physicalDevice</code>, <code>device</code>, <code>instance</code> are required. However, you should inform the library which Vulkan version do you use by setting <aclass="el"href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285"title="Optional. The highest version of Vulkan that the application is designed to use.">VmaAllocatorCreateInfo::vulkanApiVersion</a> and which extensions did you enable by setting <aclass="el"href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346"title="Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.">VmaAllocatorCreateInfo::flags</a> (like <aclass="el"href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7ca5f1b28b0414319d1687e1f2b30ab0089">VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT</a> for VK_KHR_buffer_device_address). Otherwise, VMA would use only features of Vulkan 1.0 core with no extensions.</p>
<p>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 proces.</p>
<p><b>Step 1: Compile time.</b> By default, VMA compiles with code supporting the highest Vulkan version found in the included <code><vulkan/vulkan.h></code> 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 <code>VMA_VULKAN_VERSION</code> before every <code>#include "vk_mem_alloc.h"</code>. 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:</p>
</div><!-- fragment --><p><b>Step 2: Runtime.</b> Even when compiled with higher Vulkan version available, VMA can use only features of a lower version, which is configurable during creation of the <aclass="el"href="struct_vma_allocator.html"title="Represents main object of this library initialized.">VmaAllocator</a> object. By default, only Vulkan 1.0 is used. To initialize the allocator with support for higher Vulkan version, you need to set member <aclass="el"href="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285"title="Optional. The highest version of Vulkan that the application is designed to use.">VmaAllocatorCreateInfo::vulkanApiVersion</a> to an appropriate value, e.g. using constants like <code>VK_API_VERSION_1_2</code>. See code sample below.</p>
<p>You may need to configure importing Vulkan functions. There are 3 ways to do this:</p>
<oltype="1">
<li><b>If you link with Vulkan static library</b> (e.g. "vulkan-1.lib" on Windows):<ul>
<li>You don't need to do anything.</li>
<li>VMA will use these, as macro <code>VMA_STATIC_VULKAN_FUNCTIONS</code> is defined to 1 by default.</li>
</ul>
</li>
<li><b>If you want VMA to fetch pointers to Vulkan functions dynamically</b> using <code>vkGetInstanceProcAddr</code>, <code>vkGetDeviceProcAddr</code> (this is the option presented in the example below):<ul>
<li>Define <code>VMA_STATIC_VULKAN_FUNCTIONS</code> to 0, <code>VMA_DYNAMIC_VULKAN_FUNCTIONS</code> to 1.</li>
<li>Provide pointers to these two functions via <aclass="el"href="struct_vma_vulkan_functions.html#a3eafa102f5f8915f093f40675636b849"title="Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.">VmaVulkanFunctions::vkGetInstanceProcAddr</a>, <aclass="el"href="struct_vma_vulkan_functions.html#ac383ab9af127e5e136622fa4ebea9e57"title="Required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.">VmaVulkanFunctions::vkGetDeviceProcAddr</a>.</li>
<li>The library will fetch pointers to all other functions it needs internally.</li>
</ul>
</li>
<li><b>If you fetch pointers to all Vulkan functions in a custom way</b>, e.g. using some loader like <ahref="https://github.com/zeux/volk">Volk</a>:<ul>
<li>Define <code>VMA_STATIC_VULKAN_FUNCTIONS</code> and <code>VMA_DYNAMIC_VULKAN_FUNCTIONS</code> to 0.</li>
<li>Pass these pointers via structure <aclass="el"href="struct_vma_vulkan_functions.html"title="Pointers to some Vulkan functions - a subset used by the library.">VmaVulkanFunctions</a>.</li>
<divclass="ttc"id="astruct_vma_allocator_create_info_html"><divclass="ttname"><ahref="struct_vma_allocator_create_info.html">VmaAllocatorCreateInfo</a></div><divclass="ttdoc">Description of a Allocator to be created.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:998</div></div>
<divclass="ttc"id="astruct_vma_allocator_create_info_html_a3dc197be3227da7338b1643f70db36bd"><divclass="ttname"><ahref="struct_vma_allocator_create_info.html#a3dc197be3227da7338b1643f70db36bd">VmaAllocatorCreateInfo::pVulkanFunctions</a></div><divclass="ttdeci">const VmaVulkanFunctions * pVulkanFunctions</div><divclass="ttdoc">Pointers to Vulkan functions. Can be null.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1046</div></div>
<divclass="ttc"id="astruct_vma_allocator_create_info_html_a70dd42e29b1df1d1b9b61532ae0b370b"><divclass="ttname"><ahref="struct_vma_allocator_create_info.html#a70dd42e29b1df1d1b9b61532ae0b370b">VmaAllocatorCreateInfo::instance</a></div><divclass="ttdeci">VkInstance instance</div><divclass="ttdoc">Handle to Vulkan instance object.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1051</div></div>
<divclass="ttc"id="astruct_vma_allocator_create_info_html_ae0ffc55139b54520a6bb704b29ffc285"><divclass="ttname"><ahref="struct_vma_allocator_create_info.html#ae0ffc55139b54520a6bb704b29ffc285">VmaAllocatorCreateInfo::vulkanApiVersion</a></div><divclass="ttdeci">uint32_t vulkanApiVersion</div><divclass="ttdoc">Optional. The highest version of Vulkan that the application is designed to use.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1060</div></div>
<divclass="ttc"id="astruct_vma_allocator_html"><divclass="ttname"><ahref="struct_vma_allocator.html">VmaAllocator</a></div><divclass="ttdoc">Represents main object of this library initialized.</div></div>
<li>Fill <aclass="el"href="struct_vma_allocation_create_info.html"title="Parameters of new VmaAllocation.">VmaAllocationCreateInfo</a> structure.</li>
<li>Call <aclass="el"href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51"title="Creates a new VkBuffer, allocates and binds memory for it.">vmaCreateBuffer()</a> / <aclass="el"href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73"title="Function similar to vmaCreateBuffer().">vmaCreateImage()</a> to get <code>VkBuffer</code>/<code>VkImage</code> with memory already allocated and bound to it, plus <aclass="el"href="struct_vma_allocation.html"title="Represents single memory allocation.">VmaAllocation</a> objects that represents its underlying memory.</li>
<divclass="ttc"id="astruct_vma_allocation_create_info_html"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><divclass="ttdoc">Parameters of new VmaAllocation.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1219</div></div>
<divclass="ttc"id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><divclass="ttname"><ahref="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><divclass="ttdeci">VmaMemoryUsage usage</div><divclass="ttdoc">Intended usage of memory.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1227</div></div>
<divclass="ttc"id="astruct_vma_allocation_html"><divclass="ttname"><ahref="struct_vma_allocation.html">VmaAllocation</a></div><divclass="ttdoc">Represents single memory allocation.</div></div>
