mirror/VulkanMemoryAllocator
1
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2024-11-25 08:04:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
1c35ba99ce
VulkanMemoryAllocator/docs/html/defragmentation.html
Adam Sawicki eb46f62376 Added documentation for VK_KHR_external_memory_win32 
Rebuilt the documentation.
2024-08-28 13:20:19 +02:00

225 lines
27 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.11.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: Defragmentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">Vulkan Memory Allocator
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.11.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search',false);
$(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){ initResizable(false); });
/* @license-end */
</script>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Vulkan Memory Allocator</a></li> </ul>
</div>
</div><!-- top -->
<div id="doc-content">
<div><div class="header">
<div class="headertitle"><div class="title">Defragmentation</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Interleaved allocations and deallocations of many objects of varying size can cause fragmentation over time, which can lead to a situation where the library is unable to find a continuous range of free memory for a new allocation despite there is enough free space, just scattered across many small free ranges between existing allocations.</p>
<p>To mitigate this problem, you can use defragmentation feature. It doesn't happen automatically though and needs your cooperation, because VMA is a low level library that only allocates memory. It cannot recreate buffers and images in a new place as it doesn't remember the contents of <code>VkBufferCreateInfo</code> / <code>VkImageCreateInfo</code> structures. It cannot copy their contents as it doesn't record any commands to a command buffer.</p>
<p>Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_defragmentation_info.html">VmaDefragmentationInfo</a> defragInfo = {};</div>
<div class="line">defragInfo.<a class="code hl_variable" href="struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4">pool</a> = myPool;</div>
<div class="line">defragInfo.<a class="code hl_variable" href="struct_vma_defragmentation_info.html#a3e23080c978ecf3abb3180f5b2069da7">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#gga6552a65b71d16f378c6994b3ceaef50ca2e6469bcf5a094776ceb5d118263f04b">VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT</a>;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_defragmentation_context.html">VmaDefragmentationContext</a> defragCtx;</div>
<div class="line">VkResult res = <a class="code hl_function" href="group__group__alloc.html#gac3335566858b45541fa9c0d7a6bbb57e">vmaBeginDefragmentation</a>(allocator, &amp;defragInfo, &amp;defragCtx);</div>
<div class="line"><span class="comment">// Check res...</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordflow">for</span>(;;)</div>
<div class="line">{</div>
<div class="line"> <a class="code hl_struct" href="struct_vma_defragmentation_pass_move_info.html">VmaDefragmentationPassMoveInfo</a> pass;</div>
<div class="line"> res = <a class="code hl_function" href="group__group__alloc.html#ga980d7da2ce3b1fd5c8b8476bc362cc00">vmaBeginDefragmentationPass</a>(allocator, defragCtx, &amp;pass);</div>
<div class="line"> <span class="keywordflow">if</span>(res == VK_SUCCESS)</div>
<div class="line"> <span class="keywordflow">break</span>;</div>
<div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span>(res != VK_INCOMPLETE)</div>
<div class="line"> <span class="comment">// Handle error...</span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">for</span>(uint32_t i = 0; i &lt; pass.<a class="code hl_variable" href="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">moveCount</a>; ++i)</div>
<div class="line"> {</div>
<div class="line"> <span class="comment">// Inspect pass.pMoves[i].srcAllocation, identify what buffer/image it represents.</span></div>
<div class="line"> <a class="code hl_struct" href="struct_vma_allocation_info.html">VmaAllocationInfo</a> allocInfo;</div>
<div class="line"> <a class="code hl_function" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b">vmaGetAllocationInfo</a>(allocator, 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#a25aa1bb64efc507a49c6cbc50689f862">srcAllocation</a>, &amp;allocInfo);</div>
<div class="line"> MyEngineResourceData* resData = (MyEngineResourceData*)allocInfo.<a class="code hl_variable" href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">pUserData</a>;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Recreate and bind this buffer/image at: pass.pMoves[i].dstMemory, pass.pMoves[i].dstOffset.</span></div>
<div class="line"> VkImageCreateInfo imgCreateInfo = ...</div>
<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 = <a class="code hl_function" href="group__group__alloc.html#ga3d3ca45799923aa5d138e9e5f9eb2da5">vmaBindImageMemory</a>(allocator, 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#ab65b106adf209acd7313296d1075300e">dstTmpAllocation</a>, 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>
<div class="line"> vkCmdCopyImage(cmdBuf, resData-&gt;img, ..., newImg, ...);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Make sure the copy commands finished executing.</span></div>
<div class="line"> vkWaitForFences(...);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Destroy old buffers/images bound with pass.pMoves[i].srcAllocation.</span></div>
<div class="line"> <span class="keywordflow">for</span>(uint32_t i = 0; i &lt; pass.<a class="code hl_variable" href="struct_vma_defragmentation_pass_move_info.html#a1b3e18c23f9691f35baf183e615c4408">moveCount</a>; ++i)</div>
<div class="line"> {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> vkDestroyImage(device, resData-&gt;img, <span class="keyword">nullptr</span>);</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Update appropriate descriptors to point to the new places...</span></div>
<div class="line"> </div>
<div class="line"> res = <a class="code hl_function" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226">vmaEndDefragmentationPass</a>(allocator, defragCtx, &amp;pass);</div>
<div class="line"> <span class="keywordflow">if</span>(res == VK_SUCCESS)</div>
<div class="line"> <span class="keywordflow">break</span>;</div>
<div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span>(res != VK_INCOMPLETE)</div>
<div class="line"> <span class="comment">// Handle error...</span></div>
<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>
<div class="ttc" id="agroup__group__alloc_html_gac3335566858b45541fa9c0d7a6bbb57e"><div class="ttname"><a href="group__group__alloc.html#gac3335566858b45541fa9c0d7a6bbb57e">vmaBeginDefragmentation</a></div><div class="ttdeci">VkResult vmaBeginDefragmentation(VmaAllocator allocator, const VmaDefragmentationInfo *pInfo, VmaDefragmentationContext *pContext)</div><div class="ttdoc">Begins defragmentation process.</div></div>
<div class="ttc" id="agroup__group__alloc_html_gaded05a445742a00718ee766144c5c226"><div class="ttname"><a href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226">vmaEndDefragmentationPass</a></div><div class="ttdeci">VkResult vmaEndDefragmentationPass(VmaAllocator allocator, VmaDefragmentationContext context, VmaDefragmentationPassMoveInfo *pPassInfo)</div><div class="ttdoc">Ends single defragmentation pass.</div></div>
<div class="ttc" id="agroup__group__alloc_html_gga6552a65b71d16f378c6994b3ceaef50ca2e6469bcf5a094776ceb5d118263f04b"><div class="ttname"><a href="group__group__alloc.html#gga6552a65b71d16f378c6994b3ceaef50ca2e6469bcf5a094776ceb5d118263f04b">VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT</a></div><div class="ttdeci">@ VMA_DEFRAGMENTATION_FLAG_ALGORITHM_FAST_BIT</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:765</div></div>
<div class="ttc" id="astruct_vma_allocation_info_html"><div class="ttname"><a href="struct_vma_allocation_info.html">VmaAllocationInfo</a></div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1408</div></div>
<div class="ttc" id="astruct_vma_allocation_info_html_adc507656149c04de7ed95d0042ba2a13"><div class="ttname"><a href="struct_vma_allocation_info.html#adc507656149c04de7ed95d0042ba2a13">VmaAllocationInfo::pUserData</a></div><div class="ttdeci">void * pUserData</div><div class="ttdoc">Custom general-purpose pointer that was passed as VmaAllocationCreateInfo::pUserData or set using vma...</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1455</div></div>
<div class="ttc" id="astruct_vma_defragmentation_context_html"><div class="ttname"><a href="struct_vma_defragmentation_context.html">VmaDefragmentationContext</a></div><div class="ttdoc">An opaque object that represents started defragmentation process.</div></div>
<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:1498</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:1505</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:1500</div></div>
<div class="ttc" id="astruct_vma_defragmentation_move_html_a25aa1bb64efc507a49c6cbc50689f862"><div class="ttname"><a href="struct_vma_defragmentation_move.html#a25aa1bb64efc507a49c6cbc50689f862">VmaDefragmentationMove::srcAllocation</a></div><div class="ttdeci">VmaAllocation srcAllocation</div><div class="ttdoc">Allocation that should be moved.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1531</div></div>
<div class="ttc" id="astruct_vma_defragmentation_move_html_ab65b106adf209acd7313296d1075300e"><div class="ttname"><a href="struct_vma_defragmentation_move.html#ab65b106adf209acd7313296d1075300e">VmaDefragmentationMove::dstTmpAllocation</a></div><div class="ttdeci">VmaAllocation dstTmpAllocation</div><div class="ttdoc">Temporary allocation pointing to destination memory that will replace srcAllocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1538</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:1546</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:1548</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:1572</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 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 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 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 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>
<li>You need to make sure these commands finished executing before destroying the source buffers/images and before calling <a class="el" href="group__group__alloc.html#gaded05a445742a00718ee766144c5c226" title="Ends single defragmentation pass.">vmaEndDefragmentationPass()</a>.</li>
</ul>
</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_CACHED</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 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 source <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> object.</li>
</ul>
</li>
</ul>
<p>You can defragment a specific custom pool by setting <a class="el" href="struct_vma_defragmentation_info.html#a18dd2097d8ab2976cdc7dd3e7b978bd4" title="Custom pool to be defragmented.">VmaDefragmentationInfo::pool</a> (like in the example above) or all the default pools by setting this member to null.</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>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 -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.11.0
</small></address>
</div><!-- doc-content -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink