eden-emu/VulkanMemoryAllocator
15
0
Fork 0
mirror of https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator.git synced 2025-06-05 23:10:47 +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

26
docs/html/statistics.html
View file

@ -69,17 +69,33 @@ $(function() {
<div class="headertitle"><div class="title">Statistics </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p >This library contains functions that return information about its internal state, especially the amount of memory allocated from Vulkan. Please keep in mind that these functions need to traverse all internal data structures to gather these information, so they may be quite time-consuming. Don't call them too often.</p>
<div class="textblock"><p >This library contains several functions that return information about its internal state, especially the amount of memory allocated from Vulkan.</p>
<h1><a class="anchor" id="statistics_numeric_statistics"></a>
Numeric statistics</h1>
<p >You can query for overall statistics of the allocator using function <a class="el" href="group__group__stats.html#ga333b61c1788cb23559177531e6a93ca3" title="Retrieves statistics from current state of the Allocator.">vmaCalculateStats()</a>. Information are returned using structure <a class="el" href="struct_vma_stats.html" title="General statistics from current state of Allocator.">VmaStats</a>. It contains <a class="el" href="struct_vma_stat_info.html" title="Calculated statistics of memory usage in entire allocator.">VmaStatInfo</a> - number of allocated blocks, number of allocations (occupied ranges in these blocks), number of unused (free) ranges in these blocks, number of bytes used and unused (but still allocated from Vulkan) and other information. They are summed across memory heaps, memory types and total for whole allocator.</p>
<p >You can query for statistics of a custom pool using function <a class="el" href="group__group__stats.html#gae8bf76997b234ef68aad922616df4153" title="Retrieves statistics of existing VmaPool object.">vmaGetPoolStats()</a>. Information are returned using structure <a class="el" href="struct_vma_pool_stats.html" title="Describes parameter of existing VmaPool.">VmaPoolStats</a>.</p>
<p >You can query for information about specific allocation using function <a class="el" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a>. It fill structure <a class="el" href="struct_vma_allocation_info.html" title="Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().">VmaAllocationInfo</a>.</p>
<p >If you need to obtain basic statistics about memory usage per heap, together with current budget, you can call function <a class="el" href="group__group__stats.html#ga9f88db9d46a432c0ad7278cecbc5eaa7" title="Retrieves information about current memory usage and budget for all memory heaps.">vmaGetHeapBudgets()</a> and inspect structure <a class="el" href="struct_vma_budget.html" title="Statistics of current memory usage and available budget for a specific memory heap.">VmaBudget</a>. This is useful to keep track of memory usage and stay withing budget (see also <a class="el" href="staying_within_budget.html">Staying within budget</a>). Example:</p>
<div class="fragment"><div class="line">uint32_t heapIndex = ...</div>
<div class="line"> </div>
<div class="line">VmaBudget budgets[VK_MAX_MEMORY_HEAPS];</div>
<div class="line"><a class="code hl_function" href="group__group__stats.html#ga9f88db9d46a432c0ad7278cecbc5eaa7">vmaGetHeapBudgets</a>(allocator, budgets);</div>
<div class="line"> </div>
<div class="line">printf(<span class="stringliteral">&quot;My heap currently has %u allocations taking %llu B,\n&quot;</span>,</div>
<div class="line"> budgets[heapIndex].statistics.allocationCount,</div>
<div class="line"> budgets[heapIndex].statistics.allocationBytes);</div>
<div class="line">printf(<span class="stringliteral">&quot;allocated out of %u Vulkan device memory blocks taking %llu B,\n&quot;</span>,</div>
<div class="line"> budgets[heapIndex].statistics.blockCount,</div>
<div class="line"> budgets[heapIndex].statistics.blockBytes);</div>
<div class="line">printf(<span class="stringliteral">&quot;Vulkan reports total usage %llu B with budget %llu B.\n&quot;</span>,</div>
<div class="line"> budgets[heapIndex].usage,</div>
<div class="line"> budgets[heapIndex].budget);</div>
<div class="ttc" id="agroup__group__stats_html_ga9f88db9d46a432c0ad7278cecbc5eaa7"><div class="ttname"><a href="group__group__stats.html#ga9f88db9d46a432c0ad7278cecbc5eaa7">vmaGetHeapBudgets</a></div><div class="ttdeci">void vmaGetHeapBudgets(VmaAllocator allocator, VmaBudget *pBudgets)</div><div class="ttdoc">Retrieves information about current memory usage and budget for all memory heaps.</div></div>
</div><!-- fragment --><p >You can query for more detailed statistics per memory heap, type, and totals, including minimum and maximum allocation size and unused range size, by calling function <a class="el" href="group__group__stats.html#ga36f3484de7aa6cd6edc4de9edfa0ff59" title="Retrieves statistics from current state of the Allocator.">vmaCalculateStatistics()</a> and inspecting structure <a class="el" href="struct_vma_total_statistics.html" title="General statistics from current state of the Allocator - total memory usage across all memory heaps a...">VmaTotalStatistics</a>. This function is slower though, as it has to traverse all the internal data structures, so it should be used only for debugging purposes.</p>
<p >You can query for statistics of a custom pool using function <a class="el" href="group__group__stats.html#ga34d8e7d83774eed0caee5c5ae88e217d" title="Retrieves statistics of existing VmaPool object.">vmaGetPoolStatistics()</a> or <a class="el" href="group__group__stats.html#ga50ba0eb25d2b363b792be4645ca7a380" title="Retrieves detailed statistics of existing VmaPool object.">vmaCalculatePoolStatistics()</a>.</p>
<p >You can query for information about a specific allocation using function <a class="el" href="group__group__alloc.html#ga86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation.">vmaGetAllocationInfo()</a>. It fill structure <a class="el" href="struct_vma_allocation_info.html" title="Parameters of VmaAllocation objects, that can be retrieved using function vmaGetAllocationInfo().">VmaAllocationInfo</a>.</p>
<h1><a class="anchor" id="statistics_json_dump"></a>
JSON dump</h1>
<p >You can dump internal state of the allocator to a string in JSON format using function <a class="el" href="group__group__stats.html#gaa4fee7eb5253377599ef4fd38c93c2a0" title="Builds and returns statistics as a null-terminated string in JSON format.">vmaBuildStatsString()</a>. The result is guaranteed to be correct JSON. It uses ANSI encoding. Any strings provided by user (see <a class="el" href="allocation_annotation.html#allocation_names">Allocation names</a>) are copied as-is and properly escaped for JSON, so if they use UTF-8, ISO-8859-2 or any other encoding, this JSON string can be treated as using this encoding. It must be freed using function <a class="el" href="group__group__stats.html#ga3104eb30d8122c84dd8541063f145288">vmaFreeStatsString()</a>.</p>
<p >The format of this JSON string is not part of official documentation of the library, but it will not change in backward-incompatible way without increasing library major version number and appropriate mention in changelog.</p>
<p >The JSON string contains all the data that can be obtained using <a class="el" href="group__group__stats.html#ga333b61c1788cb23559177531e6a93ca3" title="Retrieves statistics from current state of the Allocator.">vmaCalculateStats()</a>. It can also contain detailed map of allocated memory blocks and their regions - free and occupied by allocations. This allows e.g. to visualize the memory or assess fragmentation. </p>
<p >The JSON string contains all the data that can be obtained using <a class="el" href="group__group__stats.html#ga36f3484de7aa6cd6edc4de9edfa0ff59" title="Retrieves statistics from current state of the Allocator.">vmaCalculateStatistics()</a>. It can also contain detailed map of allocated memory blocks and their regions - free and occupied by allocations. This allows e.g. to visualize the memory or assess fragmentation. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->