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
master
VulkanMemoryAllocator/docs/html/virtual_allocator.html
Adam Sawicki eb46f62376 Added documentation for VK_KHR_external_memory_win32 
Rebuilt the documentation.
2024-08-28 13:20:19 +02:00

209 lines
28 KiB
HTML
Raw Permalink 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: Virtual allocator</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">Virtual allocator</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>As an extra feature, the core allocation algorithm of the library is exposed through a simple and convenient API of "virtual allocator". It doesn't allocate any real GPU memory. It just keeps track of used and free regions of a "virtual block". You can use it to allocate your own memory or other objects, even completely unrelated to Vulkan. A common use case is sub-allocation of pieces of one large GPU buffer.</p>
<h1><a class="anchor" id="virtual_allocator_creating_virtual_block"></a>
Creating virtual block</h1>
<p>To use this functionality, there is no main "allocator" object. You don't need to have <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> object created. All you need to do is to create a separate <a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a> object for each block of memory you want to be managed by the allocator:</p>
<ol type="1">
<li>Fill in <a class="el" href="struct_vma_virtual_block_create_info.html" title="Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().">VmaVirtualBlockCreateInfo</a> structure.</li>
<li>Call <a class="el" href="group__group__virtual.html#gab585754076877265fdae33e5c40ef13b" title="Creates new VmaVirtualBlock object.">vmaCreateVirtualBlock()</a>. Get new <a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a> object.</li>
</ol>
<p>Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_virtual_block_create_info.html">VmaVirtualBlockCreateInfo</a> blockCreateInfo = {};</div>
<div class="line">blockCreateInfo.<a class="code hl_variable" href="struct_vma_virtual_block_create_info.html#a670ab8c6a6e822f3c36781d79e8824e9">size</a> = 1048576; <span class="comment">// 1 MB</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_virtual_block.html">VmaVirtualBlock</a> block;</div>
<div class="line">VkResult res = <a class="code hl_function" href="group__group__virtual.html#gab585754076877265fdae33e5c40ef13b">vmaCreateVirtualBlock</a>(&amp;blockCreateInfo, &amp;block);</div>
<div class="ttc" id="agroup__group__virtual_html_gab585754076877265fdae33e5c40ef13b"><div class="ttname"><a href="group__group__virtual.html#gab585754076877265fdae33e5c40ef13b">vmaCreateVirtualBlock</a></div><div class="ttdeci">VkResult vmaCreateVirtualBlock(const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)</div><div class="ttdoc">Creates new VmaVirtualBlock object.</div></div>
<div class="ttc" id="astruct_vma_virtual_block_create_info_html"><div class="ttname"><a href="struct_vma_virtual_block_create_info.html">VmaVirtualBlockCreateInfo</a></div><div class="ttdoc">Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1597</div></div>
<div class="ttc" id="astruct_vma_virtual_block_create_info_html_a670ab8c6a6e822f3c36781d79e8824e9"><div class="ttname"><a href="struct_vma_virtual_block_create_info.html#a670ab8c6a6e822f3c36781d79e8824e9">VmaVirtualBlockCreateInfo::size</a></div><div class="ttdeci">VkDeviceSize size</div><div class="ttdoc">Total size of the virtual block.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1603</div></div>
<div class="ttc" id="astruct_vma_virtual_block_html"><div class="ttname"><a href="struct_vma_virtual_block.html">VmaVirtualBlock</a></div><div class="ttdoc">Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...</div></div>
</div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_making_virtual_allocations"></a>
Making virtual allocations</h1>
<p><a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a> object contains internal data structure that keeps track of free and occupied regions using the same code as the main Vulkan memory allocator. Similarly to <a class="el" href="struct_vma_allocation.html" title="Represents single memory allocation.">VmaAllocation</a> for standard GPU allocations, there is <a class="el" href="struct_vma_virtual_allocation.html" title="Represents single memory allocation done inside VmaVirtualBlock.">VmaVirtualAllocation</a> type that represents an opaque handle to an allocation within the virtual block.</p>
<p>In order to make such allocation:</p>
<ol type="1">
<li>Fill in <a class="el" href="struct_vma_virtual_allocation_create_info.html" title="Parameters of created virtual allocation to be passed to vmaVirtualAllocate().">VmaVirtualAllocationCreateInfo</a> structure.</li>
<li>Call <a class="el" href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01" title="Allocates new virtual allocation inside given VmaVirtualBlock.">vmaVirtualAllocate()</a>. Get new <a class="el" href="struct_vma_virtual_allocation.html" title="Represents single memory allocation done inside VmaVirtualBlock.">VmaVirtualAllocation</a> object that represents the allocation. You can also receive <code>VkDeviceSize offset</code> that was assigned to the allocation.</li>
</ol>
<p>Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_virtual_allocation_create_info.html">VmaVirtualAllocationCreateInfo</a> allocCreateInfo = {};</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_virtual_allocation_create_info.html#aae08752b86817abd0d944c6025dc603e">size</a> = 4096; <span class="comment">// 4 KB</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_virtual_allocation.html">VmaVirtualAllocation</a> alloc;</div>
<div class="line">VkDeviceSize offset;</div>
<div class="line">res = <a class="code hl_function" href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01">vmaVirtualAllocate</a>(block, &amp;allocCreateInfo, &amp;alloc, &amp;offset);</div>
<div class="line"><span class="keywordflow">if</span>(res == VK_SUCCESS)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Use the 4 KB of your memory starting at offset.</span></div>
<div class="line">}</div>
<div class="line"><span class="keywordflow">else</span></div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Allocation failed - no space for it could be found. Handle this error!</span></div>
<div class="line">}</div>
<div class="ttc" id="agroup__group__virtual_html_ga6b7cdcc1c3e5103c323fedc4e1319e01"><div class="ttname"><a href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01">vmaVirtualAllocate</a></div><div class="ttdeci">VkResult vmaVirtualAllocate(VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)</div><div class="ttdoc">Allocates new virtual allocation inside given VmaVirtualBlock.</div></div>
<div class="ttc" id="astruct_vma_virtual_allocation_create_info_html"><div class="ttname"><a href="struct_vma_virtual_allocation_create_info.html">VmaVirtualAllocationCreateInfo</a></div><div class="ttdoc">Parameters of created virtual allocation to be passed to vmaVirtualAllocate().</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1618</div></div>
<div class="ttc" id="astruct_vma_virtual_allocation_create_info_html_aae08752b86817abd0d944c6025dc603e"><div class="ttname"><a href="struct_vma_virtual_allocation_create_info.html#aae08752b86817abd0d944c6025dc603e">VmaVirtualAllocationCreateInfo::size</a></div><div class="ttdeci">VkDeviceSize size</div><div class="ttdoc">Size of the allocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1623</div></div>
<div class="ttc" id="astruct_vma_virtual_allocation_html"><div class="ttname"><a href="struct_vma_virtual_allocation.html">VmaVirtualAllocation</a></div><div class="ttdoc">Represents single memory allocation done inside VmaVirtualBlock.</div></div>
</div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_deallocation"></a>
Deallocation</h1>
<p>When no longer needed, an allocation can be freed by calling <a class="el" href="group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033" title="Frees virtual allocation inside given VmaVirtualBlock.">vmaVirtualFree()</a>. You can only pass to this function an allocation that was previously returned by <a class="el" href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01" title="Allocates new virtual allocation inside given VmaVirtualBlock.">vmaVirtualAllocate()</a> called for the same <a class="el" href="struct_vma_virtual_block.html" title="Handle to a virtual block object that allows to use core allocation algorithm without allocating any ...">VmaVirtualBlock</a>.</p>
<p>When whole block is no longer needed, the block object can be released by calling <a class="el" href="group__group__virtual.html#ga3795f7783ae2c182cede067d656f66a5" title="Destroys VmaVirtualBlock object.">vmaDestroyVirtualBlock()</a>. All allocations must be freed before the block is destroyed, which is checked internally by an assert. However, if you don't want to call <a class="el" href="group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033" title="Frees virtual allocation inside given VmaVirtualBlock.">vmaVirtualFree()</a> for each allocation, you can use <a class="el" href="group__group__virtual.html#ga5eda6f55919fb05bd2f56a112590c571" title="Frees all virtual allocations inside given VmaVirtualBlock.">vmaClearVirtualBlock()</a> to free them all at once - a feature not available in normal Vulkan memory allocator. Example:</p>
<div class="fragment"><div class="line"><a class="code hl_function" href="group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033">vmaVirtualFree</a>(block, alloc);</div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga3795f7783ae2c182cede067d656f66a5">vmaDestroyVirtualBlock</a>(block);</div>
<div class="ttc" id="agroup__group__virtual_html_ga09fc688c0c3653ff23723b037e5d5033"><div class="ttname"><a href="group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033">vmaVirtualFree</a></div><div class="ttdeci">void vmaVirtualFree(VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation)</div><div class="ttdoc">Frees virtual allocation inside given VmaVirtualBlock.</div></div>
<div class="ttc" id="agroup__group__virtual_html_ga3795f7783ae2c182cede067d656f66a5"><div class="ttname"><a href="group__group__virtual.html#ga3795f7783ae2c182cede067d656f66a5">vmaDestroyVirtualBlock</a></div><div class="ttdeci">void vmaDestroyVirtualBlock(VmaVirtualBlock virtualBlock)</div><div class="ttdoc">Destroys VmaVirtualBlock object.</div></div>
</div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_allocation_parameters"></a>
Allocation parameters</h1>
<p>You can attach a custom pointer to each allocation by using <a class="el" href="group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2" title="Changes custom pointer associated with given virtual allocation.">vmaSetVirtualAllocationUserData()</a>. Its default value is null. It can be used to store any data that needs to be associated with that allocation - e.g. an index, a handle, or a pointer to some larger data structure containing more information. Example:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>CustomAllocData</div>
<div class="line">{</div>
<div class="line"> std::string m_AllocName;</div>
<div class="line">};</div>
<div class="line">CustomAllocData* allocData = <span class="keyword">new</span> CustomAllocData();</div>
<div class="line">allocData-&gt;m_AllocName = <span class="stringliteral">&quot;My allocation 1&quot;</span>;</div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2">vmaSetVirtualAllocationUserData</a>(block, alloc, allocData);</div>
<div class="ttc" id="agroup__group__virtual_html_ga001ea1850458a4062b829e09c303fca2"><div class="ttname"><a href="group__group__virtual.html#ga001ea1850458a4062b829e09c303fca2">vmaSetVirtualAllocationUserData</a></div><div class="ttdeci">void vmaSetVirtualAllocationUserData(VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, void *pUserData)</div><div class="ttdoc">Changes custom pointer associated with given virtual allocation.</div></div>
</div><!-- fragment --><p>The pointer can later be fetched, along with allocation offset and size, by passing the allocation handle to function <a class="el" href="group__group__virtual.html#ga8ee14ceb1fe033ec84d8aa29e1f75afa" title="Returns information about a specific virtual allocation within a virtual block, like its size and pUs...">vmaGetVirtualAllocationInfo()</a> and inspecting returned structure <a class="el" href="struct_vma_virtual_allocation_info.html" title="Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().">VmaVirtualAllocationInfo</a>. If you allocated a new object to be used as the custom pointer, don't forget to delete that object before freeing the allocation! Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_virtual_allocation_info.html">VmaVirtualAllocationInfo</a> allocInfo;</div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga8ee14ceb1fe033ec84d8aa29e1f75afa">vmaGetVirtualAllocationInfo</a>(block, alloc, &amp;allocInfo);</div>
<div class="line"><span class="keyword">delete</span> (CustomAllocData*)allocInfo.<a class="code hl_variable" href="struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45">pUserData</a>;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga09fc688c0c3653ff23723b037e5d5033">vmaVirtualFree</a>(block, alloc);</div>
<div class="ttc" id="agroup__group__virtual_html_ga8ee14ceb1fe033ec84d8aa29e1f75afa"><div class="ttname"><a href="group__group__virtual.html#ga8ee14ceb1fe033ec84d8aa29e1f75afa">vmaGetVirtualAllocationInfo</a></div><div class="ttdeci">void vmaGetVirtualAllocationInfo(VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)</div><div class="ttdoc">Returns information about a specific virtual allocation within a virtual block, like its size and pUs...</div></div>
<div class="ttc" id="astruct_vma_virtual_allocation_info_html"><div class="ttname"><a href="struct_vma_virtual_allocation_info.html">VmaVirtualAllocationInfo</a></div><div class="ttdoc">Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1641</div></div>
<div class="ttc" id="astruct_vma_virtual_allocation_info_html_a41d5cb09357656411653d82fee436f45"><div class="ttname"><a href="struct_vma_virtual_allocation_info.html#a41d5cb09357656411653d82fee436f45">VmaVirtualAllocationInfo::pUserData</a></div><div class="ttdeci">void * pUserData</div><div class="ttdoc">Custom pointer associated with the allocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1656</div></div>
</div><!-- fragment --><h1><a class="anchor" id="virtual_allocator_alignment_and_units"></a>
Alignment and units</h1>
<p>It feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member <a class="el" href="struct_vma_virtual_allocation_create_info.html#a9d19709872fc1904a105079e1c885821" title="Required alignment of the allocation. Optional.">VmaVirtualAllocationCreateInfo::alignment</a> to request it. Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_virtual_allocation_create_info.html">VmaVirtualAllocationCreateInfo</a> allocCreateInfo = {};</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_virtual_allocation_create_info.html#aae08752b86817abd0d944c6025dc603e">size</a> = 4096; <span class="comment">// 4 KB</span></div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_virtual_allocation_create_info.html#a9d19709872fc1904a105079e1c885821">alignment</a> = 4; <span class="comment">// Returned offset must be a multiply of 4 B</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_virtual_allocation.html">VmaVirtualAllocation</a> alloc;</div>
<div class="line">res = <a class="code hl_function" href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01">vmaVirtualAllocate</a>(block, &amp;allocCreateInfo, &amp;alloc, <span class="keyword">nullptr</span>);</div>
<div class="ttc" id="astruct_vma_virtual_allocation_create_info_html_a9d19709872fc1904a105079e1c885821"><div class="ttname"><a href="struct_vma_virtual_allocation_create_info.html#a9d19709872fc1904a105079e1c885821">VmaVirtualAllocationCreateInfo::alignment</a></div><div class="ttdeci">VkDeviceSize alignment</div><div class="ttdoc">Required alignment of the allocation. Optional.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1628</div></div>
</div><!-- fragment --><p>Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or <code>sizeof(MyDataStruct)</code>, you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:</p>
<ul>
<li><a class="el" href="struct_vma_virtual_block_create_info.html#a670ab8c6a6e822f3c36781d79e8824e9" title="Total size of the virtual block.">VmaVirtualBlockCreateInfo::size</a></li>
<li><a class="el" href="struct_vma_virtual_allocation_create_info.html#aae08752b86817abd0d944c6025dc603e" title="Size of the allocation.">VmaVirtualAllocationCreateInfo::size</a> and <a class="el" href="struct_vma_virtual_allocation_create_info.html#a9d19709872fc1904a105079e1c885821" title="Required alignment of the allocation. Optional.">VmaVirtualAllocationCreateInfo::alignment</a></li>
<li>Using offset returned by <a class="el" href="group__group__virtual.html#ga6b7cdcc1c3e5103c323fedc4e1319e01" title="Allocates new virtual allocation inside given VmaVirtualBlock.">vmaVirtualAllocate()</a> or in <a class="el" href="struct_vma_virtual_allocation_info.html#accb40a8205f49ccca3de975da7d1a2b5" title="Offset of the allocation.">VmaVirtualAllocationInfo::offset</a></li>
</ul>
<h1><a class="anchor" id="virtual_allocator_statistics"></a>
Statistics</h1>
<p>You can obtain statistics of a virtual block using <a class="el" href="group__group__virtual.html#ga2902aa3130866afcc64bb5f984113db3" title="Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock...">vmaGetVirtualBlockStatistics()</a> (to get brief statistics that are fast to calculate) or <a class="el" href="group__group__virtual.html#ga93c5741bca44b43e5b849cacbd616098" title="Calculates and returns detailed statistics about virtual allocations and memory usage in given VmaVir...">vmaCalculateVirtualBlockStatistics()</a> (to get more detailed statistics, slower to calculate). The functions fill structures <a class="el" href="struct_vma_statistics.html" title="Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool,...">VmaStatistics</a>, <a class="el" href="struct_vma_detailed_statistics.html" title="More detailed statistics than VmaStatistics.">VmaDetailedStatistics</a> respectively - same as used by the normal Vulkan memory allocator. Example:</p>
<div class="fragment"><div class="line"><a class="code hl_struct" href="struct_vma_statistics.html">VmaStatistics</a> stats;</div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga2902aa3130866afcc64bb5f984113db3">vmaGetVirtualBlockStatistics</a>(block, &amp;stats);</div>
<div class="line">printf(<span class="stringliteral">&quot;My virtual block has %llu bytes used by %u virtual allocations\n&quot;</span>,</div>
<div class="line"> stats.<a class="code hl_variable" href="struct_vma_statistics.html#a21db06eba3422f87a2b4b4703d879c16">allocationBytes</a>, stats.<a class="code hl_variable" href="struct_vma_statistics.html#ab0ff76e50f58f9f54b6f265e5bf5dde2">allocationCount</a>);</div>
<div class="ttc" id="agroup__group__virtual_html_ga2902aa3130866afcc64bb5f984113db3"><div class="ttname"><a href="group__group__virtual.html#ga2902aa3130866afcc64bb5f984113db3">vmaGetVirtualBlockStatistics</a></div><div class="ttdeci">void vmaGetVirtualBlockStatistics(VmaVirtualBlock virtualBlock, VmaStatistics *pStats)</div><div class="ttdoc">Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock...</div></div>
<div class="ttc" id="astruct_vma_statistics_html"><div class="ttname"><a href="struct_vma_statistics.html">VmaStatistics</a></div><div class="ttdoc">Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool,...</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1178</div></div>
<div class="ttc" id="astruct_vma_statistics_html_a21db06eba3422f87a2b4b4703d879c16"><div class="ttname"><a href="struct_vma_statistics.html#a21db06eba3422f87a2b4b4703d879c16">VmaStatistics::allocationBytes</a></div><div class="ttdeci">VkDeviceSize allocationBytes</div><div class="ttdoc">Total number of bytes occupied by all VmaAllocation objects.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1200</div></div>
<div class="ttc" id="astruct_vma_statistics_html_ab0ff76e50f58f9f54b6f265e5bf5dde2"><div class="ttname"><a href="struct_vma_statistics.html#ab0ff76e50f58f9f54b6f265e5bf5dde2">VmaStatistics::allocationCount</a></div><div class="ttdeci">uint32_t allocationCount</div><div class="ttdoc">Number of VmaAllocation objects allocated.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1186</div></div>
</div><!-- fragment --><p>You can also request a full list of allocations and free regions as a string in JSON format by calling <a class="el" href="group__group__stats.html#ga52d810e1222c592e5d80556ad005f1e6" title="Builds and returns a null-terminated string in JSON format with information about given VmaVirtualBlo...">vmaBuildVirtualBlockStatsString()</a>. Returned string must be later freed using <a class="el" href="group__group__stats.html#ga47fb8d8aa69df4a7c23a9719b4080623" title="Frees a string returned by vmaBuildVirtualBlockStatsString().">vmaFreeVirtualBlockStatsString()</a>. The format of this string differs from the one returned by the main Vulkan allocator, but it is similar.</p>
<h1><a class="anchor" id="virtual_allocator_additional_considerations"></a>
Additional considerations</h1>
<p>The "virtual allocator" functionality is implemented on a level of individual memory blocks. Keeping track of a whole collection of blocks, allocating new ones when out of free space, deleting empty ones, and deciding which one to try first for a new allocation must be implemented by the user.</p>
<p>Alternative allocation algorithms are supported, just like in custom pools of the real GPU memory. See enum <a class="el" href="group__group__virtual.html#ga88bcf8c1cd3bb1610ff7343811c65bca" title="Flags to be passed as VmaVirtualBlockCreateInfo::flags.">VmaVirtualBlockCreateFlagBits</a> to learn how to specify them (e.g. <a class="el" href="group__group__virtual.html#gga88bcf8c1cd3bb1610ff7343811c65bcaae6423e2fa2f3c9211b21c819e3f10f96" title="Enables alternative, linear allocation algorithm in this virtual block.">VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT</a>). You can find their description in chapter <a class="el" href="custom_memory_pools.html">Custom memory pools</a>. Allocation strategies are also supported. See enum <a class="el" href="group__group__virtual.html#ga2e9c64d405b14156fea7e10c4ad06cb6" title="Flags to be passed as VmaVirtualAllocationCreateInfo::flags.">VmaVirtualAllocationCreateFlagBits</a> to learn how to specify them (e.g. <a class="el" href="group__group__virtual.html#gga2e9c64d405b14156fea7e10c4ad06cb6a562d10a46012719d33167d3dc5dbbf9b" title="Allocation strategy that tries to minimize allocation time.">VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT</a>).</p>
<p>Following features are supported only by the allocator of the real GPU memory and not by virtual allocations: buffer-image granularity, <code>VMA_DEBUG_MARGIN</code>, <code>VMA_MIN_ALIGNMENT</code>. </p>
</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