commit | aee61b1d2548e71070077a193c9bbcf5f018f680 | [log] [tgz] |
---|---|---|
author | Adam Sawicki <adam.sawicki@amd.com> | Thu Feb 17 14:44:06 2022 +0100 |
committer | Adam Sawicki <adam.sawicki@amd.com> | Thu Feb 17 14:44:06 2022 +0100 |
tree | a2199dc18a700b046e69f1296e349016539285f4 | |
parent | b41615cfce1bc895b3ead88baa69c7ca345def51 [diff] |
Added new API for selecting preferred memory type: VMA_MEMORY_USAGE_AUTO, VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE, VMA_MEMORY_USAGE_AUTO_PREFER_HOST, VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT, VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT, VMA_ALLOCATION_CREATE_HOST_ACCESS_ALLOW_TRANSFER_INSTEAD_BIT Old values like VMA_MEMORY_USAGE_GPU_ONLY still work as before, for backward compatibility. Updated documentation accordingly. Introduced a concept of mappable and non-mappable allocations - with VMA_MEMORY_USAGE_AUTO* an intent to map has to be specified using VMA_ALLOCATION_CREATE_HOST_ACCESS*. Added mapping hysteresis logic (internal class VmaMappingHysteresis, config macro VMA_MAPPING_HYSTERESIS_ENABLED) that prevents too many calls vkMapMemory/vkUnmapMemory back and forth. Internal improvement in VmaBlockVector::AllocatePage to try to keep mappable and non-mappable allocations separate.
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:
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:
VkDeviceMemory
is allocated separately from creating VkBuffer
/VkImage
and they must be bound together.This library can help game developers to manage memory allocations and resource creation by offering some higher-level functions:
VkDeviceMemory
+ offset + size) to the user.Additional features:
nonCoherentAtomSize
is respected automatically.VkResult
error codes - same way as in Vulkan.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:
VkBuffer
is created.VkDeviceMemory
block is allocated if needed.VmaAllocation
is an object that represents memory assigned to this buffer. It can be queried for parameters like Vulkan memory handle and offset.
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
Target | Description | CMake option | Default setting |
---|---|---|---|
VmaSample | VMA sample application | VMA_BUILD_SAMPLE | OFF |
VmaBuildSampleShaders | Shaders for VmaSample | VMA_BUILD_SAMPLE_SHADERS | OFF |
VmaReplay | Replay tool for VMA .csv trace files | VMA_BUILD_REPLAY | OFF |
Please note that while VulkanMemoryAllocator library is supported on other platforms besides Windows, VmaSample and VmaReplay are not.
These CMake options are available
CMake option | Description | Default setting |
---|---|---|
VMA_RECORDING_ENABLED | Enable VMA memory recording for debugging | OFF |
VMA_USE_STL_CONTAINERS | Use C++ STL containers instead of VMA's containers | OFF |
VMA_STATIC_VULKAN_FUNCTIONS | Link statically with Vulkan API | OFF |
VMA_DYNAMIC_VULKAN_FUNCTIONS | Fetch pointers to Vulkan functions internally (no static linking) | ON |
VMA_DEBUG_ALWAYS_DEDICATED_MEMORY | Every allocation will have its own memory block | OFF |
VMA_DEBUG_INITIALIZE_ALLOCATIONS | Automatically fill new allocations and destroyed allocations with some bit pattern | OFF |
VMA_DEBUG_GLOBAL_MUTEX | Enable single mutex protecting all entry calls to the library | OFF |
VMA_DEBUG_DONT_EXCEED_MAX_MEMORY_ALLOCATION_COUNT | Never exceed VkPhysicalDeviceLimits::maxMemoryAllocationCount and return error | OFF |
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.
See Documentation.
Many other projects on GitHub and some game development studios that use Vulkan in their games.