AuroraMiddleware/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator synced 2024-11-21 20:00:11 +00:00
Code Issues Projects Releases Wiki Activity

Improvements in documentation regarding defragmentation

Browse Source
This commit is contained in:
Adam Sawicki 2022-03-08 13:46:58 +01:00
parent e1879e9f10
commit 85a49729c3
3 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/html/defragmentation.html
View File

@ -186,6 +186,7 @@ $(function() {
<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 >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 >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 >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> <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></div><!-- contents -->
</div><!-- PageDoc --> </div><!-- PageDoc -->

6
docs/html/struct_vma_allocation_info.html
View File

@ -113,7 +113,7 @@ Public Attributes</h2></td></tr>
<p>Handle to Vulkan memory object. </p> <p>Handle to Vulkan memory object. </p>
<p >Same memory object can be shared by multiple allocations.</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>
</div> </div>
@ -148,7 +148,7 @@ Public Attributes</h2></td></tr>
<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>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 >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>
</div> </div>
@ -166,7 +166,7 @@ Public Attributes</h2></td></tr>
<p>Pointer to the beginning of this allocation as mapped data. </p> <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 >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>
</div> </div>

11
include/vk_mem_alloc.h
View File

@ -1344,7 +1344,7 @@ typedef struct VmaAllocationInfo
Same memory object can be shared by multiple allocations. 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; 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. /** \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 not entire device memory block. Functions like vmaMapMemory(), vmaBindBufferMemory() also refer to the beginning of the allocation
and apply this offset automatically. 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; VkDeviceSize offset;
/** \brief Size of this allocation, in bytes. /** \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. created with #VMA_ALLOCATION_CREATE_MAPPED_BIT flag, this value is null.
It can change after call to vmaMapMemory(), vmaUnmapMemory(). 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; void* VMA_NULLABLE pMappedData;
/** \brief Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vmaSetAllocationUserData(). /** \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 usage, possibly from multiple threads, with the exception that allocations
returned in VmaDefragmentationPassMoveInfo::pMoves shouldn't be destroyed until the defragmentation pass is ended. 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. \note Defragmentation is not supported in custom pools created with #VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT.