eden-emu/VulkanMemoryAllocator
14
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2025-05-15 09:18:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

New API for statistics. COMPATIBILITY BREAKING!

Browse source 
New structure VmaStatistics, VmaDetailedStatistics, VmaTotalStatistics. Modified structure VmaBudget.
New function vmaCalculateStatistics, vmaGetPoolStatistics, vmaCalculatePoolStatistics, vmaGetVirtualBlockStatistics, vmaCalculateVirtualBlockStatistics. vmaGetHeapBudgets function unchanged.

Updated and rebuilt the docs.
This commit is contained in:
Adam Sawicki 2022-02-22 15:19:35 +01:00
parent d00699f26d
commit 226bd5a6ad
49 changed files with 1864 additions and 943 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/html/virtual_allocator.html
View file

@ -84,8 +84,8 @@ Creating virtual block</h1>
<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:1499</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:1505</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:1516</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:1522</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>
@ -111,8 +111,8 @@ Making virtual allocations</h1>
<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:1520</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:1525</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:1537</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:1542</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>
@ -140,8 +140,8 @@ Allocation parameters</h1>
<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:1543</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:1558</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:1560</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:1575</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>
@ -151,7 +151,7 @@ Alignment and units</h1>
<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:1530</div></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:1547</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>
@ -160,15 +160,15 @@ Alignment and units</h1>
</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#ga95169b4730e94757897470086ec2768a" title="Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock...">vmaCalculateVirtualBlockStats()</a>. The function fills structure <a class="el" href="struct_vma_stat_info.html" title="Calculated statistics of memory usage in entire allocator.">VmaStatInfo</a> - 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_stat_info.html">VmaStatInfo</a> statInfo;</div>
<div class="line"><a class="code hl_function" href="group__group__virtual.html#ga95169b4730e94757897470086ec2768a">vmaCalculateVirtualBlockStats</a>(block, &amp;statInfo);</div>
<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"> statInfo.<a class="code hl_variable" href="struct_vma_stat_info.html#ab0c6c73837e5a70c749fbd4f6064895a">usedBytes</a>, statInfo.<a class="code hl_variable" href="struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff">allocationCount</a>);</div>
<div class="ttc" id="agroup__group__virtual_html_ga95169b4730e94757897470086ec2768a"><div class="ttname"><a href="group__group__virtual.html#ga95169b4730e94757897470086ec2768a">vmaCalculateVirtualBlockStats</a></div><div class="ttdeci">void vmaCalculateVirtualBlockStats(VmaVirtualBlock virtualBlock, VmaStatInfo *pStatInfo)</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_stat_info_html"><div class="ttname"><a href="struct_vma_stat_info.html">VmaStatInfo</a></div><div class="ttdoc">Calculated statistics of memory usage in entire allocator.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1106</div></div>
<div class="ttc" id="astruct_vma_stat_info_html_a537741e4d5cdddc1c0ab95ec650afaff"><div class="ttname"><a href="struct_vma_stat_info.html#a537741e4d5cdddc1c0ab95ec650afaff">VmaStatInfo::allocationCount</a></div><div class="ttdeci">uint32_t allocationCount</div><div class="ttdoc">Number of VmaAllocation allocation objects allocated.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1110</div></div>
<div class="ttc" id="astruct_vma_stat_info_html_ab0c6c73837e5a70c749fbd4f6064895a"><div class="ttname"><a href="struct_vma_stat_info.html#ab0c6c73837e5a70c749fbd4f6064895a">VmaStatInfo::usedBytes</a></div><div class="ttdeci">VkDeviceSize usedBytes</div><div class="ttdoc">Total number of bytes occupied by all allocations.</div><div class="ttdef"><b>Definition:</b> vk_mem_alloc.h:1114</div></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:1111</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:1133</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:1119</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>