search

GPUOpen-LibrariesAndSDKs / VulkanMemoryAllocator

Easy to integrate Vulkan memory allocation library
MIT License
2.48k stars 334 forks source link
memory-management vulkan

readme

Vulkan Memory Allocator

Easy to integrate Vulkan memory allocation library.

Documentation: Browse online: 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:

Average time to resolve an issue

Problem

Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics APIs, 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:

Prerequisites

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

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 VkDeviceMemory handle and offset.

How to build

On Windows it is recommended to use CMake GUI.

Alternatively you can generate/open a Visual Studio from the command line:

# By default CMake picks the newest version of Visual Studio it can use
cmake -S .  -B build -D VMA_BUILD_SAMPLES=ON
cmake --open build

On Linux:

cmake -S . -B build
# Since VMA has no source files, you can skip to installation immediately
cmake --install build --prefix build/install

How to use

After calling either find_package or add_subdirectory simply link the library. This automatically handles configuring the include directory. Example:

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

For more info on using CMake visit the official CMake documentation.

Building using vcpkg

You can download and install VulkanMemoryAllocator using the vcpkg dependency manager:

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

The VulkanMemoryAllocator port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

Binaries

The release comes with precompiled binary executable for "VulkanSample" application which contains test suite. It is compiled using Visual Studio 2022, so it requires appropriate libraries to work, including "MSVCP140.dll", "VCRUNTIME140.dll", "VCRUNTIME140_1.dll". If the launch fails with error message telling about those files missing, please download and install Microsoft Visual C++ Redistributable, "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