Home

Awesome

Vulkan Memory Allocator

Easy to integrate Vulkan memory allocation library.

Documentation: See Vulkan Memory Allocator (generated from Doxygen-style comments in include/vk_mem_alloc.h)

License: MIT. See LICENSE.txt

Changelog: See CHANGELOG.md

Product page: Vulkan Memory Allocator on GPUOpen

Build status:

Problem

Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics API-s, like D3D11 or OpenGL) for several reasons:

Features

This library can help game developers to manage memory allocations and resource creation by offering some higher-level functions:

  1. Functions that help to choose correct and optimal memory type based on intended usage of the memory.
    • Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags.
  2. Functions that allocate memory blocks, reserve and return parts of them (VkDeviceMemory + offset + size) to the user.
    • Library keeps track of allocated memory blocks, used and unused ranges inside them, finds best matching unused ranges for new allocations, respects all the rules of alignment and buffer/image granularity.
  3. Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call.

Additional features:

Prequisites

Example

Basic usage of this library is very simple. Advanced features are optional. After you created global VmaAllocator object, a complete code needed to create a buffer may look like this:

VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
bufferInfo.size = 65536;
bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;

VmaAllocationCreateInfo allocInfo = {};
allocInfo.usage = VMA_MEMORY_USAGE_GPU_ONLY;

VkBuffer buffer;
VmaAllocation allocation;
vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);

With this one function call:

  1. VkBuffer is created.
  2. VkDeviceMemory block is allocated if needed.
  3. An unused region of the memory block is bound to this buffer.

VmaAllocation is an object that represents memory assigned to this buffer. It can be queried for parameters like Vulkan memory handle and offset.

How to build

On Windows it is recommended to use CMake UI. Alternatively you can generate a Visual Studio project map using CMake in command line: cmake -B./build/ -DCMAKE_BUILD_TYPE=Debug -G "Visual Studio 16 2019" -A x64 ./

On Linux:

mkdir build
cd build
cmake ..
make

The following targets are available

TargetDescriptionCMake optionDefault setting
VmaSampleVMA sample applicationVMA_BUILD_SAMPLEOFF
VmaBuildSampleShadersShaders for VmaSampleVMA_BUILD_SAMPLE_SHADERSOFF
VmaReplayReplay tool for VMA .csv trace filesVMA_BUILD_REPLAYOFF

Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample and VmaReplay are not.

These CMake options are available

CMake optionDescriptionDefault setting
VMA_RECORDING_ENABLEDEnable VMA memory recording for debuggingOFF
VMA_USE_STL_CONTAINERSUse C++ STL containers instead of VMA's containersOFF
VMA_STATIC_VULKAN_FUNCTIONSLink statically with Vulkan APIOFF
VMA_DYNAMIC_VULKAN_FUNCTIONSFetch pointers to Vulkan functions internally (no static linking)ON
VMA_DEBUG_ALWAYS_DEDICATED_MEMORYEvery allocation will have its own memory blockOFF
VMA_DEBUG_INITIALIZE_ALLOCATIONSAutomatically fill new allocations and destroyed allocations with some bit patternOFF
VMA_DEBUG_GLOBAL_MUTEXEnable single mutex protecting all entry calls to the libraryOFF
VMA_DEBUG_DONT_EXCEED_MAX_MEMORY_ALLOCATION_COUNTNever exceed VkPhysicalDeviceLimits::maxMemoryAllocationCount and return errorOFF

Binaries

The release comes with precompiled binary executables for "VulkanSample" application which contains test suite and "VmaReplay" tool. They are compiled using Visual Studio 2019, so they require appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If their launch fails with error message telling about those files missing, please download and install Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019, "x64" version.

Read more

See Documentation.

Software using this library

Many other projects on GitHub and some game development studios that use Vulkan in their games.

See also