Change in the defragmentation API. Compatibility breaking!

Removed VmaDefragmentationMove::dstMemory, dstOffset, internalData, added dstTmpAllocation.
Code by @medranSolus

Author: adam-sawicki-a

docs/html/defragmentation.html

@@ -101,7 +101,7 @@
 <div class="line">        VkImage newImg;</div>
 <div class="line">        res = vkCreateImage(device, &amp;imgCreateInfo, <span class="keyword">nullptr</span>, &amp;newImg);</div>
 <div class="line">        <span class="comment">// Check res...</span></div>
-<div class="line">        res = vKBindImageMemory(device, newImg, pass.<a class="code hl_variable" href="struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725">pMoves</a>[i].<a class="code hl_variable" href="struct_vma_defragmentation_move.html#a382fbec8dac2747abdc1883b69ef9458">dstMemory</a>, pass.<a class="code hl_variable" href="struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725">pMoves</a>[i].<a class="code hl_variable" href="struct_vma_defragmentation_move.html#a80c466b445bc272f82c7dbf1a971ba18">dstOffset</a>);</div>
+<div class="line">        res = <a class="code hl_function" href="group__group__alloc.html#ga3d3ca45799923aa5d138e9e5f9eb2da5">vmaBindImageMemory</a>(allocator, pMoves[i].dstTmpAllocation, newImg);</div>
 <div class="line">        <span class="comment">// Check res...</span></div>
 <div class="line"> </div>
 <div class="line">        <span class="comment">// Issue a vkCmdCopyBuffer/vkCmdCopyImage to copy its content to the new place.</span></div>
@@ -128,6 +128,7 @@
 <div class="line">}</div>
 <div class="line"> </div>
 <div class="line"><a class="code hl_function" href="group__group__alloc.html#ga59f01ca3d53d50b7cca9b442b77a3e87">vmaEndDefragmentation</a>(allocator, defragCtx, <span class="keyword">nullptr</span>);</div>
+<div class="ttc" id="agroup__group__alloc_html_ga3d3ca45799923aa5d138e9e5f9eb2da5"><div class="ttname"><a href="group__group__alloc.html#ga3d3ca45799923aa5d138e9e5f9eb2da5">vmaBindImageMemory</a></div><div class="ttdeci">VkResult vmaBindImageMemory(VmaAllocator allocator, VmaAllocation allocation, VkImage image)</div><div class="ttdoc">Binds image to allocation.</div></div>
 <div class="ttc" id="agroup__group__alloc_html_ga59f01ca3d53d50b7cca9b442b77a3e87"><div class="ttname"><a href="group__group__alloc.html#ga59f01ca3d53d50b7cca9b442b77a3e87">vmaEndDefragmentation</a></div><div class="ttdeci">void vmaEndDefragmentation(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationStats *pStats)</div><div class="ttdoc">Ends defragmentation process.</div></div>
 <div class="ttc" id="agroup__group__alloc_html_ga86dd08aba8633bfa4ad0df2e76481d8b"><div class="ttname"><a href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a></div><div class="ttdeci">void vmaGetAllocationInfo(VmaAllocator allocator, VmaAllocation allocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Returns current information about specified allocation.</div></div>
 <div class="ttc" id="agroup__group__alloc_html_ga980d7da2ce3b1fd5c8b8476bc362cc00"><div class="ttname"><a href="group__group__alloc.html#ga980d7da2ce3b1fd5c8b8476bc362cc00">vmaBeginDefragmentationPass</a></div><div class="ttdeci">VkResult vmaBeginDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)</div><div class="ttdoc">Starts single defragmentation pass.</div></div>
@@ -140,33 +141,30 @@
 <div class="ttc" id="astruct_vma_defragmentation_info_html"><div class="ttname"><a href="struct_vma_defragmentation_info.html">VmaDefragmentationInfo</a></div><div class="ttdoc">Parameters for defragmentation.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1401</div></div>
 <div class="ttc" id="astruct_vma_defragmentation_info_html_a18dd2097d8ab2976cdc7dd3e7b978bd4"><div class="ttname"><a href="struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4">VmaDefragmentationInfo::pool</a></div><div class="ttdeci">VmaPool pool</div><div class="ttdoc">Custom pool to be defragmented.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1408</div></div>
 <div class="ttc" id="astruct_vma_defragmentation_info_html_a3e23080c978ecf3abb3180f5b2069da7"><div class="ttname"><a href="struct_vma_defragmentation_info.html#a3e23080c978ecf3abb3180f5b2069da7">VmaDefragmentationInfo::flags</a></div><div class="ttdeci">VmaDefragmentationFlags flags</div><div class="ttdoc">Use combination of VmaDefragmentationFlagBits.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1403</div></div>
-<div class="ttc" id="astruct_vma_defragmentation_move_html_a382fbec8dac2747abdc1883b69ef9458"><div class="ttname"><a href="struct_vma_defragmentation_move.html#a382fbec8dac2747abdc1883b69ef9458">VmaDefragmentationMove::dstMemory</a></div><div class="ttdeci">VkDeviceMemory dstMemory</div><div class="ttdoc">Destination memory block where the allocation should be moved.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1429</div></div>
-<div class="ttc" id="astruct_vma_defragmentation_move_html_a80c466b445bc272f82c7dbf1a971ba18"><div class="ttname"><a href="struct_vma_defragmentation_move.html#a80c466b445bc272f82c7dbf1a971ba18">VmaDefragmentationMove::dstOffset</a></div><div class="ttdeci">VkDeviceSize dstOffset</div><div class="ttdoc">Destination offset where the allocation should be moved.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1431</div></div>
-<div class="ttc" id="astruct_vma_defragmentation_pass_move_info_html"><div class="ttname"><a href="struct_vma_defragmentation_pass_move_info.html">VmaDefragmentationPassMoveInfo</a></div><div class="ttdoc">Parameters for incremental defragmentation steps.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1441</div></div>
-<div class="ttc" id="astruct_vma_defragmentation_pass_move_info_html_a1b3e18c23f9691f35baf183e615c4408"><div class="ttname"><a href="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">VmaDefragmentationPassMoveInfo::moveCount</a></div><div class="ttdeci">uint32_t moveCount</div><div class="ttdoc">Number of elements in the pMoves array.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1443</div></div>
-<div class="ttc" id="astruct_vma_defragmentation_pass_move_info_html_adfa7a4994afd9b940e7f1dfaf436a725"><div class="ttname"><a href="struct_vma_defragmentation_pass_move_info.html#adfa7a4994afd9b940e7f1dfaf436a725">VmaDefragmentationPassMoveInfo::pMoves</a></div><div class="ttdeci">VmaDefragmentationMove * pMoves</div><div class="ttdoc">Array of moves to be performed by the user in the current defragmentation pass.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1467</div></div>
+<div class="ttc" id="astruct_vma_defragmentation_pass_move_info_html"><div class="ttname"><a href="struct_vma_defragmentation_pass_move_info.html">VmaDefragmentationPassMoveInfo</a></div><div class="ttdoc">Parameters for incremental defragmentation steps.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1442</div></div>
+<div class="ttc" id="astruct_vma_defragmentation_pass_move_info_html_a1b3e18c23f9691f35baf183e615c4408"><div class="ttname"><a href="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">VmaDefragmentationPassMoveInfo::moveCount</a></div><div class="ttdeci">uint32_t moveCount</div><div class="ttdoc">Number of elements in the pMoves array.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1444</div></div>
 </div><!-- fragment --><p >Although functions like <a class="el" href="group__group__alloc.html#gac72ee55598617e8eecca384e746bab51" title="Creates a new VkBuffer, allocates and binds memory for it.">vmaCreateBuffer()</a>, <a class="el" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer().">vmaCreateImage()</a>, <a class="el" href="group__group__alloc.html#ga0d9f4e4ba5bf9aab1f1c746387753d77" title="Destroys Vulkan buffer and frees allocated memory.">vmaDestroyBuffer()</a>, <a class="el" href="group__group__alloc.html#gae50d2cb3b4a3bfd4dd40987234e50e7e" title="Destroys Vulkan image and frees allocated memory.">vmaDestroyImage()</a> create/destroy an allocation and a buffer/image at once, these are just a shortcut for creating the resource, allocating memory, and binding them together. Defragmentation works on memory allocations only. You must handle the rest manually. Defragmentation is an iterative process that should repreat "passes" as long as related functions return <code>VK_INCOMPLETE</code> not <code>VK_SUCCESS</code>. In each pass:</p>
 <ol type="1">
 <li><a class="el" href="group__group__alloc.html#ga980d7da2ce3b1fd5c8b8476bc362cc00" title="Starts single defragmentation pass.">vmaBeginDefragmentationPass()</a> function call:<ul>
 <li>Calculates and returns the list of allocations to be moved in this pass. Note this can be a time-consuming process.</li>
-<li>Reserves destination memory for them by creating internal allocations. Returns their <code>VkDeviceMemory</code> + offset.</li>
+<li>Reserves destination memory for them by creating temporary destination allocations that you can query for their <code>VkDeviceMemory</code> + offset using <a class="el" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a>.</li>
 </ul>
 </li>
 <li>Inside the pass, <b>you should</b>:<ul>
 <li>Inspect the returned list of allocations to be moved.</li>
-<li>Create new buffers/images and bind them at the returned destination <code>VkDeviceMemory</code> + offset.</li>
+<li>Create new buffers/images and bind them at the returned destination temporary allocations.</li>
 <li>Copy data from source to destination resources if necessary.</li>
 <li>Destroy the source buffers/images, but NOT their allocations.</li>
 </ul>
 </li>
 <li><a class="el" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226" title="Ends single defragmentation pass.">vmaEndDefragmentationPass()</a> function call:<ul>
 <li>Frees the source memory reserved for the allocations that are moved.</li>
-<li>Modifies <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> objects that are moved to point to the destination reserved memory.</li>
+<li>Modifies source <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> objects that are moved to point to the destination reserved memory.</li>
 <li>Frees <code>VkDeviceMemory</code> blocks that became empty.</li>
 </ul>
 </li>
 </ol>
-<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 <a class="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 >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 <a class="el" href="group__group__alloc.html#ggada9e3861caf96f08894b0bcc160ec257ad25bc6f816b226b4fd5170e845f218d2" title="Set this value if you cannot move the allocation. New place reserved at dstTmpAllocation will be free...">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 >Inside a pass, for each allocation that should be moved:</p>
 <ul>
 <li>You should copy its data from the source to the destination place by calling e.g. <code>vkCmdCopyBuffer()</code>, <code>vkCmdCopyImage()</code>.<ul>
@@ -175,12 +173,12 @@
 </li>
 <li>If a resource doesn't contain any meaningful data, e.g. it is a transient color attachment image to be cleared, filled, and used temporarily in each rendering frame, you can just recreate this image without copying its data.</li>
 <li>If the resource is in <code>HOST_VISIBLE</code> and <code>HOST_COHERENT</code> memory, you can copy its data on the CPU using <code>memcpy()</code>.</li>
-<li>If you cannot move the allocation, you can set <code>pass.pMoves[i].operation</code> to <a class="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 will cancel the move.<ul>
+<li>If you cannot move the allocation, you can set <code>pass.pMoves[i].operation</code> to <a class="el" href="group__group__alloc.html#ggada9e3861caf96f08894b0bcc160ec257ad25bc6f816b226b4fd5170e845f218d2" title="Set this value if you cannot move the allocation. New place reserved at dstTmpAllocation will be free...">VMA_DEFRAGMENTATION_MOVE_OPERATION_IGNORE</a>. This will cancel the move.<ul>
 <li><a class="el" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226" title="Ends single defragmentation pass.">vmaEndDefragmentationPass()</a> will then free the destination memory not the source memory of the allocation, leaving it unchanged.</li>
 </ul>
 </li>
 <li>If you decide the allocation is unimportant and can be destroyed instead of moved (e.g. it wasn't used for long time), you can set <code>pass.pMoves[i].operation</code> to <a class="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>.<ul>
-<li><a class="el" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226" title="Ends single defragmentation pass.">vmaEndDefragmentationPass()</a> will then free both source and destination memory, and will destroy the <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object.</li>
+<li><a class="el" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226" title="Ends single defragmentation pass.">vmaEndDefragmentationPass()</a> will then free both source and destination memory, and will destroy the source <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object.</li>
 </ul>
 </li>
 </ul>

docs/html/functions.html

@@ -88,8 +88,7 @@ <h3><a id="index_d" name="index_d"></a>- d -</h3><ul>
 <li>device&#160;:&#160;<a class="el" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">VmaAllocatorCreateInfo</a>, <a class="el" href="struct_vma_allocator_info.html#a012b4c485bf3b0ea8921352c5ee0c357">VmaAllocatorInfo</a></li>
 <li>deviceMemory&#160;:&#160;<a class="el" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">VmaAllocationInfo</a></li>
 <li>deviceMemoryBlocksFreed&#160;:&#160;<a class="el" href="struct_vma_defragmentation_stats.html#a0113f1877904a5d1ee8f409216ff276b">VmaDefragmentationStats</a></li>
-<li>dstMemory&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a382fbec8dac2747abdc1883b69ef9458">VmaDefragmentationMove</a></li>
-<li>dstOffset&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a80c466b445bc272f82c7dbf1a971ba18">VmaDefragmentationMove</a></li>
+<li>dstTmpAllocation&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#ab65b106adf209acd7313296d1075300e">VmaDefragmentationMove</a></li>
 </ul>
 
 
@@ -100,7 +99,6 @@ <h3><a id="index_f" name="index_f"></a>- f -</h3><ul>
 
 <h3><a id="index_i" name="index_i"></a>- i -</h3><ul>
 <li>instance&#160;:&#160;<a class="el" href="struct_vma_allocator_create_info.html#a70dd42e29b1df1d1b9b61532ae0b370b">VmaAllocatorCreateInfo</a>, <a class="el" href="struct_vma_allocator_info.html#a2ed6a4d2d3fea039d66a13f15d0ce5fe">VmaAllocatorInfo</a></li>
-<li>internalData&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a4f3637400767f3e642b3936e18b00e0f">VmaDefragmentationMove</a></li>
 </ul>
 
 

docs/html/functions_vars.html

@@ -88,8 +88,7 @@ <h3><a id="index_d" name="index_d"></a>- d -</h3><ul>
 <li>device&#160;:&#160;<a class="el" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">VmaAllocatorCreateInfo</a>, <a class="el" href="struct_vma_allocator_info.html#a012b4c485bf3b0ea8921352c5ee0c357">VmaAllocatorInfo</a></li>
 <li>deviceMemory&#160;:&#160;<a class="el" href="struct_vma_allocation_info.html#ae0bfb7dfdf79a76ffefc9a94677a2f67">VmaAllocationInfo</a></li>
 <li>deviceMemoryBlocksFreed&#160;:&#160;<a class="el" href="struct_vma_defragmentation_stats.html#a0113f1877904a5d1ee8f409216ff276b">VmaDefragmentationStats</a></li>
-<li>dstMemory&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a382fbec8dac2747abdc1883b69ef9458">VmaDefragmentationMove</a></li>
-<li>dstOffset&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a80c466b445bc272f82c7dbf1a971ba18">VmaDefragmentationMove</a></li>
+<li>dstTmpAllocation&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#ab65b106adf209acd7313296d1075300e">VmaDefragmentationMove</a></li>
 </ul>
 
 
@@ -100,7 +99,6 @@ <h3><a id="index_f" name="index_f"></a>- f -</h3><ul>
 
 <h3><a id="index_i" name="index_i"></a>- i -</h3><ul>
 <li>instance&#160;:&#160;<a class="el" href="struct_vma_allocator_create_info.html#a70dd42e29b1df1d1b9b61532ae0b370b">VmaAllocatorCreateInfo</a>, <a class="el" href="struct_vma_allocator_info.html#a2ed6a4d2d3fea039d66a13f15d0ce5fe">VmaAllocatorInfo</a></li>
-<li>internalData&#160;:&#160;<a class="el" href="struct_vma_defragmentation_move.html#a4f3637400767f3e642b3936e18b00e0f">VmaDefragmentationMove</a></li>
 </ul>