Vulkan Memory Allocator: Statistics

Vulkan Memory Allocator

Classes | Typedefs | Functions
Statistics

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. More...

## Classes
struct | VmaStatistics
| Calculated statistics of memory usage e.g. in a specific memory type, heap, custom pool, or total. 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. in a specific memory type, heap, custom pool, or total. 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
void | vmaCalculateStatistics (VmaAllocator allocator, VmaTotalStatistics *pStats)
| Retrieves statistics from current state of the Allocator. More...
void | vmaGetHeapBudgets (VmaAllocator allocator, VmaBudget *pBudgets)
| Retrieves information about current memory usage and budget for all memory heaps. More...
void | vmaGetPoolStatistics (VmaAllocator allocator, VmaPool pool, VmaStatistics *pPoolStats)
| Retrieves statistics of existing VmaPool object. More...
void | vmaCalculatePoolStatistics (VmaAllocator allocator, VmaPool pool, VmaDetailedStatistics *pPoolStats)
| Retrieves detailed statistics of existing VmaPool object. More...
void | vmaBuildVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char **ppStatsString, VkBool32 detailedMap)
| Builds and returns a null-terminated string in JSON format with information about given VmaVirtualBlock. More...
void | vmaFreeVirtualBlockStatsString (VmaVirtualBlock virtualBlock, char *pStatsString)
| Frees a string returned by vmaBuildVirtualBlockStatsString(). More...
void | vmaBuildStatsString (VmaAllocator allocator, char **ppStatsString, VkBool32 detailedMap)
| Builds and returns statistics as a null-terminated string in JSON format. More...
void | vmaFreeStatsString (VmaAllocator allocator, char *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()

void vmaBuildStatsString | ( | VmaAllocator | allocator,
|  | char ** | 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()

void vmaBuildVirtualBlockStatsString | ( | VmaVirtualBlock | virtualBlock,
|  | char ** | 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()

void vmaCalculatePoolStatistics | ( | VmaAllocator | allocator,
|  | VmaPool | pool,
|  | VmaDetailedStatistics * | pPoolStats
| ) |  |

Retrieves detailed statistics of existing VmaPool object.

Parameters

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

## ◆ vmaCalculateStatistics()

void vmaCalculateStatistics | ( | VmaAllocator | allocator,
|  | VmaTotalStatistics * | 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()

void vmaFreeStatsString | ( | VmaAllocator | allocator,
|  | char * | pStatsString
| ) |  |

## ◆ vmaFreeVirtualBlockStatsString()

void vmaFreeVirtualBlockStatsString | ( | VmaVirtualBlock | virtualBlock,
|  | char * | pStatsString
| ) |  |

Frees a string returned by vmaBuildVirtualBlockStatsString().

## ◆ vmaGetHeapBudgets()

void vmaGetHeapBudgets | ( | VmaAllocator | allocator,
|  | VmaBudget * | 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()

void vmaGetPoolStatistics | ( | VmaAllocator | allocator,
|  | VmaPool | pool,
|  | VmaStatistics * | pPoolStats
| ) |  |

Retrieves statistics of existing VmaPool object.

Parameters

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