Statistics

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

Numeric statistics

If you need to obtain basic statistics about memory usage per memory segment group, together with current budget, you can call function D3D12MA::Allocator::GetBudget() and inspect structure D3D12MA::Budget. This is useful to keep track of memory usage and stay withing budget. Example:

D3D12MA::Budget localBudget;
allocator->GetBudget(&localBudget, NULL);
 
printf("My GPU memory currently has %u allocations taking %llu B,\n",
    localBudget.Statistics.AllocationCount,
    localBudget.Statistics.AllocationBytes);
printf("allocated out of %u D3D12 memory heaps taking %llu B,\n",
    localBudget.Statistics.BlockCount,
    localBudget.Statistics.BlockBytes);
printf("D3D12 reports total usage %llu B with budget %llu B.\n",
    localBudget.UsageBytes,
    localBudget.BudgetBytes);

You can query for more detailed statistics per heap type, memory segment group, and totals, including minimum and maximum allocation size and unused range size, by calling function D3D12MA::Allocator::CalculateStatistics() and inspecting structure D3D12MA::TotalStatistics. 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 D3D12MA::Pool::GetStatistics() or D3D12MA::Pool::CalculateStatistics().

You can query for information about a specific allocation using functions of the D3D12MA::Allocation class, e.g. GetSize(), GetOffset(), GetHeap().

JSON dump

You can dump internal state of the allocator to a string in JSON format using function D3D12MA::Allocator::BuildStatsString(). The result is guaranteed to be correct JSON. It uses Windows Unicode (UTF-16) encoding. Any strings provided by user (see D3D12MA::Allocation::SetName()) are copied as-is and properly escaped for JSON. It must be freed using function D3D12MA::Allocator::FreeStatsString().

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 D3D12MA::Allocator::CalculateStatistics(). 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.

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