VulkanMemoryAllocator/CHANGELOG.md

3.0.0 (2022-03-25)

It has been a long time since the previous official release, so hopefully everyone has been using the latest code from "master" branch, which is always maintained in a good state, not the old version. For completeness, here is the list of changes since v2.3.0. The major version number has changed, so there are some compatibility-breaking changes, but the basic API stays the same and is mostly backward-compatible.

Major features added (some compatibility-breaking):

• Added new API for selecting preferred memory type: flags 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, but are not recommended.
• Added new defragmentation API and algorithm, replacing the old one. See structure VmaDefragmentationInfo, VmaDefragmentationMove, VmaDefragmentationPassMoveInfo, VmaDefragmentationStats, function vmaBeginDefragmentation, vmaEndDefragmentation, vmaBeginDefragmentationPass, vmaEndDefragmentationPass.
• Redesigned API for statistics, replacing the old one. See structures: VmaStatistics, VmaDetailedStatistics, VmaTotalStatistics. VmaBudget, functions: vmaGetHeapBudgets, vmaCalculateStatistics, vmaGetPoolStatistics, vmaCalculatePoolStatistics, vmaGetVirtualBlockStatistics, vmaCalculateVirtualBlockStatistics.
• Added "Virtual allocator" feature - possibility to use core allocation algorithms for allocation of custom memory, not necessarily Vulkan device memory. See functions like vmaCreateVirtualBlock, vmaDestroyVirtualBlock and many more.
• VmaAllocation now keeps both void* pUserData and char* pName. Added function vmaSetAllocationName, member VmaAllocationInfo::pName. Flag VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT is now deprecated.
• Clarified and cleaned up various ways of importing Vulkan functions. See macros VMA_STATIC_VULKAN_FUNCTIONS, VMA_DYNAMIC_VULKAN_FUNCTIONS, structure VmaVulkanFunctions. Added members VmaVulkanFunctions::vkGetInstanceProcAddr, vkGetDeviceProcAddr, which are now required when using VMA_DYNAMIC_VULKAN_FUNCTIONS.

Removed (compatibility-breaking):

• Removed whole "lost allocations" feature. Removed from the interface: VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT, VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT, vmaCreateLostAllocation, vmaMakePoolAllocationsLost, vmaTouchAllocation, VmaAllocatorCreateInfo::frameInUseCount, VmaPoolCreateInfo::frameInUseCount.
• Removed whole "record & replay" feature. Removed from the API: VmaAllocatorCreateInfo::pRecordSettings, VmaRecordSettings, VmaRecordFlagBits, VmaRecordFlags. Removed VmaReplay application.
• Removed "buddy" algorithm - removed flag VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT.

Minor but compatibility-breaking changes:

• Changes in ALLOCATION_CREATE_STRATEGY flags. Removed flags: VMA_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_BIT, VMA_ALLOCATION_CREATE_STRATEGY_WORST_FIT_BIT, VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_BIT, which were aliases to other existing flags.
• Added a member void* pUserData to VmaDeviceMemoryCallbacks. Updated PFN_vmaAllocateDeviceMemoryFunction, PFN_vmaFreeDeviceMemoryFunction to use the new pUserData member.
• Removed function vmaResizeAllocation that was already deprecated.

Other major changes:

• Added new features to custom pools: support for dedicated allocations, new member VmaPoolCreateInfo::pMemoryAllocateNext, minAllocationAlignment.
• Added support for Vulkan 1.2, 1.3.
• Added support for VK_KHR_buffer_device_address extension - flag VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT.
• Added support for VK_EXT_memory_priority extension - flag VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT, members VmaAllocationCreateInfo::priority, VmaPoolCreateInfo::priority.
• Added support for VK_AMD_device_coherent_memory extension - flag VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT.
• Added member VmaAllocatorCreateInfo::pTypeExternalMemoryHandleTypes.
• Added function vmaGetAllocatorInfo, structure VmaAllocatorInfo.
• Added functions vmaFlushAllocations, vmaInvalidateAllocations for multiple allocations at once.
• Added flag VMA_ALLOCATION_CREATE_CAN_ALIAS_BIT.
• Added function vmaCreateBufferWithAlignment.
• Added convenience function vmaGetAllocationMemoryProperties.
• Added convenience functions: vmaCreateAliasingBuffer, vmaCreateAliasingImage.

Other minor changes:

• Implemented Two-Level Segregated Fit (TLSF) allocation algorithm, replacing previous default one. It is much faster, especially when freeing many allocations at once or when bufferImageGranularity is large.
• Renamed debug macro VMA_DEBUG_ALIGNMENT to VMA_MIN_ALIGNMENT.
• Added CMake support - CMakeLists.txt files. Removed Premake support.
• Changed vmaInvalidateAllocation and vmaFlushAllocation to return VkResult.
• Added nullability annotations for Clang: VMA_NULLABLE, VMA_NOT_NULL, VMA_NULLABLE_NON_DISPATCHABLE, VMA_NOT_NULL_NON_DISPATCHABLE, VMA_LEN_IF_NOT_NULL.
• JSON dump format has changed.
• Countless fixes and improvements, including performance optimizations, compatibility with various platforms and compilers, documentation.

2.3.0 (2019-12-04)

Major release after a year of development in "master" branch and feature branches. Notable new features: supporting Vulkan 1.1, supporting query for memory budget.

Major changes:

• Added support for Vulkan 1.1.
  • Added member VmaAllocatorCreateInfo::vulkanApiVersion.
  • When Vulkan 1.1 is used, there is no need to enable VK_KHR_dedicated_allocation or VK_KHR_bind_memory2 extensions, as they are promoted to Vulkan itself.
• Added support for query for memory budget and staying within the budget.
  • Added function vmaGetBudget, structure VmaBudget. This can also serve as simple statistics, more efficient than vmaCalculateStats.
  • By default the budget it is estimated based on memory heap sizes. It may be queried from the system using VK_EXT_memory_budget extension if you use VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT flag and VmaAllocatorCreateInfo::instance member.
  • Added flag VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT that fails an allocation if it would exceed the budget.
• Added new memory usage options:
  • VMA_MEMORY_USAGE_CPU_COPY for memory that is preferably not DEVICE_LOCAL but not guaranteed to be HOST_VISIBLE.
  • VMA_MEMORY_USAGE_GPU_LAZILY_ALLOCATED for memory that is LAZILY_ALLOCATED.
• Added support for VK_KHR_bind_memory2 extension:
  • Added VMA_ALLOCATION_CREATE_DONT_BIND_BIT flag that lets you create both buffer/image and allocation, but don't bind them together.
  • Added flag VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT, functions vmaBindBufferMemory2, vmaBindImageMemory2 that let you specify additional local offset and pNext pointer while binding.
• Added functions vmaSetPoolName, vmaGetPoolName that let you assign string names to custom pools. JSON dump file format and VmaDumpVis tool is updated to show these names.
• Defragmentation is legal only on buffers and images in VK_IMAGE_TILING_LINEAR. This is due to the way it is currently implemented in the library and the restrictions of the Vulkan specification. Clarified documentation in this regard. See discussion in #59.

Minor changes:

• Made vmaResizeAllocation function deprecated, always returning failure.
• Made changes in the internal algorithm for the choice of memory type. Be careful! You may now get a type that is not HOST_VISIBLE or HOST_COHERENT if it's not stated as always ensured by some VMA_MEMORY_USAGE_* flag.
• Extended VmaReplay application with more detailed statistics printed at the end.
• Added macros VMA_CALL_PRE, VMA_CALL_POST that let you decorate declarations of all library functions if you want to e.g. export/import them as dynamically linked library.
• Optimized VmaAllocation objects to be allocated out of an internal free-list allocator. This makes allocation and deallocation causing 0 dynamic CPU heap allocations on average.
• Updated recording CSV file format version to 1.8, to support new functions.
• Many additions and fixes in documentation. Many compatibility fixes for various compilers and platforms. Other internal bugfixes, optimizations, updates, refactoring...

2.2.0 (2018-12-13)

Major release after many months of development in "master" branch and feature branches. Notable new features: defragmentation of GPU memory, buddy algorithm, convenience functions for sparse binding.

Major changes:

• New, more powerful defragmentation:
  • Added structure VmaDefragmentationInfo2, functions vmaDefragmentationBegin, vmaDefragmentationEnd.
  • Added support for defragmentation of GPU memory.
  • Defragmentation of CPU memory now uses memmove, so it can move data to overlapping regions.
  • Defragmentation of CPU memory is now available for memory types that are HOST_VISIBLE but not HOST_COHERENT.
  • Added structure member VmaVulkanFunctions::vkCmdCopyBuffer.
  • Major internal changes in defragmentation algorithm.
  • VmaReplay: added parameters: --DefragmentAfterLine, --DefragmentationFlags.
  • Old interface (structure VmaDefragmentationInfo, function vmaDefragment) is now deprecated.
• Added buddy algorithm, available for custom pools - flag VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT.
• Added convenience functions for multiple allocations and deallocations at once, intended for sparse binding resources - functions vmaAllocateMemoryPages, vmaFreeMemoryPages.
• Added function that tries to resize existing allocation in place: vmaResizeAllocation.
• Added flags for allocation strategy: VMA_ALLOCATION_CREATE_STRATEGY_BEST_FIT_BIT, VMA_ALLOCATION_CREATE_STRATEGY_WORST_FIT_BIT, VMA_ALLOCATION_CREATE_STRATEGY_FIRST_FIT_BIT, and their aliases: VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT, VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT, VMA_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_BIT.

Minor changes:

• Changed behavior of allocation functions to return VK_ERROR_VALIDATION_FAILED_EXT when trying to allocate memory of size 0, create buffer with size 0, or image with one of the dimensions 0.
• VmaReplay: Added support for Windows end of lines.
• Updated recording CSV file format version to 1.5, to support new functions.
• Internal optimization: using read-write mutex on some platforms.
• Many additions and fixes in documentation. Many compatibility fixes for various compilers. Other internal bugfixes, optimizations, refactoring, added more internal validation...

2.1.0 (2018-09-10)

Minor bugfixes.

2.1.0-beta.1 (2018-08-27)

Major release after many months of development in "development" branch and features branches. Many new features added, some bugs fixed. API stays backward-compatible.

Major changes:

• Added linear allocation algorithm, accessible for custom pools, that can be used as free-at-once, stack, double stack, or ring buffer. See "Linear allocation algorithm" documentation chapter.
  • Added VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT, VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT.
• Added feature to record sequence of calls to the library to a file and replay it using dedicated application. See documentation chapter "Record and replay".
  • Recording: added VmaAllocatorCreateInfo::pRecordSettings.
  • Replaying: added VmaReplay project.
  • Recording file format: added document "docs/Recording file format.md".
• Improved support for non-coherent memory.
  • Added functions: vmaFlushAllocation, vmaInvalidateAllocation.
  • nonCoherentAtomSize is now respected automatically.
  • Added VmaVulkanFunctions::vkFlushMappedMemoryRanges, vkInvalidateMappedMemoryRanges.
• Improved debug features related to detecting incorrect mapped memory usage. See documentation chapter "Debugging incorrect memory usage".
  • Added debug macro VMA_DEBUG_DETECT_CORRUPTION, functions vmaCheckCorruption, vmaCheckPoolCorruption.
  • Added debug macro VMA_DEBUG_INITIALIZE_ALLOCATIONS to initialize contents of allocations with a bit pattern.
  • Changed behavior of VMA_DEBUG_MARGIN macro - it now adds margin also before first and after last allocation in a block.
• Changed format of JSON dump returned by vmaBuildStatsString (not backward compatible!).
  • Custom pools and memory blocks now have IDs that don't change after sorting.
  • Added properties: "CreationFrameIndex", "LastUseFrameIndex", "Usage".
  • Changed VmaDumpVis tool to use these new properties for better coloring.
  • Changed behavior of vmaGetAllocationInfo and vmaTouchAllocation to update allocation.lastUseFrameIndex even if allocation cannot become lost.

Minor changes:

• Changes in custom pools:
  • Added new structure member VmaPoolStats::blockCount.
  • Changed behavior of VmaPoolCreateInfo::blockSize = 0 (default) - it now means that pool may use variable block sizes, just like default pools do.
• Improved logic of vmaFindMemoryTypeIndex for some cases, especially integrated GPUs.
• VulkanSample application: Removed dependency on external library MathFu. Added own vector and matrix structures.
• Changes that improve compatibility with various platforms, including: Visual Studio 2012, 32-bit code, C compilers.
  • Changed usage of "VK_KHR_dedicated_allocation" extension in the code to be optional, driven by macro VMA_DEDICATED_ALLOCATION, for compatibility with Android.
• Many additions and fixes in documentation, including description of new features, as well as "Validation layer warnings".
• Other bugfixes.

2.0.0 (2018-03-19)

A major release with many compatibility-breaking changes.

Notable new features:

• Introduction of VmaAllocation handle that you must retrieve from allocation functions and pass to deallocation functions next to normal VkBuffer and VkImage.
• Introduction of VmaAllocationInfo structure that you can retrieve from VmaAllocation handle to access parameters of the allocation (like VkDeviceMemory and offset) instead of retrieving them directly from allocation functions.
• Support for reference-counted mapping and persistently mapped allocations - see vmaMapMemory, VMA_ALLOCATION_CREATE_MAPPED_BIT.
• Support for custom memory pools - see VmaPool handle, VmaPoolCreateInfo structure, vmaCreatePool function.
• Support for defragmentation (compaction) of allocations - see function vmaDefragment and related structures.
• Support for "lost allocations" - see appropriate chapter on documentation Main Page.

1.0.1 (2017-07-04)

• Fixes for Linux GCC compilation.
• Changed "CONFIGURATION SECTION" to contain #ifndef so you can define these macros before including this header, not necessarily change them in the file.

1.0.0 (2017-06-16)

First public release.