Rewritten documentation chapter about defragmentation.

Author: adam-sawicki-a

README.md

@@ -45,7 +45,7 @@ Additional features:
 - Custom memory pools: Create a pool with desired parameters (e.g. fixed or limited maximum size) and allocate memory out of it.
 - Linear allocator: Create a pool with linear algorithm and use it for much faster allocations and deallocations in free-at-once, stack, double stack, or ring buffer fashion.
 - Support for VK_KHR_dedicated_allocation extension: Just enable it and it will be used automatically by the library.
-- Defragmentation: Call one function and let the library move data around to free some memory blocks and make your allocations better compacted.
+- Defragmentation of GPU and CPU memory: Let the library move data around to free some memory blocks and make your allocations better compacted.
 - Lost allocations: Allocate memory with appropriate flags and let the library remove allocations that are not used for many frames to make room for new ones.
 - Statistics: Obtain detailed statistics about the amount of memory used, unused, number of allocated blocks, number of allocations etc. - globally, per memory heap, and per memory type.
 - Debug annotations: Associate string with name or opaque pointer to your own data with every allocation.

docs/html/defragmentation.html

@@ -65,7 +65,7 @@
 
 <h3><a id="index_a"></a>- a -</h3><ul>
 <li>allocationCount
-: <a class="el" href="struct_vma_defragmentation_info2.html#ae41a36871f23fdd34df9c72149204c57">VmaDefragmentationInfo2</a>
+: <a class="el" href="struct_vma_defragmentation_info2.html#a3cf86ab32c1da779b4923d301a3056ba">VmaDefragmentationInfo2</a>
 , <a class="el" href="struct_vma_pool_stats.html#ad1924eb54fffa45e9e0e65670c8fe5eb">VmaPoolStats</a>
 , <a class="el" href="struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff">VmaStatInfo</a>
 </li>
@@ -78,9 +78,6 @@ <h3><a id="index_a"></a>- a -</h3><ul>
 <li>allocationSizeMin
 : <a class="el" href="struct_vma_stat_info.html#ade8b40bd3139c04aabd2fc538a356fea">VmaStatInfo</a>
 </li>
-<li>allocationsLost
-: <a class="el" href="struct_vma_defragmentation_stats.html#a87f0adc9588757b1e3ac1815597ace03">VmaDefragmentationStats</a>
-</li>
 <li>allocationsMoved
 : <a class="el" href="struct_vma_defragmentation_stats.html#aefeabf130022008eadd75999478af3f9">VmaDefragmentationStats</a>
 </li>
@@ -104,6 +101,13 @@ <h3><a id="index_b"></a>- b -</h3><ul>
 </ul>
 
 
+<h3><a id="index_c"></a>- c -</h3><ul>
+<li>commandBuffer
+: <a class="el" href="struct_vma_defragmentation_info2.html#a7f71f39590c5316771493d2333f9c1bd">VmaDefragmentationInfo2</a>
+</li>
+</ul>
+
+
 <h3><a id="index_d"></a>- d -</h3><ul>
 <li>device
 : <a class="el" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">VmaAllocatorCreateInfo</a>
@@ -214,6 +218,12 @@ <h3><a id="index_p"></a>- p -</h3><ul>
 <li>pool
 : <a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">VmaAllocationCreateInfo</a>
 </li>
+<li>poolCount
+: <a class="el" href="struct_vma_defragmentation_info2.html#a7e70aa2a1081d849dcc7829b19d3ec9d">VmaDefragmentationInfo2</a>
+</li>
+<li>pPools
+: <a class="el" href="struct_vma_defragmentation_info2.html#a0b3effd57f3fcdeb2ed62210b4ef20e1">VmaDefragmentationInfo2</a>
+</li>
 <li>pRecordSettings
 : <a class="el" href="struct_vma_allocator_create_info.html#ace2aa4877b16a42b0b7673d4e26000ee">VmaAllocatorCreateInfo</a>
 </li>
@@ -295,6 +305,9 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 <li>vkBindImageMemory
 : <a class="el" href="struct_vma_vulkan_functions.html#a1338d96a128a5ade648b8d934907c637">VmaVulkanFunctions</a>
 </li>
+<li>vkCmdCopyBuffer
+: <a class="el" href="struct_vma_vulkan_functions.html#ae5c0db8c89a3b82593dc16aa6a49fa3a">VmaVulkanFunctions</a>
+</li>
 <li>vkCreateBuffer
 : <a class="el" href="struct_vma_vulkan_functions.html#ae8084315a25006271a2edfc3a447519f">VmaVulkanFunctions</a>
 </li>

docs/html/functions.html

@@ -65,7 +65,7 @@
 
 <h3><a id="index_a"></a>- a -</h3><ul>
 <li>allocationCount
-: <a class="el" href="struct_vma_defragmentation_info2.html#ae41a36871f23fdd34df9c72149204c57">VmaDefragmentationInfo2</a>
+: <a class="el" href="struct_vma_defragmentation_info2.html#a3cf86ab32c1da779b4923d301a3056ba">VmaDefragmentationInfo2</a>
 , <a class="el" href="struct_vma_pool_stats.html#ad1924eb54fffa45e9e0e65670c8fe5eb">VmaPoolStats</a>
 , <a class="el" href="struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff">VmaStatInfo</a>
 </li>
@@ -78,9 +78,6 @@ <h3><a id="index_a"></a>- a -</h3><ul>
 <li>allocationSizeMin
 : <a class="el" href="struct_vma_stat_info.html#ade8b40bd3139c04aabd2fc538a356fea">VmaStatInfo</a>
 </li>
-<li>allocationsLost
-: <a class="el" href="struct_vma_defragmentation_stats.html#a87f0adc9588757b1e3ac1815597ace03">VmaDefragmentationStats</a>
-</li>
 <li>allocationsMoved
 : <a class="el" href="struct_vma_defragmentation_stats.html#aefeabf130022008eadd75999478af3f9">VmaDefragmentationStats</a>
 </li>
@@ -104,6 +101,13 @@ <h3><a id="index_b"></a>- b -</h3><ul>
 </ul>
 
 
+<h3><a id="index_c"></a>- c -</h3><ul>
+<li>commandBuffer
+: <a class="el" href="struct_vma_defragmentation_info2.html#a7f71f39590c5316771493d2333f9c1bd">VmaDefragmentationInfo2</a>
+</li>
+</ul>
+
+
 <h3><a id="index_d"></a>- d -</h3><ul>
 <li>device
 : <a class="el" href="struct_vma_allocator_create_info.html#ad924ddd77b04039c88d0c09b0ffcd500">VmaAllocatorCreateInfo</a>
@@ -214,6 +218,12 @@ <h3><a id="index_p"></a>- p -</h3><ul>
 <li>pool
 : <a class="el" href="struct_vma_allocation_create_info.html#a6272c0555cfd1fe28bff1afeb6190150">VmaAllocationCreateInfo</a>
 </li>
+<li>poolCount
+: <a class="el" href="struct_vma_defragmentation_info2.html#a7e70aa2a1081d849dcc7829b19d3ec9d">VmaDefragmentationInfo2</a>
+</li>
+<li>pPools
+: <a class="el" href="struct_vma_defragmentation_info2.html#a0b3effd57f3fcdeb2ed62210b4ef20e1">VmaDefragmentationInfo2</a>
+</li>
 <li>pRecordSettings
 : <a class="el" href="struct_vma_allocator_create_info.html#ace2aa4877b16a42b0b7673d4e26000ee">VmaAllocatorCreateInfo</a>
 </li>
@@ -295,6 +305,9 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 <li>vkBindImageMemory
 : <a class="el" href="struct_vma_vulkan_functions.html#a1338d96a128a5ade648b8d934907c637">VmaVulkanFunctions</a>
 </li>
+<li>vkCmdCopyBuffer
+: <a class="el" href="struct_vma_vulkan_functions.html#ae5c0db8c89a3b82593dc16aa6a49fa3a">VmaVulkanFunctions</a>
+</li>
 <li>vkCreateBuffer
 : <a class="el" href="struct_vma_vulkan_functions.html#ae8084315a25006271a2edfc3a447519f">VmaVulkanFunctions</a>
 </li>

docs/html/functions_vars.html

@@ -91,6 +91,7 @@ <h1><a class="anchor" id="general_considerations_validation_layer_warnings"></a>
 </li>
 <li><em>Non-linear image 0xebc91 is aliased with linear buffer 0xeb8e4 which may indicate a bug.</em><ul>
 <li>It happens when you use lost allocations, and a new image or buffer is created in place of an existing object that bacame lost.</li>
+<li>It may happen also when you use <a class="el" href="defragmentation.html">defragmentation</a>.</li>
 </ul>
 </li>
 </ul>
@@ -111,7 +112,7 @@ <h1><a class="anchor" id="general_considerations_features_not_supported"></a>
 <p>Features deliberately excluded from the scope of this library:</p>
 <ul>
 <li>Support for sparse binding and sparse residency. You can still use these features (when supported by the device) with VMA. You just need to do it yourself. Allocate memory pages with <a class="el" href="vk__mem__alloc_8h.html#abf28077dbf82d0908b8acbe8ee8dd9b8" title="General purpose memory allocation. ">vmaAllocateMemory()</a>. Any explicit support for sparse binding/residency would rather require another, higher-level library on top of VMA.</li>
-<li>Data transfer - issuing commands that transfer data between buffers or images, any usage of <code>VkCommandList</code> or <code>VkQueue</code> and related synchronization is responsibility of the user.</li>
+<li>Data transfer - issuing commands that transfer data between buffers or images, any usage of <code>VkCommandBuffer</code> or <code>VkQueue</code> and related synchronization is responsibility of the user.</li>
 <li>Allocations for imported/exported external memory. They tend to require explicit memory type index and dedicated allocation anyway, so they don't interact with main features of this library. Such special purpose allocations should be made manually, using <code>vkCreateBuffer()</code> and <code>vkAllocateMemory()</code>.</li>
 <li>Recreation of buffers and images. Although the library has functions for buffer and image creation (<a class="el" href="vk__mem__alloc_8h.html#ac72ee55598617e8eecca384e746bab51">vmaCreateBuffer()</a>, <a class="el" href="vk__mem__alloc_8h.html#a02a94f25679275851a53e82eacbcfc73" title="Function similar to vmaCreateBuffer(). ">vmaCreateImage()</a>), you need to recreate these objects yourself after defragmentation. That's because the big structures <code>VkBufferCreateInfo</code>, <code>VkImageCreateInfo</code> are not stored in <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation. ">VmaAllocation</a> object.</li>
 <li>Handling CPU memory allocation failures. When dynamically creating small C++ objects in CPU memory (not Vulkan memory), allocation failures are not checked and handled gracefully, because that would complicate code significantly and is usually not needed in desktop PC applications anyway.</li>

docs/html/general_considerations.html

@@ -138,21 +138,9 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 <li>VMA_DEDICATED_ALLOCATION
 : <a class="el" href="vk__mem__alloc_8h.html#af7b860e63b96d11e44ae8587ba06bbf4">vk_mem_alloc.h</a>
 </li>
-<li>VMA_DEFRAGMENTATION_ALGORITHM_MASK
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cad5069876a2b8b45065b91e43ef906c1d">vk_mem_alloc.h</a>
-</li>
-<li>VMA_DEFRAGMENTATION_CAN_MAKE_LOST_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50ca4e406da317f64208d0b26eb82c8d8071">vk_mem_alloc.h</a>
-</li>
-<li>VMA_DEFRAGMENTATION_FAST_ALGORITHM_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50ca72611a502fd73f59c478475a3e18ca7f">vk_mem_alloc.h</a>
-</li>
 <li>VMA_DEFRAGMENTATION_FLAG_BITS_MAX_ENUM
 : <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cab87ec33154803bfeb5ac2b379f1d6a97">vk_mem_alloc.h</a>
 </li>
-<li>VMA_DEFRAGMENTATION_OPTIMAL_ALGORITHM_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cacf7eb65ad6d2423ebe2ca3f56bb77a46">vk_mem_alloc.h</a>
-</li>
 <li>VMA_MEMORY_USAGE_CPU_ONLY
 : <a class="el" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">vk_mem_alloc.h</a>
 </li>
@@ -271,7 +259,7 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 : <a class="el" href="vk__mem__alloc_8h.html#a8774e20e91e245aae959ba63efa15dd2">vk_mem_alloc.h</a>
 </li>
 <li>VmaDefragmentationFlagBits
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50c">vk_mem_alloc.h</a>
+: <a class="el" href="vk__mem__alloc_8h.html#a96df0eddab2e1735782fe4e7cd05ea7f">vk_mem_alloc.h</a>
 </li>
 <li>VmaDefragmentationFlags
 : <a class="el" href="vk__mem__alloc_8h.html#a88a77cef37e5d3c4fc9eb328885d048d">vk_mem_alloc.h</a>
@@ -358,7 +346,7 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 : <a class="el" href="vk__mem__alloc_8h.html#a2e5612d871d64c5624087b837a338c34">vk_mem_alloc.h</a>
 </li>
 <li>VmaRecordFlagBits
-: <a class="el" href="vk__mem__alloc_8h.html#ade20b626a6635ce1bf30ea53dea774e4">vk_mem_alloc.h</a>
+: <a class="el" href="vk__mem__alloc_8h.html#a4dd2c44642312a147a4e93373a6e64d2">vk_mem_alloc.h</a>
 </li>
 <li>VmaRecordFlags
 : <a class="el" href="vk__mem__alloc_8h.html#af3929a1a4547c592fc0b0e55ef452828">vk_mem_alloc.h</a>

docs/html/globals.html

@@ -118,21 +118,9 @@ <h3><a id="index_v"></a>- v -</h3><ul>
 <li>VMA_ALLOCATOR_CREATE_KHR_DEDICATED_ALLOCATION_BIT
 : <a class="el" href="vk__mem__alloc_8h.html#a4f87c9100d154a65a4ad495f7763cf7cace7da7cc6e71a625dfa763c55a597878">vk_mem_alloc.h</a>
 </li>
-<li>VMA_DEFRAGMENTATION_ALGORITHM_MASK
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cad5069876a2b8b45065b91e43ef906c1d">vk_mem_alloc.h</a>
-</li>
-<li>VMA_DEFRAGMENTATION_CAN_MAKE_LOST_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50ca4e406da317f64208d0b26eb82c8d8071">vk_mem_alloc.h</a>
-</li>
-<li>VMA_DEFRAGMENTATION_FAST_ALGORITHM_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50ca72611a502fd73f59c478475a3e18ca7f">vk_mem_alloc.h</a>
-</li>
 <li>VMA_DEFRAGMENTATION_FLAG_BITS_MAX_ENUM
 : <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cab87ec33154803bfeb5ac2b379f1d6a97">vk_mem_alloc.h</a>
 </li>
-<li>VMA_DEFRAGMENTATION_OPTIMAL_ALGORITHM_BIT
-: <a class="el" href="vk__mem__alloc_8h.html#a6552a65b71d16f378c6994b3ceaef50cacf7eb65ad6d2423ebe2ca3f56bb77a46">vk_mem_alloc.h</a>
-</li>
 <li>VMA_MEMORY_USAGE_CPU_ONLY
 : <a class="el" href="vk__mem__alloc_8h.html#aa5846affa1e9da3800e3e78fae2305cca40bdf4cddeffeb12f43d45ca1286e0a5">vk_mem_alloc.h</a>
 </li>

docs/html/globals_eval.html

@@ -105,7 +105,12 @@ <h1><a class="anchor" id="main_table_of_contents"></a>
 <li><a class="el" href="custom_memory_pools.html#buddy_algorithm">Buddy allocation algorithm</a></li>
 </ul>
 </li>
-<li><a class="el" href="defragmentation.html">Defragmentation</a></li>
+<li><a class="el" href="defragmentation.html">Defragmentation</a><ul>
+<li><a class="el" href="defragmentation.html#defragmentation_cpu">Defragmenting CPU memory</a></li>
+<li><a class="el" href="defragmentation.html#defragmentation_gpu">Defragmenting GPU memory</a></li>
+<li><a class="el" href="defragmentation.html#defragmentation_additional_notes">Additional notes</a></li>
+</ul>
+</li>
 <li><a class="el" href="lost_allocations.html">Lost allocations</a></li>
 <li><a class="el" href="statistics.html">Statistics</a><ul>
 <li><a class="el" href="statistics.html#statistics_numeric_statistics">Numeric statistics</a></li>

docs/html/index.html

@@ -31,6 +31,7 @@ var menudata={children:[
 {text:"All",url:"functions.html",children:[
 {text:"a",url:"functions.html#index_a"},
 {text:"b",url:"functions.html#index_b"},
+{text:"c",url:"functions.html#index_c"},
 {text:"d",url:"functions.html#index_d"},
 {text:"f",url:"functions.html#index_f"},
 {text:"m",url:"functions.html#index_m"},
@@ -44,6 +45,7 @@ var menudata={children:[
 {text:"Variables",url:"functions_vars.html",children:[
 {text:"a",url:"functions_vars.html#index_a"},
 {text:"b",url:"functions_vars.html#index_b"},
+{text:"c",url:"functions_vars.html#index_c"},
 {text:"d",url:"functions_vars.html#index_d"},
 {text:"f",url:"functions_vars.html#index_f"},
 {text:"m",url:"functions_vars.html#index_m"},

docs/html/menudata.js

@@ -1,10 +1,9 @@
 var searchData=
 [
   ['allocation_20names_20and_20user_20data',['Allocation names and user data',['../allocation_annotation.html',1,'index']]],
-  ['allocationcount',['allocationCount',['../struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff',1,'VmaStatInfo::allocationCount()'],['../struct_vma_pool_stats.html#ad1924eb54fffa45e9e0e65670c8fe5eb',1,'VmaPoolStats::allocationCount()'],['../struct_vma_defragmentation_info2.html#ae41a36871f23fdd34df9c72149204c57',1,'VmaDefragmentationInfo2::allocationCount()']]],
+  ['allocationcount',['allocationCount',['../struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff',1,'VmaStatInfo::allocationCount()'],['../struct_vma_pool_stats.html#ad1924eb54fffa45e9e0e65670c8fe5eb',1,'VmaPoolStats::allocationCount()'],['../struct_vma_defragmentation_info2.html#a3cf86ab32c1da779b4923d301a3056ba',1,'VmaDefragmentationInfo2::allocationCount()']]],
   ['allocationsizeavg',['allocationSizeAvg',['../struct_vma_stat_info.html#a1081a039964e566c672e7a2347f9e599',1,'VmaStatInfo']]],
   ['allocationsizemax',['allocationSizeMax',['../struct_vma_stat_info.html#a17e9733a5ecd76287d4db6e66f71f50c',1,'VmaStatInfo']]],
   ['allocationsizemin',['allocationSizeMin',['../struct_vma_stat_info.html#ade8b40bd3139c04aabd2fc538a356fea',1,'VmaStatInfo']]],
-  ['allocationslost',['allocationsLost',['../struct_vma_defragmentation_stats.html#a87f0adc9588757b1e3ac1815597ace03',1,'VmaDefragmentationStats']]],
   ['allocationsmoved',['allocationsMoved',['../struct_vma_defragmentation_stats.html#aefeabf130022008eadd75999478af3f9',1,'VmaDefragmentationStats']]]
 ];