<divclass="textblock"><p>Interleaved allocations and deallocations of many objects of varying size can cause fragmentation over time, 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 defragmentation feature. It doesn't happen automatically though and needs your cooperation, because VMA is a low level library that only allocates memory. It cannot recreate buffers and images in a new place as it doesn't remember the contents of <code>VkBufferCreateInfo</code> / <code>VkImageCreateInfo</code> structures. It cannot copy their contents as it doesn't record any commands to a command buffer.</p>
<divclass="line"><spanclass="keywordflow">for</span>(uint32_t i = 0; i < pass.<aclass="code hl_variable"href="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">moveCount</a>; ++i)</div>
<divclass="line"> {</div>
<divclass="line"><spanclass="comment">//- Inspect pass.pMoves[i].srcAllocation, identify what buffer or image it represents.</span></div>
<divclass="line"><spanclass="comment">//- Recreate this buffer or image at pass.pMoves[i].dstMemory, pass.pMoves[i].dstOffset.</span></div>
<divclass="line"><spanclass="comment">//- Issue a vkCmdCopyBuffer/vkCmdCopyImage to copy its content to the new place.</span></div>
<divclass="line"> }</div>
<divclass="line"><spanclass="comment">//- Make sure the copy commands finished executing.</span></div>
<divclass="line"><spanclass="comment">//- Update appropriate descriptors to point to the new places.</span></div>
<divclass="ttc"id="astruct_vma_defragmentation_context_html"><divclass="ttname"><ahref="struct_vma_defragmentation_context.html">VmaDefragmentationContext</a></div><divclass="ttdoc">An opaque object that represents started defragmentation process.</div></div>
<divclass="ttc"id="astruct_vma_defragmentation_info_html"><divclass="ttname"><ahref="struct_vma_defragmentation_info.html">VmaDefragmentationInfo</a></div><divclass="ttdoc">Parameters for defragmentation.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1382</div></div>
<divclass="ttc"id="astruct_vma_defragmentation_info_html_a18dd2097d8ab2976cdc7dd3e7b978bd4"><divclass="ttname"><ahref="struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4">VmaDefragmentationInfo::pool</a></div><divclass="ttdeci">VmaPool pool</div><divclass="ttdoc">Custom pool to be defragmented.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1389</div></div>
<divclass="ttc"id="astruct_vma_defragmentation_info_html_a3e23080c978ecf3abb3180f5b2069da7"><divclass="ttname"><ahref="struct_vma_defragmentation_info.html#a3e23080c978ecf3abb3180f5b2069da7">VmaDefragmentationInfo::flags</a></div><divclass="ttdeci">VmaDefragmentationFlags flags</div><divclass="ttdoc">Use combination of VmaDefragmentationFlagBits.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1384</div></div>
<divclass="ttc"id="astruct_vma_defragmentation_pass_move_info_html"><divclass="ttname"><ahref="struct_vma_defragmentation_pass_move_info.html">VmaDefragmentationPassMoveInfo</a></div><divclass="ttdoc">Parameters for incremental defragmentation steps.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1422</div></div>
<divclass="ttc"id="astruct_vma_defragmentation_pass_move_info_html_a1b3e18c23f9691f35baf183e615c4408"><divclass="ttname"><ahref="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">VmaDefragmentationPassMoveInfo::moveCount</a></div><divclass="ttdeci">uint32_t moveCount</div><divclass="ttdoc">Number of elements in the pMoves array.</div><divclass="ttdef"><b>Definition:</b> vk_mem_alloc.h:1424</div></div>
</div><!-- fragment --><p>You can defragment a specific custom pool by setting <aclass="el"href="struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4"title="Custom pool to be defragmented.">VmaDefragmentationInfo::pool</a> (like in the example above) or all the default pools by setting this member to null.</p>
<p>Unlike in previous iterations of the defragmentation API, there is no list of "movable" allocations passed as a parameter. Defragmentation algorithm tries to move all suitable allocations. You can, however, refuse to move some of them inside a defragmentation pass, by setting <code>pass.pMoves[i].operation</code> to <aclass="el"href="group__group__alloc.html#ggada9e3861caf96f08894b0bcc160ec257ad25bc6f816b226b4fd5170e845f218d2"title="Set this value if you cannot move the allocation. New place reserved dstMemory + dstOffset will be fr...">VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE</a>. This is not recommended and may result in suboptimal packing of the allocations after defragmentation. If you cannot ensure any allocation can be moved, it is better to keep movable allocations separate in a custom pool.</p>
<p>You can also decide to destroy an allocation instead of moving it. You should then set <code>pass.pMoves[i].operation</code> to <aclass="el"href="group__group__alloc.html#ggada9e3861caf96f08894b0bcc160ec257a9786f8492a9be2c03bd26395e352ab85"title="Set this value if you decide to abandon the allocation and you destroyed the buffer/image....">VMA_DEFRAGMENTATION_MOVE_OPERATION_DESTROY</a>.</p>
<p>You can perform the defragmentation incrementally to limit the number of allocations and bytes to be moved in each pass, e.g. to call it in sync with render frames and not to experience too big hitches. See members: <aclass="el"href="struct_vma_defragmentation_info.html#a637ada77b02179a27fa92290000afac4"title="Maximum numbers of bytes that can be copied during single pass, while moving allocations to different...">VmaDefragmentationInfo::maxBytesPerPass</a>, <aclass="el"href="struct_vma_defragmentation_info.html#ac2db29d309bebc4f7d55041416e9694b"title="Maximum number of allocations that can be moved during single pass to a different place.">VmaDefragmentationInfo::maxAllocationsPerPass</a>.</p>
<p>It is also safe to perform the defragmentation asynchronously to render frames and other Vulkan and VMA usage, possibly from multiple threads, with the exception that allocations returned in <aclass="el"href="struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725"title="Array of moves to be performed by the user in the current defragmentation pass.">VmaDefragmentationPassMoveInfo::pMoves</a> shouldn't be destroyed until the defragmentation pass is ended.</p>
<dlclass="section note"><dt>Note</dt><dd>Defragmentation is not supported in custom pools created with <aclass="el"href="group__group__alloc.html#gga9a7c45f9c863695d98c83fa5ac940fe7a13c8a444197c67866be9cb05599fc726"title="Enables alternative, linear allocation algorithm in this pool.">VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT</a>. </dd></dl>
