1This is an official documentation for file format used by Vulkan Memory Allocator library 2to record and replay sequence of calls to its functions. 3This feature can be enabled by using `VmaAllocatorCreateInfo::pRecordSettings` structure members. 4For details, see main documentation of the library. 5Playback can be launched using **VmaReplay** console application. 6 7Recording is a text file. 8Line endings: Unix `'\n'`. 9Character encoding: single-byte (can be ASCII or UTF-8, whaterver you use in custom strings). 10Suggested file extension: **csv**. File can be processed sequentially - no random access is needed. 11Each line forms a separate entry. 12Each line consists of a set of values (also called columns), separated by comma `','` (hence "CSV" format - Comma Separated Values). 13Number of columns is different in different lines. 14 15# Header 16 17First line identifies file format. It must always be: 18 19 Vulkan Memory Allocator,Calls recording 20 21Second line identifies format version, where first column is major version and second column is minor version. 22Formats with only minor version incremented are backward compatible. 23VmaReplay application supports all older versions. 24Current version is: 25 26 1,8 27 28# Configuration 29 30Header is followed by mandatory configuration section (min format version 1.3). It starts with line: 31 32 Config,Begin 33 34And ends with line: 35 36 Config,End 37 38Between them there can be zero or more lines with configuration options. They store values of various variables from the current environment from the time of recording, like properties and limits of Vulkan physical device, available memory heaps and types, enabled Vulkan extensions, as well macros that configure VMA internals. Supported configuration options are: 39 40 VulkanApiVersion,<uint32>,<uint32> 41 42 PhysicalDevice,apiVersion,<uint32> 43 PhysicalDevice,driverVersion,<uint32> 44 PhysicalDevice,vendorID,<uint32> 45 PhysicalDevice,deviceID,<uint32> 46 PhysicalDevice,deviceType,<uint32> 47 PhysicalDevice,deviceName,<string> 48 49 PhysicalDeviceLimits,maxMemoryAllocationCount,<uint32> 50 PhysicalDeviceLimits,bufferImageGranularity,<uint64> 51 PhysicalDeviceLimits,nonCoherentAtomSize,<uint64> 52 53 PhysicalDeviceMemory,HeapCount,<uint32> 54 PhysicalDeviceMemory,Heap,<index:uint32>,size,<uint64> 55 PhysicalDeviceMemory,Heap,<index:uint32>,flags,<uint32> 56 PhysicalDeviceMemory,TypeCount,<uint32> 57 PhysicalDeviceMemory,Type,<index:uint32>,heapIndex,<uint32> 58 PhysicalDeviceMemory,Type,<index:uint32>,propertyFlags,<uint32> 59 60 Extension,VK_KHR_dedicated_allocation,<bool> 61 Extension,VK_KHR_bind_memory2,<bool> 62 Extension,VK_EXT_memory_budget,<bool> 63 Extension,VK_AMD_device_coherent_memory,<bool> 64 65 Macro,VMA_DEBUG_ALWAYS_DEDICATED_MEMORY,<bool> 66 Macro,VMA_DEBUG_ALIGNMENT,<uint64> 67 Macro,VMA_DEBUG_MARGIN,<uint64> 68 Macro,VMA_DEBUG_INITIALIZE_ALLOCATIONS,<bool> 69 Macro,VMA_DEBUG_DETECT_CORRUPTION,<bool> 70 Macro,VMA_DEBUG_GLOBAL_MUTEX,<bool> 71 Macro,VMA_DEBUG_MIN_BUFFER_IMAGE_GRANULARITY,<uint64> 72 Macro,VMA_SMALL_HEAP_MAX_SIZE,<uint64> 73 Macro,VMA_DEFAULT_LARGE_HEAP_BLOCK_SIZE,<uint64> 74 75# Function calls 76 77Remaining lines contain recorded calls to VMA functions. First columns are always: 78 79- Thread ID : uint32 80- Time since first call : float, in seconds 81- VMA frame index : uint32 82- Function name : string 83 84Remaining columns are function parameters and output, depending on function name, which can be: 85 86**vmaCreateAllocator, vmaDestroyAllocator** 87 88No parameters. 89 90**vmaCreatePool** 91 92- memoryTypeIndex : uint32 93- flags : uint32 94- blockSize : uint64 95- minBlockCount : uint64 96- maxBlockCount : uint64 97- frameInUseCount : uint32 98- pool (output) : pointer 99 100**vmaDestroyPool** 101 102- pool : pointer 103 104**vmaSetAllocationUserData** 105 106- allocation : pointer 107- pUserData : string (may contain additional commas) 108 109**vmaCreateBuffer** 110 111- bufferCreateInfo.flags : uint32 112- bufferCreateInfo.size : uint64 113- bufferCreateInfo.usage : uint32 114- bufferCreateInfo.sharingMode : uint32 115- allocationCreateInfo.flags : uint32 116- allocationCreateInfo.usage : uint32 117- allocationCreateInfo.requiredFlags : uint32 118- allocationCreateInfo.preferredFlags : uint32 119- allocationCreateInfo.memoryTypeBits : uint32 120- allocationCreateInfo.pool : pointer 121- allocation (output) : pointer 122- allocationCreateInfo.pUserData : string (may contain additional commas) 123 124**vmaDestroyBuffer** 125 126- allocation : pointer 127 128**vmaCreateImage** 129 130- imageCreateInfo.flags : uint32 131- imageCreateInfo.imageType : uint32 132- imageCreateInfo.format : uint32 133- imageCreateInfo.extent.width : uint32 134- imageCreateInfo.extent.height : uint32 135- imageCreateInfo.extent.depth : uint32 136- imageCreateInfo.mipLevels : uint32 137- imageCreateInfo.arrayLayers : uint32 138- imageCreateInfo.samples : uint32 139- imageCreateInfo.tiling : uint32 140- imageCreateInfo.usage : uint32 141- imageCreateInfo.sharingMode : uint32 142- imageCreateInfo.initialLayout : uint32 143- allocationCreateInfo.flags : uint32 144- allocationCreateInfo.usage : uint32 145- allocationCreateInfo.requiredFlags : uint32 146- allocationCreateInfo.preferredFlags : uint32 147- allocationCreateInfo.memoryTypeBits : uint32 148- allocationCreateInfo.pool : pointer 149- allocation (output) : pointer 150- allocationCreateInfo.pUserData : string (may contain additional commas) 151 152**vmaDestroyImage** 153 154- allocation : pointer 155 156**vmaFreeMemory** (min format version 1.1) 157 158- allocation : pointer 159 160**vmaFreeMemoryPages** (min format version: 1.5) 161 162- allocations : list of pointers 163 164**vmaCreateLostAllocation** (min format version 1.2) 165 166- allocation (output) : pointer 167 168**vmaAllocateMemory** (min format version 1.2) 169 170- vkMemoryRequirements.size : uint64 171- vkMemoryRequirements.alignment : uint64 172- vkMemoryRequirements.memoryTypeBits : uint32 173- allocationCreateInfo.flags : uint32 174- allocationCreateInfo.usage : uint32 175- allocationCreateInfo.requiredFlags : uint32 176- allocationCreateInfo.preferredFlags : uint32 177- allocationCreateInfo.memoryTypeBits : uint32 178- allocationCreateInfo.pool : pointer 179- allocation (output) : pointer 180- allocationCreateInfo.pUserData : string (may contain additional commas) 181 182**vmaAllocateMemoryPages** (min format version 1.5) 183 184- vkMemoryRequirements.size : uint64 185- vkMemoryRequirements.alignment : uint64 186- vkMemoryRequirements.memoryTypeBits : uint32 187- allocationCreateInfo.flags : uint32 188- allocationCreateInfo.usage : uint32 189- allocationCreateInfo.requiredFlags : uint32 190- allocationCreateInfo.preferredFlags : uint32 191- allocationCreateInfo.memoryTypeBits : uint32 192- allocationCreateInfo.pool : pointer 193- allocations (output) : list of pointers 194- allocationCreateInfo.pUserData : string (may contain additional commas) 195 196**vmaAllocateMemoryForBuffer, vmaAllocateMemoryForImage** (min format version 1.2) 197 198- vkMemoryRequirements.size : uint64 199- vkMemoryRequirements.alignment : uint64 200- vkMemoryRequirements.memoryTypeBits : uint32 201- requiresDedicatedAllocation : bool 202- prefersDedicatedAllocation : bool 203- allocationCreateInfo.flags : uint32 204- allocationCreateInfo.usage : uint32 205- allocationCreateInfo.requiredFlags : uint32 206- allocationCreateInfo.preferredFlags : uint32 207- allocationCreateInfo.memoryTypeBits : uint32 208- allocationCreateInfo.pool : pointer 209- allocation (output) : pointer 210- allocationCreateInfo.pUserData : string (may contain additional commas) 211 212**vmaMapMemory, vmaUnmapMemory** (min format version 1.2) 213 214- allocation : pointer 215 216**vmaFlushAllocation, vmaInvalidateAllocation** (min format version 1.2) 217 218- allocation : pointer 219- offset : uint64 220- size : uint64 221 222**vmaTouchAllocation, vmaGetAllocationInfo** (min format version 1.2) 223 224- allocation : pointer 225 226**vmaMakePoolAllocationsLost** (min format version: 1.2) 227 228- pool : pointer 229 230**vmaResizeAllocation** (min format version: 1.4, max format version: 1.5) 231 232- allocation : pointer 233- newSize : uint64 234 235**vmaDefragmentationBegin** (min format version: 1.5) 236 237- defragmentationInfo2.flags : uint32 238- defragmentationInfo2.pAllocations : list of pointers 239- defragmentationInfo2.pPools : list of pointers 240- defragmentationInfo2.maxCpuBytesToMove : uint64 241- defragmentationInfo2.maxCpuAllocationsToMove : uint32 242- defragmentationInfo2.maxGpuBytesToMove : uint64 243- defragmentationInfo2.maxGpuAllocationsToMove : uint32 244- defragmentationInfo2.commandBuffer : pointer 245- context (output) : pointer 246 247**vmaDefragmentationEnd** (min format version: 1.5) 248 249- context : pointer 250 251**vmaSetPoolName** (min format version: 1.7) 252 253- pool : pointer 254- pName : string (may contain additional commas) 255 256# Data types 257 258**bool** 259 260Encoded as `0` for false or `1` for true. 261 262**uint32, uint64** 263 264Encoded in decimal format. 265 266**pointer** 267 268Encoded in hexadecimal format. 269 270**pUserData** 271 272If `pUserData` was a pointer, it is encoded as hexadecimal string. 273If `VMA_ALLOCATION_CREATE_USER_DATA_COPY_STRING_BIT` was used with the allocation, the string is written as-is. 274It may contain additional commas. 275It should not contain end-of-line characters - results are then undefined. 276 277**list of (...)** (min format version: 1.5) 278 279An ordered sequence of values of some type, separated by single space. 280 281# Example file 282 283 Vulkan Memory Allocator,Calls recording 284 1,8 285 Config,Begin 286 VulkanApiVersion,1,1 287 PhysicalDevice,apiVersion,4198477 288 PhysicalDevice,driverVersion,8388653 289 PhysicalDevice,vendorID,4098 290 PhysicalDevice,deviceID,26751 291 PhysicalDevice,deviceType,2 292 PhysicalDevice,deviceName,Radeon RX Vega 293 PhysicalDeviceLimits,maxMemoryAllocationCount,4096 294 PhysicalDeviceLimits,bufferImageGranularity,1 295 PhysicalDeviceLimits,nonCoherentAtomSize,128 296 PhysicalDeviceMemory,HeapCount,3 297 PhysicalDeviceMemory,Heap,0,size,8304721920 298 PhysicalDeviceMemory,Heap,0,flags,3 299 PhysicalDeviceMemory,Heap,1,size,8286175232 300 PhysicalDeviceMemory,Heap,1,flags,0 301 PhysicalDeviceMemory,Heap,2,size,268435456 302 PhysicalDeviceMemory,Heap,2,flags,3 303 PhysicalDeviceMemory,TypeCount,4 304 PhysicalDeviceMemory,Type,0,heapIndex,0 305 PhysicalDeviceMemory,Type,0,propertyFlags,1 306 PhysicalDeviceMemory,Type,1,heapIndex,1 307 PhysicalDeviceMemory,Type,1,propertyFlags,6 308 PhysicalDeviceMemory,Type,2,heapIndex,2 309 PhysicalDeviceMemory,Type,2,propertyFlags,7 310 PhysicalDeviceMemory,Type,3,heapIndex,1 311 PhysicalDeviceMemory,Type,3,propertyFlags,14 312 Extension,VK_KHR_dedicated_allocation,1 313 Extension,VK_KHR_bind_memory2,1 314 Extension,VK_EXT_memory_budget,1 315 Macro,VMA_DEBUG_ALWAYS_DEDICATED_MEMORY,0 316 Macro,VMA_DEBUG_ALIGNMENT,1 317 Macro,VMA_DEBUG_MARGIN,0 318 Macro,VMA_DEBUG_INITIALIZE_ALLOCATIONS,0 319 Macro,VMA_DEBUG_DETECT_CORRUPTION,0 320 Macro,VMA_DEBUG_GLOBAL_MUTEX,0 321 Macro,VMA_DEBUG_MIN_BUFFER_IMAGE_GRANULARITY,1 322 Macro,VMA_SMALL_HEAP_MAX_SIZE,1073741824 323 Macro,VMA_DEFAULT_LARGE_HEAP_BLOCK_SIZE,268435456 324 Config,End 325 12552,0.000,0,vmaCreateAllocator 326 12552,0.010,0,vmaCreateImage,0,1,37,128,128,1,1,1,1,1,1,0,8,36,2,0,0,0,0000000000000000,000001D85B8B1A80, 327 12552,0.010,0,vmaSetAllocationUserData,000001D85B8B1A80,Ala ma kota 328 12552,0.015,0,vmaCreateImage,0,1,37,128,128,1,1,1,1,0,6,0,0,0,1,0,0,0,0000000000000000,000001D85B8B1620, 329 12552,0.017,0,vmaDestroyImage,000001D85B8B1A80 330 12552,0.017,0,vmaCreateBuffer,0,768,1,0,4,2,0,0,0,0000000000000000,000001D85B8B19E0, 331 12552,0.017,0,vmaCreateBuffer,0,768,130,0,0,1,0,0,0,0000000000000000,000001D85B8B1A80, 332 12552,0.017,0,vmaCreateBuffer,0,60,1,0,4,2,0,0,0,0000000000000000,000001D85B8B1DA0, 333 12552,0.017,0,vmaCreateBuffer,0,60,66,0,0,1,0,0,0,0000000000000000,000001D85B8B16C0, 334 12552,0.017,0,vmaDestroyBuffer,000001D85B8B1DA0 335 12552,0.017,0,vmaDestroyBuffer,000001D85B8B19E0 336 12552,0.022,0,vmaCreateImage,0,1,126,1424,704,1,1,1,1,0,32,0,0,0,1,0,0,0,0000000000000000,000001D85B8B1EE0, 337 12552,0.048,0,vmaDestroyImage,000001D85B8B1EE0 338 12552,0.053,0,vmaCreateImage,0,1,126,1424,704,1,1,1,1,0,32,0,0,0,1,0,0,0,0000000000000000,000001D85B8B1EE0, 339 12552,0.662,0,vmaDestroyImage,000001D85B8B1EE0 340 12552,0.695,0,vmaDestroyImage,000001D85B8B1620 341 12552,0.695,0,vmaDestroyBuffer,000001D85B8B16C0 342 12552,0.695,0,vmaDestroyBuffer,000001D85B8B1A80 343 12552,0.695,0,vmaDestroyAllocator 344