Statistics

API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format. More...

Classes
struct	VmaStatistics
	Calculated statistics of memory usage e.g. More...
struct	VmaDetailedStatistics
	More detailed statistics than VmaStatistics. More...
struct	VmaTotalStatistics
	General statistics from current state of the Allocator - total memory usage across all memory heaps and types. More...
struct	VmaBudget
	Statistics of current memory usage and available budget for a specific memory heap. More...

Typedefs
typedef struct VmaStatistics	VmaStatistics
	Calculated statistics of memory usage e.g. More...
typedef struct VmaDetailedStatistics	VmaDetailedStatistics
	More detailed statistics than VmaStatistics. More...
typedef struct VmaTotalStatistics	VmaTotalStatistics
	General statistics from current state of the Allocator - total memory usage across all memory heaps and types. More...
typedef struct VmaBudget	VmaBudget
	Statistics of current memory usage and available budget for a specific memory heap. More...

Functions
VMA_CALL_PRE void VMA_CALL_POST	vmaCalculateStatistics (VmaAllocator VMA_NOT_NULL allocator, VmaTotalStatistics *VMA_NOT_NULL pStats)
	Retrieves statistics from current state of the Allocator. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaGetHeapBudgets (VmaAllocator VMA_NOT_NULL allocator, VmaBudget *VMA_NOT_NULL VMA_LEN_IF_NOT_NULL("VkPhysicalDeviceMemoryProperties::memoryHeapCount") pBudgets)
	Retrieves information about current memory usage and budget for all memory heaps. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaGetPoolStatistics (VmaAllocator VMA_NOT_NULL allocator, VmaPool VMA_NOT_NULL pool, VmaStatistics *VMA_NOT_NULL pPoolStats)
	Retrieves statistics of existing VmaPool object. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaCalculatePoolStatistics (VmaAllocator VMA_NOT_NULL allocator, VmaPool VMA_NOT_NULL pool, VmaDetailedStatistics *VMA_NOT_NULL pPoolStats)
	Retrieves detailed statistics of existing VmaPool object. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaBuildVirtualBlockStatsString (VmaVirtualBlock VMA_NOT_NULL virtualBlock, char *VMA_NULLABLE *VMA_NOT_NULL ppStatsString, VkBool32 detailedMap)
	Builds and returns a null-terminated string in JSON format with information about given VmaVirtualBlock. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaFreeVirtualBlockStatsString (VmaVirtualBlock VMA_NOT_NULL virtualBlock, char *VMA_NULLABLE pStatsString)
	Frees a string returned by vmaBuildVirtualBlockStatsString(). More...
VMA_CALL_PRE void VMA_CALL_POST	vmaBuildStatsString (VmaAllocator VMA_NOT_NULL allocator, char *VMA_NULLABLE *VMA_NOT_NULL ppStatsString, VkBool32 detailedMap)
	Builds and returns statistics as a null-terminated string in JSON format. More...
VMA_CALL_PRE void VMA_CALL_POST	vmaFreeStatsString (VmaAllocator VMA_NOT_NULL allocator, char *VMA_NULLABLE pStatsString)

Detailed Description

API elements that query current status of the allocator, from memory usage, budget, to full dump of the internal state in JSON format.

See documentation chapter: Statistics.

Typedef Documentation

VmaBudget

typedef struct VmaBudget VmaBudget

Statistics of current memory usage and available budget for a specific memory heap.

These are fast to calculate. See function vmaGetHeapBudgets().

VmaDetailedStatistics

typedef struct VmaDetailedStatistics VmaDetailedStatistics

More detailed statistics than VmaStatistics.

These are slower to calculate. Use for debugging purposes. See functions: vmaCalculateStatistics(), vmaCalculatePoolStatistics().

Previous version of the statistics API provided averages, but they have been removed because they can be easily calculated as:

VkDeviceSize allocationSizeAvg = detailedStats.statistics.allocationBytes / detailedStats.statistics.allocationCount;
VkDeviceSize unusedBytes = detailedStats.statistics.blockBytes - detailedStats.statistics.allocationBytes;
VkDeviceSize unusedRangeSizeAvg = unusedBytes / detailedStats.unusedRangeCount;

VmaStatistics

typedef struct VmaStatistics VmaStatistics

Calculated statistics of memory usage e.g.

in a specific memory type, heap, custom pool, or total.

These are fast to calculate. See functions: vmaGetHeapBudgets(), vmaGetPoolStatistics().

VmaTotalStatistics

typedef struct VmaTotalStatistics VmaTotalStatistics

General statistics from current state of the Allocator - total memory usage across all memory heaps and types.

These are slower to calculate. Use for debugging purposes. See function vmaCalculateStatistics().

Function Documentation

vmaBuildStatsString()

VMA_CALL_PRE void VMA_CALL_POST vmaBuildStatsString	(	VmaAllocator VMA_NOT_NULL	allocator,
		char *VMA_NULLABLE *VMA_NOT_NULL	ppStatsString,
		VkBool32	detailedMap
	)

Builds and returns statistics as a null-terminated string in JSON format.

Parameters

	allocator
[out]	ppStatsString	Must be freed using vmaFreeStatsString() function.
	detailedMap

vmaBuildVirtualBlockStatsString()

VMA_CALL_PRE void VMA_CALL_POST vmaBuildVirtualBlockStatsString	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		char *VMA_NULLABLE *VMA_NOT_NULL	ppStatsString,
		VkBool32	detailedMap
	)

Builds and returns a null-terminated string in JSON format with information about given VmaVirtualBlock.

Parameters

	virtualBlock	Virtual block.
[out]	ppStatsString	Returned string.
	detailedMap	Pass VK_FALSE to only obtain statistics as returned by vmaCalculateVirtualBlockStatistics(). Pass VK_TRUE to also obtain full list of allocations and free spaces.

Returned string must be freed using vmaFreeVirtualBlockStatsString().

vmaCalculatePoolStatistics()

VMA_CALL_PRE void VMA_CALL_POST vmaCalculatePoolStatistics	(	VmaAllocator VMA_NOT_NULL	allocator,
		VmaPool VMA_NOT_NULL	pool,
		VmaDetailedStatistics *VMA_NOT_NULL	pPoolStats
	)

Retrieves detailed statistics of existing VmaPool object.

Parameters

	allocator	Allocator object.
	pool	Pool object.
[out]	pPoolStats	Statistics of specified pool.

vmaCalculateStatistics()

VMA_CALL_PRE void VMA_CALL_POST vmaCalculateStatistics	(	VmaAllocator VMA_NOT_NULL	allocator,
		VmaTotalStatistics *VMA_NOT_NULL	pStats
	)

Retrieves statistics from current state of the Allocator.

This function is called "calculate" not "get" because it has to traverse all internal data structures, so it may be quite slow. Use it for debugging purposes. For faster but more brief statistics suitable to be called every frame or every allocation, use vmaGetHeapBudgets().

Note that when using allocator from multiple threads, returned information may immediately become outdated.

vmaFreeStatsString()

VMA_CALL_PRE void VMA_CALL_POST vmaFreeStatsString	(	VmaAllocator VMA_NOT_NULL	allocator,
		char *VMA_NULLABLE	pStatsString
	)

vmaFreeVirtualBlockStatsString()

VMA_CALL_PRE void VMA_CALL_POST vmaFreeVirtualBlockStatsString	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		char *VMA_NULLABLE	pStatsString
	)

Frees a string returned by vmaBuildVirtualBlockStatsString().

vmaGetHeapBudgets()

VMA_CALL_PRE void VMA_CALL_POST vmaGetHeapBudgets	(	VmaAllocator VMA_NOT_NULL	allocator,
		VmaBudget *VMA_NOT_NULL VMA_LEN_IF_NOT_NULL("VkPhysicalDeviceMemoryProperties::memoryHeapCount")	pBudgets
	)

Retrieves information about current memory usage and budget for all memory heaps.

Parameters

	allocator
[out]	pBudgets	Must point to array with number of elements at least equal to number of memory heaps in physical device used.

This function is called "get" not "calculate" because it is very fast, suitable to be called every frame or every allocation. For more detailed statistics use vmaCalculateStatistics().

Note that when using allocator from multiple threads, returned information may immediately become outdated.

vmaGetPoolStatistics()

VMA_CALL_PRE void VMA_CALL_POST vmaGetPoolStatistics	(	VmaAllocator VMA_NOT_NULL	allocator,
		VmaPool VMA_NOT_NULL	pool,
		VmaStatistics *VMA_NOT_NULL	pPoolStats
	)

Retrieves statistics of existing VmaPool object.

Parameters

	allocator	Allocator object.
	pool	Pool object.
[out]	pPoolStats	Statistics of specified pool.