Added documentation chapter "Writing custom defragmentation algorithm".

Author: adam-sawicki-a

docs/html/defragmentation.html

@@ -106,7 +106,16 @@ <h1><a class="anchor" id="defragmentation_additional_notes"></a>
 <p>While using defragmentation, you may experience validation layer warnings, which you just need to ignore. See <a class="el" href="general_considerations.html#general_considerations_validation_layer_warnings">Validation layer warnings</a>.</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>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 may still remain after this call. This is normal. </p>
+<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 need to be moved. Some fragmentation may still remain - this is normal.</p>
+<h1><a class="anchor" id="defragmentation_custom_algorithm"></a>
+Writing custom defragmentation algorithm</h1>
+<p>If you want to implement your own, custom defragmentation algorithm, there is infrastructure prepared for that, but it is not exposed through the library API - you need to hack its source code. Here are steps needed to do this:</p>
+<ol type="1">
+<li>Main thing you need to do is to define your own class derived from base abstract class <code>VmaDefragmentationAlgorithm</code> and implement your version of its pure virtual method. See definition and comments of this class for details.</li>
+<li>Your code needs to interact with device memory block metadata. If you need more access to its data than it's provided by its public interface, declare your new class as a friend class e.g. in class <code>VmaBlockMetadata_Generic</code>.</li>
+<li>If you want to create a flag that would enable your algorithm or pass some additional flags to configure it, define some enum with such flags and use them in <a class="el" href="struct_vma_defragmentation_info2.html#a53e844ee5633e229cf6daf14b2d9fff9" title="Reserved for future use. Should be 0. ">VmaDefragmentationInfo2::flags</a>.</li>
+<li>Modify function <code>VmaBlockVectorDefragmentationContext::Begin</code> to create object of your new class whenever needed. </li>
+</ol>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>

docs/html/index.html

@@ -109,6 +109,7 @@ <h1><a class="anchor" id="main_table_of_contents"></a>
 <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>
+<li><a class="el" href="defragmentation.html#defragmentation_custom_algorithm">Writing custom allocation algorithm</a></li>
 </ul>
 </li>
 <li><a class="el" href="lost_allocations.html">Lost allocations</a></li>

docs/html/vk__mem__alloc_8h_source.html

@@ -65,6 +65,7 @@ Documentation of all members: vk_mem_alloc.h
   	- [Defragmenting CPU memory](@ref defragmentation_cpu)
   	- [Defragmenting GPU memory](@ref defragmentation_gpu)
   	- [Additional notes](@ref defragmentation_additional_notes)
+  	- [Writing custom allocation algorithm](@ref defragmentation_custom_algorithm)
   - \subpage lost_allocations
   - \subpage statistics
     - [Numeric statistics](@ref statistics_numeric_statistics)
@@ -903,7 +904,26 @@ 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 may still remain after this call. This is normal.
+need to be moved. Some fragmentation may still remain - this is normal.
+
+\section defragmentation_custom_algorithm Writing custom defragmentation algorithm
+
+If you want to implement your own, custom defragmentation algorithm,
+there is infrastructure prepared for that,
+but it is not exposed through the library API - you need to hack its source code.
+Here are steps needed to do this:
+
+-# Main thing you need to do is to define your own class derived from base abstract
+   class `VmaDefragmentationAlgorithm` and implement your version of its pure virtual method.
+   See definition and comments of this class for details.
+-# Your code needs to interact with device memory block metadata.
+   If you need more access to its data than it's provided by its public interface,
+   declare your new class as a friend class e.g. in class `VmaBlockMetadata_Generic`.
+-# If you want to create a flag that would enable your algorithm or pass some additional
+   flags to configure it, define some enum with such flags and use them in
+   VmaDefragmentationInfo2::flags.
+-# Modify function `VmaBlockVectorDefragmentationContext::Begin` to create object
+   of your new class whenever needed.
 
 
 \page lost_allocations Lost allocations
@@ -5844,7 +5864,7 @@ struct VmaPool_T
 Performs defragmentation:
 
 - Updates `pBlockVector->m_pMetadata`.
-- Updates allocations by calling ChangeBlockAllocation().
+- Updates allocations by calling ChangeBlockAllocation() or ChangeOffset().
 - Does not move actual data, only returns requested moves as `moves`.
 */
 class VmaDefragmentationAlgorithm