Documentation: Written "Statistics" chapter.

Author: adam-sawicki-a

docs/html/index.html

@@ -96,6 +96,11 @@ <h1><a class="anchor" id="main_table_of_contents"></a>
 </li>
 <li><a class="el" href="defragmentation.html">Defragmentation</a></li>
 <li><a class="el" href="lost_allocations.html">Lost allocations</a></li>
+<li><a class="el" href="statistics.html">Statistics</a><ul>
+<li><a class="el" href="statistics.html#statistics_numeric_statistics">Numeric statistics</a></li>
+<li><a class="el" href="statistics.html#statistics_json_dump">JSON dump</a></li>
+</ul>
+</li>
 <li><a class="el" href="allocation_annotation.html">Allocation names and user data</a><ul>
 <li><a class="el" href="allocation_annotation.html#allocation_user_data">Allocation user data</a></li>
 <li><a class="el" href="allocation_annotation.html#allocation_names">Allocation names</a></li>

docs/html/pages.html

@@ -64,7 +64,6 @@
 <div class="contents">
 <div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
 <table class="directory">
-<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="statistics.html" target="_self">Statistics</a></td><td class="desc"></td></tr>
 </table>
 </div><!-- directory -->
 </div><!-- contents -->

docs/html/search/all_c.js

@@ -1,5 +1,5 @@
 var searchData=
 [
   ['size',['size',['../struct_vma_pool_stats.html#a326807b2de2b0931cee4ed9a5f2e420c',1,'VmaPoolStats::size()'],['../struct_vma_allocation_info.html#aac76d113a6a5ccbb09fea00fb25fd18f',1,'VmaAllocationInfo::size()']]],
-  ['statistics',['Statistics',['../statistics.html',1,'']]]
+  ['statistics',['Statistics',['../statistics.html',1,'index']]]
 ];

docs/html/search/pages_7.js

@@ -1,4 +1,4 @@
 var searchData=
 [
-  ['statistics',['Statistics',['../statistics.html',1,'']]]
+  ['statistics',['Statistics',['../statistics.html',1,'index']]]
 ];

docs/html/statistics.html

@@ -56,13 +56,28 @@
 </iframe>
 </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 class="header">
   <div class="headertitle">
 <div class="title">Statistics </div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"></div></div><!-- 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>
+<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="vk__mem__alloc_8h.html#a333b61c1788cb23559177531e6a93ca3" 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="vk__mem__alloc_8h.html#ae8bf76997b234ef68aad922616df4153" 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="vk__mem__alloc_8h.html#a86dd08aba8633bfa4ad0df2e76481d8b" title="Returns current information about specified allocation and atomically marks it as used in current fra...">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="vk__mem__alloc_8h.html#aa4fee7eb5253377599ef4fd38c93c2a0" title="Builds and returns statistics as 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 treted as using this encoding. It must be freed using function <a class="el" href="vk__mem__alloc_8h.html#a3104eb30d8122c84dd8541063f145288">vmaFreeStatsString()</a>.</p>
+<p>The format of this 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 mention in changelog.</p>
+<p>The string contains all the data that can be obtained using <a class="el" href="vk__mem__alloc_8h.html#a333b61c1788cb23559177531e6a93ca3" 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>
+</div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
 Generated by &#160;<a href="http://www.doxygen.org/index.html">

docs/html/vk__mem__alloc_8h_source.html

@@ -57,6 +57,9 @@ Documentation of all members: vk_mem_alloc.h
     - [Choosing memory type index](@ref custom_memory_pools_MemTypeIndex)
   - \subpage defragmentation
   - \subpage lost_allocations
+  - \subpage statistics
+    - [Numeric statistics](@ref statistics_numeric_statistics)
+    - [JSON dump](@ref statistics_json_dump)
   - \subpage allocation_annotation
     - [Allocation user data](@ref allocation_user_data)
     - [Allocation names](@ref allocation_names)
@@ -673,7 +676,45 @@ allocations (like in the example above) and don't use them.
 
 \page statistics Statistics
 
-
+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.
+
+\section statistics_numeric_statistics Numeric statistics
+
+You can query for overall statistics of the allocator using function vmaCalculateStats().
+Information are returned using structure #VmaStats.
+It contains #VmaStatInfo - 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.
+
+You can query for statistics of a custom pool using function vmaGetPoolStats().
+Information are returned using structure #VmaPoolStats.
+
+You can query for information about specific allocation using function vmaGetAllocationInfo().
+It fill structure #VmaAllocationInfo.
+
+\section statistics_json_dump JSON dump
+
+You can dump internal state of the allocator to a string in JSON format using function vmaBuildStatsString().
+The result is guaranteed to be correct JSON.
+It uses ANSI encoding.
+Any strings provided by user (see [Allocation names](@ref allocation_names))
+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 treted as using this encoding.
+It must be freed using function vmaFreeStatsString().
+
+The format of this 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 mention in changelog.
+
+The string contains all the data that can be obtained using vmaCalculateStats().
+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.
 
 
 \page allocation_annotation Allocation names and user data