Introduction

We released Vulkan Memory Allocator 1.0 (VMA) back in July last year, but we’ve been remiss in posting about the progress of the library as it marched onwards, despite hitting a decent marker of maturity with the 2.0 release back in March this year. Let’s correct that with the release of 2.1 today.

Since extracting the library from a game he was working on to make it generally useful by any Vulkan® client application, Adam Sawicki, VMA’s chief engineer, has been mostly feedback-driven in the road to 2.0 and beyond. Real games and applications using the library have shaped the features and evolution of the code, and feedback from the community that’s using it leads us to believe it’s now integrated into a majority of in-development Vulkan-based games and apps on PC today.

For example, the EA SEED team’s Halcyon engine that they’ve developed for their future-looking research. Halcyon powers the Project PICA PICA demo that SEED released in March to show off their work with DirectX ray-tracing, but also supports Vulkan as a traditional rendering API, using VMA internally to manage memory. In fact, SEED were one of the earliest adopters of the library back when we released 1.0 and have used it ever since, giving us great feedback along the way. Thanks, Graham!

In a similar vein, Confetti Interactive use it in their Forge open source cross-platform rendering engine, and were possibly the first ever user of the library outside of AMD in a production Vulkan environment, integrating it even before we formally released 1.0!

Last but not least by any means, the Google team working on Filament, a modern engine primarily aimed at Android games but which is also cross-platform, also integrated VMA into their rendering system. Vulkan’s maturity on Android has helped it push into mobile-focused engines. Exposure to the underlying platform architecture of today’s mobile devices — where it’s quite different to common PC systems and especially where the memory subsystem is concerned — has helped make VMA more robust and helped it consider how more types of games and applications consume and manage their Vulkan memory.

There’s also been a natural evolution in the new features of the library as it has matured. More optimal allocation strategies, support for defragmentation, and more developer-focused profiling and debugging support is all there now. The future also looks bright: we internally sponsor VMA as an active research project for Adam and other engineers to work on it, dedicating time to experimentation inside the library to make sure it stays great.

We want to continue to make it useful in the future, as games and their use of Vulkan — and the Vulkan API itself! — matures.

Vulkan Memory Allocator 2.1

The 2.1 release has no breaking API changes compared to 2.0, so it should be a straightforward update if you’re already using 2.0 in your project. The JSON-based dump file format did change however, so if you’re consuming that in any of your own tooling then consult the documentation to see what’s new. The supplied VmaDumpVis visualiser has already been updated to take the changes into account.

New allocation strategy

2.1 now supports linear allocations, whereby VMA will never try and use freed regions and will always alloc at the start of the region’s nominal free space. That makes it cheaper to allocate since the allocator always knows where to place the next allocation, and cuts down on the size of the metadata stored to keep track of them. Because of the way frees are processed with a linear allocator, it’s also possible to treat linearly-allocated pools in specific optimised ways that might better map how your game treats Vulkan memory.

The documentation has a number of examples for that, showing you how to use the allocator to construct a stack, double stack, and a ring buffer, so be sure and check it out. If you make use of the new linear allocator then send us feedback and let us know (and tell us how if you can!), so we can see how it’s being used and continue to optimise it, or think about other allocation strategies that might make sense for your use case.

Memory usage debugging

VMA has a memory debugging system that helps you discover and fix instances of incorrect memory usage in your app. Controlled by a few simple macros, the system lets you track down issues with a number of strategies. The first is to ask VMA to wrap new allocations, and destruction of those allocations, with specific bit patterns. By looking out for the bit pattern values you can help track down memory reads that you didn’t initialise properly, or reads from memory that you already freed.

VMA can also pad new allocations with a specific margin. Technically margin padding was introduced in 2.0, but the feature was expanded for 2.1 and is worth talking about in general. The idea behind padded allocations is that if you enable them (you can control the padding size with the macro) and a memory-related bug you’re experiencing goes away, that’s probably because the padding is now catching writes you’re erroneously making outside of an allocation boundary. Beware that padding will cause memory usage to increase, so make sure to disable it after it helps you fix a bug.

That feature can also be combined with corruption detection. Enabling that will have VMA check if the padded area is set to a specific canary value. At destroy time, VMA will check the padded area for the canary value and if it finds anything other than that it’ll let you know; that means you definitely wrote something into the padding region that you shouldn’t have.

There’s a new API function — vmaCheck[Pool]Corruption() — to call to request a check outside of when allocations are destroyed, too. Make sure and check the documentation for the nuance in the memory debugging features; certain features are only supported for certain memory types, or have specific usage restrictions.

Trace and replay

VMA now supports trace and replay functionality. The precompiled binary is Windows only just now, but full source is provided if you want to bring that to another target platform. All library calls are recorded, and a playback binary is provided to replay the trace, helping you to gather stats and benchmarks on your memory usage, and check that memory usage on another platform is bug and crash free on the player’s target platform, helping with porting from one platform to another.

Beware of capture and playback differences on different GPUs if you’re making use of that feature, and check the documentation for usage guidelines and extra information about how to enable it. The trace file format is also fully documented (and simple for machines and humans to consume too!).

More information

As mentioned, the Vulkan Memory Allocator is a community-driven library; we add, fix and optimise things based on how you use it and what you want to see next. So if there’s anything you’d like to see next, a bug you need fixed, or a specific use case that you’d like to see optimised, please file an issue over on GitHub. Adam follows up on all received feedback and issues quickly, so don’t be shy in letting him know if there’s something you need.