Statistics

This library contains several functions that return information about its internal state, especially the amount of memory allocated from Vulkan.

Numeric statistics

If you need to obtain basic statistics about memory usage per heap, together with current budget, you can call function vmaGetHeapBudgets() and inspect structure VmaBudget. This is useful to keep track of memory usage and stay withing budget (see also Staying within budget). Example:

uint32_t heapIndex = ...

VmaBudget budgets[VK_MAX_MEMORY_HEAPS];
vmaGetHeapBudgets(allocator, budgets);

printf("My heap currently has %u allocations taking %llu B,\n",
    budgets[heapIndex].statistics.allocationCount,
    budgets[heapIndex].statistics.allocationBytes);
printf("allocated out of %u Vulkan device memory blocks taking %llu B,\n",
    budgets[heapIndex].statistics.blockCount,
    budgets[heapIndex].statistics.blockBytes);
printf("Vulkan reports total usage %llu B with budget %llu B.\n",
    budgets[heapIndex].usage,
    budgets[heapIndex].budget);

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 vmaCalculateStatistics() and inspecting structure VmaTotalStatistics. This function is slower though, as it has to traverse all the internal data structures, so it should be used only for debugging purposes.

You can query for statistics of a custom pool using function vmaGetPoolStatistics() or vmaCalculatePoolStatistics().

You can query for information about a specific allocation using function vmaGetAllocationInfo(). It fill structure VmaAllocationInfo.

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) 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 vmaFreeStatsString().

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.

The JSON string contains all the data that can be obtained using vmaCalculateStatistics(). 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.