Improvements in documentation regarding defragmentation

Author: adam-sawicki-a

docs/html/defragmentation.html

@@ -186,6 +186,7 @@
 <p >Defragmentation is always performed in each pool separately. Allocations are never moved between different Vulkan memory types. The size of the destination memory reserved for a moved allocation is the same as the original one. Alignment of an allocation as it was determined using <code>vkGetBufferMemoryRequirements()</code> etc. is also respected after defragmentation. Buffers/images should be recreated with the same <code>VkBufferCreateInfo</code> / <code>VkImageCreateInfo</code> parameters as the original ones.</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: <a class="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>, <a class="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 <a class="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>
+<p ><b>Mapping</b> is preserved on allocations that are moved during defragmentation. Whether through <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f" title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a> or <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a>, the allocations are mapped at their new place. Of course, pointer to the mapped data changes, so it needs to be queried using <a class="el" href="struct_vma_allocation_info.html#a5eeffbe2d2f30f53370ff14aefbadbe2" title="Pointer to the beginning of this allocation as mapped data.">VmaAllocationInfo::pMappedData</a>.</p>
 <dl class="section note"><dt>Note</dt><dd>Defragmentation is not supported in custom pools created with <a class="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>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->

docs/html/struct_vma_allocation_info.html

@@ -113,7 +113,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#ae0bfb7dfdf79a76ffefc9a94
 
 <p>Handle to Vulkan memory object. </p>
 <p >Same memory object can be shared by multiple allocations.</p>
-<p >It can change after call to vmaDefragment() if this allocation is passed to the function. </p>
+<p >It can change after the allocation is moved during <a class="el" href="defragmentation.html">Defragmentation</a>. </p>
 
 </div>
 </div>
@@ -148,7 +148,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a4a3c732388dbdc7a23f9365b
 
 <p>Offset in <code>VkDeviceMemory</code> object to the beginning of this allocation, in bytes. <code>(deviceMemory, offset)</code> pair is unique to this allocation. </p>
 <p >You usually don't need to use this offset. If you create a buffer or an image together with the allocation using e.g. function <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>, functions that operate on these resources refer to the beginning of the buffer or image, not entire device memory block. Functions like <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a>, <a class="el" href="group__group__alloc.html#ga6b0929b914b60cf2d45cac4bf3547470" title="Binds buffer to allocation.">vmaBindBufferMemory()</a> also refer to the beginning of the allocation and apply this offset automatically.</p>
-<p >It can change after call to vmaDefragment() if this allocation is passed to the function. </p>
+<p >It can change after the allocation is moved during <a class="el" href="defragmentation.html">Defragmentation</a>. </p>
 
 </div>
 </div>
@@ -166,7 +166,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a5eeffbe2d2f30f53370ff14a
 
 <p>Pointer to the beginning of this allocation as mapped data. </p>
 <p >If the allocation hasn't been mapped using <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a> and hasn't been created with <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a11da372cc3a82931c5e5d6146cd9dd1f" title="Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.">VMA_ALLOCATION_CREATE_MAPPED_BIT</a> flag, this value is null.</p>
-<p >It can change after call to <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a>, <a class="el" href="group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45" title="Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().">vmaUnmapMemory()</a>. It can also change after call to vmaDefragment() if this allocation is passed to the function. </p>
+<p >It can change after call to <a class="el" href="group__group__alloc.html#gad5bd1243512d099706de88168992f069" title="Maps memory represented by given allocation and returns pointer to it.">vmaMapMemory()</a>, <a class="el" href="group__group__alloc.html#ga9bc268595cb33f6ec4d519cfce81ff45" title="Unmaps memory represented by given allocation, mapped previously using vmaMapMemory().">vmaUnmapMemory()</a>. It can also change after the allocation is moved during <a class="el" href="defragmentation.html">Defragmentation</a>. </p>
 
 </div>
 </div>

include/vk_mem_alloc.h

@@ -1344,7 +1344,7 @@ typedef struct VmaAllocationInfo
 
     Same memory object can be shared by multiple allocations.
 
-    It can change after call to vmaDefragment() if this allocation is passed to the function.
+    It can change after the allocation is moved during \ref defragmentation.
     */
     VkDeviceMemory VMA_NULLABLE_NON_DISPATCHABLE deviceMemory;
     /** \brief Offset in `VkDeviceMemory` object to the beginning of this allocation, in bytes. `(deviceMemory, offset)` pair is unique to this allocation.
@@ -1354,7 +1354,7 @@ typedef struct VmaAllocationInfo
     not entire device memory block. Functions like vmaMapMemory(), vmaBindBufferMemory() also refer to the beginning of the allocation
     and apply this offset automatically.
 
-    It can change after call to vmaDefragment() if this allocation is passed to the function.
+    It can change after the allocation is moved during \ref defragmentation.
     */
     VkDeviceSize offset;
     /** \brief Size of this allocation, in bytes.
@@ -1374,7 +1374,7 @@ typedef struct VmaAllocationInfo
     created with #VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.
 
     It can change after call to vmaMapMemory(), vmaUnmapMemory().
-    It can also change after call to vmaDefragment() if this allocation is passed to the function.
+    It can also change after the allocation is moved during \ref defragmentation.
     */
     void* VMA_NULLABLE pMappedData;
     /** \brief Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vmaSetAllocationUserData().
@@ -18357,6 +18357,11 @@ It is also safe to perform the defragmentation asynchronously to render frames a
 usage, possibly from multiple threads, with the exception that allocations
 returned in VmaDefragmentationPassMoveInfo::pMoves shouldn't be destroyed until the defragmentation pass is ended.
 
+<b>Mapping</b> is preserved on allocations that are moved during defragmentation.
+Whether through #VMA_ALLOCATION_CREATE_MAPPED_BIT or vmaMapMemory(), the allocations
+are mapped at their new place. Of course, pointer to the mapped data changes, so it needs to be queried
+using VmaAllocationInfo::pMappedData.
+
 \note Defragmentation is not supported in custom pools created with #VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT.