This release gathers fixes and improvements made during many months of continuous development on the main branch, mostly based on issues and pull requests on GitHub.
Additions to the library API:
vmaCopyMemoryToAllocation, vmaCopyAllocationToMemory.vmaCreateAliasingBuffer2, vmaCreateAliasingImage2 that offer creating a buffer/image in an existing allocation with additional allocationLocalOffset.vmaGetAllocationInfo2, structure VmaAllocationInfo2 that return additional information about an allocation, useful for interop with other APIs (#383, #340).VmaDefragmentationInfo::pfnBreakCallback that allows breaking long execution of vmaBeginDefragmentation. Also added PFN_vmaCheckDefragmentationBreakFunction, VmaDefragmentationInfo::pBreakCallbackUserData.VMA_ALLOCATOR_CREATE_KHR_MAINTENANCE4_BIT flag (#397).VMA_ALLOCATOR_CREATE_KHR_MAINTENANCE5_BIT flag (#411).Other changes:
VMA_DEBUG_LOG and VMA_DEBUG_LOG_FORMAT (#297).VMA_ASSERT_LEAK, VMA_LEAK_LOG_FORMAT separate from normal VMA_ASSERT, VMA_DEBUG_LOG_FORMAT (#379, #385).VMA_EXTENDS_VK_STRUCT (#347).#include that resulted in compilation error about snprintf not declared on some compilers (#312).HOST_CACHED memory type, like Raspberry Pi (#362).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):
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.VmaDefragmentationInfo, VmaDefragmentationMove, VmaDefragmentationPassMoveInfo, VmaDefragmentationStats, function vmaBeginDefragmentation, vmaEndDefragmentation, vmaBeginDefragmentationPass, vmaEndDefragmentationPass.VmaStatistics, VmaDetailedStatistics, VmaTotalStatistics. VmaBudget, functions: vmaGetHeapBudgets, vmaCalculateStatistics, vmaGetPoolStatistics, vmaCalculatePoolStatistics, vmaGetVirtualBlockStatistics, vmaCalculateVirtualBlockStatistics.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.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):
VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT, VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT, vmaCreateLostAllocation, vmaMakePoolAllocationsLost, vmaTouchAllocation, VmaAllocatorCreateInfo::frameInUseCount, VmaPoolCreateInfo::frameInUseCount.VmaAllocatorCreateInfo::pRecordSettings, VmaRecordSettings, VmaRecordFlagBits, VmaRecordFlags. Removed VmaReplay application.VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT.Minor but compatibility-breaking changes:
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.void* pUserData to VmaDeviceMemoryCallbacks. Updated PFN_vmaAllocateDeviceMemoryFunction, PFN_vmaFreeDeviceMemoryFunction to use the new pUserData member.vmaResizeAllocation that was already deprecated.Other major changes:
VmaPoolCreateInfo::pMemoryAllocateNext, minAllocationAlignment.VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT.VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT, members VmaAllocationCreateInfo::priority, VmaPoolCreateInfo::priority.VMA_ALLOCATOR_CREATE_AMD_DEVICE_COHERENT_MEMORY_BIT.VmaAllocatorCreateInfo::pTypeExternalMemoryHandleTypes.vmaGetAllocatorInfo, structure VmaAllocatorInfo.vmaFlushAllocations, vmaInvalidateAllocations for multiple allocations at once.VMA_ALLOCATION_CREATE_CAN_ALIAS_BIT.vmaCreateBufferWithAlignment.vmaGetAllocationMemoryProperties.vmaCreateAliasingBuffer, vmaCreateAliasingImage.Other minor changes:
bufferImageGranularity is large.VMA_DEBUG_ALIGNMENT to VMA_MIN_ALIGNMENT.vmaInvalidateAllocation and vmaFlushAllocation to return VkResult.VMA_NULLABLE, VMA_NOT_NULL, VMA_NULLABLE_NON_DISPATCHABLE, VMA_NOT_NULL_NON_DISPATCHABLE, VMA_LEN_IF_NOT_NULL.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:
VmaAllocatorCreateInfo::vulkanApiVersion.vmaGetBudget, structure VmaBudget. This can also serve as simple statistics, more efficient than vmaCalculateStats.VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT flag and VmaAllocatorCreateInfo::instance member.VMA_ALLOCATION_CREATE_WITHIN_BUDGET_BIT that fails an allocation if it would exceed the budget.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.VMA_ALLOCATION_CREATE_DONT_BIND_BIT flag that lets you create both buffer/image and allocation, but don't bind them together.VMA_ALLOCATOR_CREATE_KHR_BIND_MEMORY2_BIT, functions vmaBindBufferMemory2, vmaBindImageMemory2 that let you specify additional local offset and pNext pointer while binding.vmaSetPoolName, vmaGetPoolName that let you assign string names to custom pools. JSON dump file format and VmaDumpVis tool is updated to show these names.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:
vmaResizeAllocation function deprecated, always returning failure.HOST_VISIBLE or HOST_COHERENT if it's not stated as always ensured by some VMA_MEMORY_USAGE_* flag.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.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.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:
VmaDefragmentationInfo2, functions vmaDefragmentationBegin, vmaDefragmentationEnd.memmove, so it can move data to overlapping regions.HOST_VISIBLE but not HOST_COHERENT.VmaVulkanFunctions::vkCmdCopyBuffer.--DefragmentAfterLine, --DefragmentationFlags.VmaDefragmentationInfo, function vmaDefragment) is now deprecated.VMA_POOL_CREATE_BUDDY_ALGORITHM_BIT.vmaAllocateMemoryPages, vmaFreeMemoryPages.vmaResizeAllocation.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:
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.Minor bugfixes.
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:
VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT, VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT.VmaAllocatorCreateInfo::pRecordSettings.vmaFlushAllocation, vmaInvalidateAllocation.nonCoherentAtomSize is now respected automatically.VmaVulkanFunctions::vkFlushMappedMemoryRanges, vkInvalidateMappedMemoryRanges.VMA_DEBUG_DETECT_CORRUPTION, functions vmaCheckCorruption, vmaCheckPoolCorruption.VMA_DEBUG_INITIALIZE_ALLOCATIONS to initialize contents of allocations with a bit pattern.VMA_DEBUG_MARGIN macro - it now adds margin also before first and after last allocation in a block.vmaBuildStatsString (not backward compatible!).vmaGetAllocationInfo and vmaTouchAllocation to update allocation.lastUseFrameIndex even if allocation cannot become lost.Minor changes:
VmaPoolStats::blockCount.VmaPoolCreateInfo::blockSize = 0 (default) - it now means that pool may use variable block sizes, just like default pools do.vmaFindMemoryTypeIndex for some cases, especially integrated GPUs.VMA_DEDICATED_ALLOCATION, for compatibility with Android.A major release with many compatibility-breaking changes.
Notable new features:
VmaAllocation handle that you must retrieve from allocation functions and pass to deallocation functions next to normal VkBuffer and VkImage.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.vmaMapMemory, VMA_ALLOCATION_CREATE_MAPPED_BIT.VmaPool handle, VmaPoolCreateInfo structure, vmaCreatePool function.vmaDefragment and related structures.First public release.