README.md
1# Vulkan Memory Allocator
2
3Easy to integrate Vulkan memory allocation library.
4
5**Documentation:** Browse online: [Vulkan Memory Allocator](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/) (generated from Doxygen-style comments in [include/vk_mem_alloc.h](include/vk_mem_alloc.h))
6
7**License:** MIT. See [LICENSE.txt](LICENSE.txt)
8
9**Changelog:** See [CHANGELOG.md](CHANGELOG.md)
10
11**Product page:** [Vulkan Memory Allocator on GPUOpen](https://gpuopen.com/gaming-product/vulkan-memory-allocator/)
12
13**Build status:**
14
15- Windows: [](https://ci.appveyor.com/project/adam-sawicki-amd/vulkanmemoryallocator/branch/master)
16- Linux: [](https://app.travis-ci.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)
17
18[](http://isitmaintained.com/project/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator "Average time to resolve an issue")
19
20# Problem
21
22Memory allocation and resource (buffer and image) creation in Vulkan is difficult (comparing to older graphics APIs, like D3D11 or OpenGL) for several reasons:
23
24- It requires a lot of boilerplate code, just like everything else in Vulkan, because it is a low-level and high-performance API.
25- There is additional level of indirection: `VkDeviceMemory` is allocated separately from creating `VkBuffer`/`VkImage` and they must be bound together.
26- Driver must be queried for supported memory heaps and memory types. Different GPU vendors provide different types of it.
27- It is recommended to allocate bigger chunks of memory and assign parts of them to particular resources, as there is a limit on maximum number of memory blocks that can be allocated.
28
29# Features
30
31This library can help game developers to manage memory allocations and resource creation by offering some higher-level functions:
32
331. Functions that help to choose correct and optimal memory type based on intended usage of the memory.
34 - Required or preferred traits of the memory are expressed using higher-level description comparing to Vulkan flags.
352. Functions that allocate memory blocks, reserve and return parts of them (`VkDeviceMemory` + offset + size) to the user.
36 - 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.
373. Functions that can create an image/buffer, allocate memory for it and bind them together - all in one call.
38
39Additional features:
40
41- Well-documented - description of all functions and structures provided, along with chapters that contain general description and example code.
42- Thread-safety: Library is designed to be used in multithreaded code. Access to a single device memory block referred by different buffers and textures (binding, mapping) is synchronized internally. Memory mapping is reference-counted.
43- Configuration: Fill optional members of `VmaAllocatorCreateInfo` structure to provide custom CPU memory allocator, pointers to Vulkan functions and other parameters.
44- Customization and integration with custom engines: Predefine appropriate macros to provide your own implementation of all external facilities used by the library like assert, mutex, atomic.
45- Support for memory mapping, reference-counted internally. Support for persistently mapped memory: Just allocate with appropriate flag and access the pointer to already mapped memory.
46- Support for non-coherent memory. Functions that flush/invalidate memory. `nonCoherentAtomSize` is respected automatically.
47- Support for resource aliasing (overlap).
48- Support for sparse binding and sparse residency: Convenience functions that allocate or free multiple memory pages at once.
49- Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size) and allocate memory out of it.
50- Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion.
51- Support for Vulkan 1.0, 1.1, 1.2, 1.3.
52- Support for extensions (and equivalent functionality included in new Vulkan versions):
53 - VK_KHR_dedicated_allocation: Just enable it and it will be used automatically by the library.
54 - VK_KHR_buffer_device_address: Flag `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR` is automatically added to memory allocations where needed.
55 - VK_EXT_memory_budget: Used internally if available to query for current usage and budget. If not available, it falls back to an estimation based on memory heap sizes.
56 - VK_EXT_memory_priority: Set `priority` of allocations or custom pools and it will be set automatically using this extension.
57 - VK_AMD_device_coherent_memory
58- Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted.
59- Statistics: Obtain brief or detailed statistics about the amount of memory used, unused, number of allocated blocks, number of allocations etc. - globally, per memory heap, and per memory type.
60- Debug annotations: Associate custom `void* pUserData` and debug `char* pName` with each allocation.
61- JSON dump: Obtain a string in JSON format with detailed map of internal state, including list of allocations, their string names, and gaps between them.
62- Convert this JSON dump into a picture to visualize your memory. See [tools/GpuMemDumpVis](tools/GpuMemDumpVis/README.md).
63- Debugging incorrect memory usage: Enable initialization of all allocated memory with a bit pattern to detect usage of uninitialized or freed memory. Enable validation of a magic number after every allocation to detect out-of-bounds memory corruption.
64- Support for interoperability with OpenGL.
65- Virtual allocator: Interface for using core allocation algorithm to allocate any custom data, e.g. pieces of one large buffer.
66
67# Prerequisites
68
69- Self-contained C++ library in single header file. No external dependencies other than standard C and C++ library and of course Vulkan. Some features of C++14 used. STL containers, RTTI, or C++ exceptions are not used.
70- Public interface in C, in same convention as Vulkan API. Implementation in C++.
71- Error handling implemented by returning `VkResult` error codes - same way as in Vulkan.
72- Interface documented using Doxygen-style comments.
73- Platform-independent, but developed and tested on Windows using Visual Studio. Continuous integration setup for Windows and Linux. Used also on Android, MacOS, and other platforms.
74
75# Example
76
77Basic 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:
78
79```cpp
80VkBufferCreateInfo bufferInfo = { VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO };
81bufferInfo.size = 65536;
82bufferInfo.usage = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT | VK_BUFFER_USAGE_TRANSFER_DST_BIT;
83
84VmaAllocationCreateInfo allocInfo = {};
85allocInfo.usage = VMA_MEMORY_USAGE_AUTO;
86
87VkBuffer buffer;
88VmaAllocation allocation;
89vmaCreateBuffer(allocator, &bufferInfo, &allocInfo, &buffer, &allocation, nullptr);
90```
91
92With this one function call:
93
941. `VkBuffer` is created.
952. `VkDeviceMemory` block is allocated if needed.
963. An unused region of the memory block is bound to this buffer.
97
98`VmaAllocation` is an object that represents memory assigned to this buffer. It can be queried for parameters like `VkDeviceMemory` handle and offset.
99
100# How to build
101
102On Windows it is recommended to use [CMake GUI](https://cmake.org/runningcmake/).
103
104Alternatively you can generate/open a Visual Studio from the command line:
105
106```sh
107# By default CMake picks the newest version of Visual Studio it can use
108cmake -S . -B build -D VMA_BUILD_SAMPLES=ON
109cmake --open build
110```
111
112On Linux:
113
114```sh
115cmake -S . -B build
116# Since VMA has no source files, you can skip to installation immediately
117cmake --install build --prefix build/install
118```
119
120## How to use
121
122After calling either `find_package` or `add_subdirectory` simply link the library.
123This automatically handles configuring the include directory. Example:
124
125```cmake
126find_package(VulkanMemoryAllocator CONFIG REQUIRED)
127target_link_libraries(YourGameEngine PRIVATE GPUOpen::VulkanMemoryAllocator)
128```
129
130For more info on using CMake visit the official [CMake documentation](https://cmake.org/cmake/help/latest/index.html).
131
132## Building using vcpkg
133
134You can download and install VulkanMemoryAllocator using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
135
136 git clone https://github.com/Microsoft/vcpkg.git
137 cd vcpkg
138 ./bootstrap-vcpkg.sh
139 ./vcpkg integrate install
140 ./vcpkg install vulkan-memory-allocator
141
142The 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](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
143
144# Binaries
145
146The release comes with precompiled binary executable for "VulkanSample" application which contains test suite. It is compiled using Visual Studio 2019, 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 for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads), "x64" version.
147
148# Read more
149
150See **[Documentation](https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/)**.
151
152# Software using this library
153
154- **[X-Plane](https://x-plane.com/)**
155- **[Detroit: Become Human](https://gpuopen.com/learn/porting-detroit-3/)**
156- **[Vulkan Samples](https://github.com/LunarG/VulkanSamples)** - official Khronos Vulkan samples. License: Apache-style.
157- **[Anvil](https://github.com/GPUOpen-LibrariesAndSDKs/Anvil)** - cross-platform framework for Vulkan. License: MIT.
158- **[Filament](https://github.com/google/filament)** - physically based rendering engine for Android, Windows, Linux and macOS, from Google. Apache License 2.0.
159- **[Atypical Games - proprietary game engine](https://developer.samsung.com/galaxy-gamedev/gamedev-blog/infinitejet.html)**
160- **[Flax Engine](https://flaxengine.com/)**
161- **[Godot Engine](https://github.com/godotengine/godot/)** - multi-platform 2D and 3D game engine. License: MIT.
162- **[Lightweight Java Game Library (LWJGL)](https://www.lwjgl.org/)** - includes binding of the library for Java. License: BSD.
163- **[PowerVR SDK](https://github.com/powervr-graphics/Native_SDK)** - C++ cross-platform 3D graphics SDK, from Imagination. License: MIT.
164- **[Skia](https://github.com/google/skia)** - complete 2D graphic library for drawing Text, Geometries, and Images, from Google.
165- **[The Forge](https://github.com/ConfettiFX/The-Forge)** - cross-platform rendering framework. Apache License 2.0.
166- **[VK9](https://github.com/disks86/VK9)** - Direct3D 9 compatibility layer using Vulkan. Zlib lincese.
167- **[vkDOOM3](https://github.com/DustinHLand/vkDOOM3)** - Vulkan port of GPL DOOM 3 BFG Edition. License: GNU GPL.
168- **[vkQuake2](https://github.com/kondrak/vkQuake2)** - vanilla Quake 2 with Vulkan support. License: GNU GPL.
169- **[Vulkan Best Practice for Mobile Developers](https://github.com/ARM-software/vulkan_best_practice_for_mobile_developers)** from ARM. License: MIT.
170- **[RPCS3](https://github.com/RPCS3/rpcs3)** - PlayStation 3 emulator/debugger. License: GNU GPLv2.
171- **[PPSSPP](https://github.com/hrydgard/ppsspp)** - Playstation Portable emulator/debugger. License: GNU GPLv2+.
172
173[Many other projects on GitHub](https://github.com/search?q=AMD_VULKAN_MEMORY_ALLOCATOR_H&type=Code) and some game development studios that use Vulkan in their games.
174
175# See also
176
177- **[D3D12 Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator)** - equivalent library for Direct3D 12. License: MIT.
178- **[Awesome Vulkan](https://github.com/vinjn/awesome-vulkan)** - a curated list of awesome Vulkan libraries, debuggers and resources.
179- **[vcpkg](https://github.com/Microsoft/vcpkg)** dependency manager from Microsoft also offers a port of this library.
180- **[VulkanMemoryAllocator-Hpp](https://github.com/malte-v/VulkanMemoryAllocator-Hpp)** - C++ binding for this library. License: CC0-1.0.
181- **[PyVMA](https://github.com/realitix/pyvma)** - Python wrapper for this library. Author: Jean-Sébastien B. (@realitix). License: Apache 2.0.
182- **[vk-mem](https://github.com/gwihlidal/vk-mem-rs)** - Rust binding for this library. Author: Graham Wihlidal. License: Apache 2.0 or MIT.
183- **[Haskell bindings](https://hackage.haskell.org/package/VulkanMemoryAllocator)**, **[github](https://github.com/expipiplus1/vulkan/tree/master/VulkanMemoryAllocator)** - Haskell bindings for this library. Author: Ellie Hermaszewska (@expipiplus1). License BSD-3-Clause.
184- **[vma_sample_sdl](https://github.com/rextimmy/vma_sample_sdl)** - SDL port of the sample app of this library (with the goal of running it on multiple platforms, including MacOS). Author: @rextimmy. License: MIT.
185- **[vulkan-malloc](https://github.com/dylanede/vulkan-malloc)** - Vulkan memory allocation library for Rust. Based on version 1 of this library. Author: Dylan Ede (@dylanede). License: MIT / Apache 2.0.
186
){kind=link}
){kind=link}