<divclass="textblock"><p>Interleaved allocations and deallocations of many objects of varying size can cause fragmentation, which can lead to a situation where the library is unable to find a continuous range of free memory for a new allocation despite there is enough free space, just scattered across many small free ranges between existing allocations.</p>
<p>To mitigate this problem, you can use <aclass="el"href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb"title="Deprecated. Compacts memory by moving allocations. ">vmaDefragment()</a>. Given set of allocations, this function can move them to compact used memory, ensure more continuous free space and possibly also free some <code>VkDeviceMemory</code>. Currently it can work only on allocations made from memory type that is <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code>. Allocations are modified to point to the new <code>VkDeviceMemory</code> and offset. Data in this memory is also <code>memmove</code>-ed to the new place. However, if you have images or buffers bound to these allocations (and you certainly do), you need to destroy, recreate, and bind them to the new place in memory.</p>
<p>After allocation has been moved, its <aclass="el"href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67"title="Handle to Vulkan memory object. ">VmaAllocationInfo::deviceMemory</a> and/or <aclass="el"href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268"title="Offset into deviceMemory object to the beginning of this allocation, in bytes. (deviceMemory, offset) pair is unique to this allocation. ">VmaAllocationInfo::offset</a> changes. You must query them again using <aclass="el"href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b"title="Returns current information about specified allocation and atomically marks it as used in current fra...">vmaGetAllocationInfo()</a> if you need them.</p>
<p>If an allocation has been moved, data in memory is copied to new place automatically, but if it was bound to a buffer or an image, you must destroy that object yourself, create new one and bind it to the new memory pointed by the allocation. You must use <code>vkDestroyBuffer()</code>, <code>vkDestroyImage()</code>, <code>vkCreateBuffer()</code>, <code>vkCreateImage()</code> for that purpose and NOT <aclass="el"href="vk__mem__alloc_8h.html#a0d9f4e4ba5bf9aab1f1c746387753d77"title="Destroys Vulkan buffer and frees allocated memory. ">vmaDestroyBuffer()</a>, <aclass="el"href="vk__mem__alloc_8h.html#ae50d2cb3b4a3bfd4dd40987234e50e7e"title="Destroys Vulkan image and frees allocated memory. ">vmaDestroyImage()</a>, <aclass="el"href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a>, <aclass="el"href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73"title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>! Example:</p>
<divclass="fragment"><divclass="line">VkDevice device = ...;</div><divclass="line"><aclass="code"href="struct_vma_allocator.html">VmaAllocator</a> allocator = ...;</div><divclass="line">std::vector<VkBuffer> buffers = ...;</div><divclass="line">std::vector<VmaAllocation> allocations = ...;</div><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">size_t</span> allocCount = allocations.size();</div><divclass="line"></div><divclass="line">std::vector<VkBool32> allocationsChanged(allocCount);</div><divclass="line"><aclass="code"href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb">vmaDefragment</a>(allocator, allocations.data(), allocCount, allocationsChanged.data(), <spanclass="keyword">nullptr</span>, <spanclass="keyword">nullptr</span>);</div><divclass="line"></div><divclass="line"><spanclass="keywordflow">for</span>(<spanclass="keywordtype">size_t</span> i = 0; i < allocCount; ++i)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span>(allocationsChanged[i])</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// Destroy buffers that is immutably bound to memory region which is no longer valid.</span></div><divclass="line"> vkDestroyBuffer(device, buffers[i], <spanclass="keyword">nullptr</span>);</div><divclass="line"></div><divclass="line"><spanclass="comment">// Create new buffer with same parameters.</span></div><divclass="line"> VkBufferCreateInfo bufferInfo = ...;</div><divclass="line"> vkCreateBuffer(device, &bufferInfo, <spanclass="keyword">nullptr</span>, &buffers[i]);</div><divclass="line"></div><divclass="line"><spanclass="comment">// You can make dummy call to vkGetBufferMemoryRequirements here to silence validation layer warning.</span></div><divclass="line"></div><divclass="line"><spanclass="comment">// Bind new buffer with new memory region. Data contained in it is already there.</span></div><divclass="line"><aclass="code"href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div><divclass="line"><aclass="code"href="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, allocations[i], &allocInfo);</div><divclass="line"> vkBindBufferMemory(device, buffers[i], allocInfo.<aclass="code"href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">deviceMemory</a>, allocInfo.<aclass="code"href="struct_vma_allocation_info.html#a4a3c732388dbdc7a23f9365b00825268">offset</a>);</div><divclass="line"> }</div><divclass="line">}</div></div><!-- fragment --><p>Please don't expect memory to be fully compacted after defragmentation. Algorithms inside are based on some heuristics that try to maximize number of Vulkan memory blocks to make totally empty to release them, as well as to maximimze continuous empty space inside remaining blocks, while minimizing the number and size of allocations that needs to be moved. Some fragmentation still remains after this call. This is normal.</p>
<p>If you defragment allocations bound to images, these images should be created with <code>VK_IMAGE_CREATE_ALIAS_BIT</code> flag, to make sure that new image created with same parameters and pointing to data copied to another memory region will interpret its contents consistently. Otherwise you may experience corrupted data on some implementations, e.g. due to different pixel swizzling used internally by the graphics driver.</p>
<p>If you defragment allocations bound to images, new images to be bound to new memory region after defragmentation should be created with <code>VK_IMAGE_LAYOUT_PREINITIALIZED</code> and then transitioned to their original layout from before defragmentation using an image memory barrier.</p>
<p>For further details, see documentation of function <aclass="el"href="vk__mem__alloc_8h.html#a6aced90fcc7b39882b6654a740a0b9bb"title="Deprecated. Compacts memory by moving allocations. ">vmaDefragment()</a>. </p>
