Vulkan Memory Allocator (VMA)

VMA simplifies Vulkan memory management by providing:

• Optimal Memory Selection: Functions to choose memory types based on usage traits.
• Block Management: Automatic tracking of used/unused ranges, alignment, and granularity.
• Unified Creation: Functions to create, allocate, and bind buffers/images in one call.
• Thread Safety: Internal synchronization for multi-threaded access to memory blocks.
• Advanced Features: Support for defragmentation, custom memory pools, linear allocators, sparse binding, and resource aliasing.
• Debugging Tools: JSON state dumps, debug annotations (pName, pUserData), and memory initialization patterns to detect uninitialized usage.

VMA is a header-only library (single header file), so you can skip the installation step after building if you only need the headers.

On Windows: Use CMake GUI or the command line to generate a Visual Studio solution.

On Linux: Generate the build files and install to a local prefix.

# Windows
cmake -S .  -B build -D VMA_BUILD_SAMPLES=ON
cmake --open build

# Linux
cmake -S . -B build
cmake --install build --prefix build/install

To use the GpuMemDumpVis visualization tool, ensure you have the following installed on your system:

• Python 3
• Pillow (Python Imaging Library fork)

You can install the library using the vcpkg dependency manager. This is useful for automated dependency management in C++ projects.

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install vulkan-memory-allocator

GpuMemDumpVis is a Python script used to visualize the internal state of Vulkan Memory Allocator (VMA) or D3D12 Memory Allocator (D3D12MA) libraries.

To generate a visualization, you must provide a JSON dump file (generated via vmaBuildStatsString() or D3D12MA::Allocator::BuildStatsString()) and specify an output image path. The output format (e.g., PNG, JPEG, BMP) is determined by the file extension provided.

python GpuMemDumpVis.py -o OUTPUT_FILE INPUT_FILE

To use VMA in a CMake-based project, use find_package or add_subdirectory. Linking to the target GPUOpen::VulkanMemoryAllocator will automatically configure the necessary include directories.

find_package(VulkanMemoryAllocator CONFIG REQUIRED)
target_link_libraries(YourGameEngine PRIVATE GPUOpen::VulkanMemoryAllocator)

The simplest way to create a buffer and its associated memory is using vmaCreateBuffer. This single call creates the VkBuffer, allocates the required VkDeviceMemory, and binds them together.

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_AUTO;

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

The following command-line arguments are available for the GpuMemDumpVis.py script:

• INPUT_FILE: Path to the source JSON file containing the allocator's internal state (UTF-8/UTF-16 encoding).
• OUTPUT_FILE: Path to the destination image file.
• -h: Display help on command line syntax.
• -v: Display the program version number.