Introduction

While using the library, sequence of calls to its functions together with their parameters can be recorded to a file and later replayed using standalone player application. It can be useful to:

Test correctness - check if same sequence of calls will not cause crash or failures on a target platform.
Gather statistics - see number of allocations, peak memory usage, number of calls etc.
Benchmark performance - see how much time it takes to replay the whole sequence.

Usage

Recording functionality is disabled by default. To enable it, define following macro before every include of this library:

#define VMA_RECORDING_ENABLED 1

To record sequence of calls to a file: Fill in VmaAllocatorCreateInfo::pRecordSettings member while creating VmaAllocator object. File is opened and written during whole lifetime of the allocator.

To replay file: Use VmaReplay - standalone command-line program. Precompiled binary can be found in "bin" directory. Its source can be found in "src/VmaReplay" directory. Its project is generated by Premake. Command line syntax is printed when the program is launched without parameters. Basic usage:

VmaReplay.exe MyRecording.csv

Documentation of file format can be found in file: "docs/Recording file format.md". It's a human-readable, text file in CSV format (Comma Separated Values).

Additional considerations

Replaying file that was recorded on a different GPU (with different parameters like bufferImageGranularity, nonCoherentAtomSize, and especially different set of memory heaps and types) may give different performance and memory usage results, as well as issue some warnings and errors.
Current implementation of recording in VMA, as well as VmaReplay application, is coded and tested only on Windows. Inclusion of recording code is driven by VMA_RECORDING_ENABLED macro. Support for other platforms should be easy to add. Contributions are welcomed.