Virtual allocator

As an extra feature, the core allocation algorithm of the library is exposed through a simple and convenient API of "virtual allocator". It doesn't allocate any real GPU memory. It just keeps track of used and free regions of a "virtual block". You can use it to allocate your own memory or other objects, even completely unrelated to D3D12. A common use case is sub-allocation of pieces of one large GPU buffer.

Creating virtual block

To use this functionality, there is no main "allocator" object. You don't need to have D3D12MA::Allocator object created. All you need to do is to create a separate D3D12MA::VirtualBlock object for each block of memory you want to be managed by the allocator:

1. Fill in D3D12MA::ALLOCATOR_DESC structure.
2. Call D3D12MA::CreateVirtualBlock. Get new D3D12MA::VirtualBlock object.

Example:

D3D12MA::VIRTUAL_BLOCK_DESC blockDesc = {};
blockDesc.Size = 1048576; // 1 MB
 
D3D12MA::VirtualBlock *block;
HRESULT hr = CreateVirtualBlock(&blockDesc, &block);

Making virtual allocations

D3D12MA::VirtualBlock object contains internal data structure that keeps track of free and occupied regions using the same code as the main D3D12 memory allocator. A single allocation is identified by a lightweight structure D3D12MA::VirtualAllocation. You will also likely want to know the offset at which the allocation was made in the block.

In order to make an allocation:

1. Fill in D3D12MA::VIRTUAL_ALLOCATION_DESC structure.
2. Call D3D12MA::VirtualBlock::Allocate. Get new D3D12MA::VirtualAllocation value that identifies the allocation.

Example:

D3D12MA::VIRTUAL_ALLOCATION_DESC allocDesc = {};
allocDesc.Size = 4096; // 4 KB
 
D3D12MA::VirtualAllocation alloc;
UINT64 allocOffset;
hr = block->Allocate(&allocDesc, &alloc, &allocOffset);
if(SUCCEEDED(hr))
{
    // Use the 4 KB of your memory starting at allocOffset.
}
else
{
    // Allocation failed - no space for it could be found. Handle this error!
}

Deallocation

When no longer needed, an allocation can be freed by calling D3D12MA::VirtualBlock::FreeAllocation.

When whole block is no longer needed, the block object can be released by calling block->Release(). All allocations must be freed before the block is destroyed, which is checked internally by an assert. However, if you don't want to call block->FreeAllocation for each allocation, you can use D3D12MA::VirtualBlock::Clear to free them all at once - a feature not available in normal D3D12 memory allocator.

Example:

block->FreeAllocation(alloc);
block->Release();

Allocation parameters

You can attach a custom pointer to each allocation by using D3D12MA::VirtualBlock::SetAllocationPrivateData. Its default value is NULL. It can be used to store any data that needs to be associated with that allocation - e.g. an index, a handle, or a pointer to some larger data structure containing more information. Example:

struct CustomAllocData
{
    std::string m_AllocName;
};
CustomAllocData* allocData = new CustomAllocData();
allocData->m_AllocName = "My allocation 1";
block->SetAllocationPrivateData(alloc, allocData);

The pointer can later be fetched, along with allocation offset and size, by passing the allocation handle to function D3D12MA::VirtualBlock::GetAllocationInfo and inspecting returned structure D3D12MA::VIRTUAL_ALLOCATION_INFO. If you allocated a new object to be used as the custom pointer, don't forget to delete that object before freeing the allocation! Example:

VIRTUAL_ALLOCATION_INFO allocInfo;
block->GetAllocationInfo(alloc, &allocInfo);
delete (CustomAllocData*)allocInfo.pPrivateData;
 
block->FreeAllocation(alloc);

Alignment and units

It feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member D3D12MA::VIRTUAL_ALLOCATION_DESC::Alignment to request it. Example:

D3D12MA::VIRTUAL_ALLOCATION_DESC allocDesc = {};
allocDesc.Size = 4096; // 4 KB
allocDesc.Alignment = 4; // Returned offset must be a multiply of 4 B
 
D3D12MA::VirtualAllocation alloc;
UINT64 allocOffset;
hr = block->Allocate(&allocDesc, &alloc, &allocOffset);

Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:

• D3D12MA::VIRTUAL_BLOCK_DESC::Size
• D3D12MA::VIRTUAL_ALLOCATION_DESC::Size and D3D12MA::VIRTUAL_ALLOCATION_DESC::Alignment
• Using offset returned by D3D12MA::VirtualBlock::Allocate and D3D12MA::VIRTUAL_ALLOCATION_INFO::Offset

Statistics

You can obtain brief statistics of a virtual block using D3D12MA::VirtualBlock::GetStatistics(). The function fills structure D3D12MA::Statistics - same as used by the normal D3D12 memory allocator. Example:

D3D12MA::Statistics stats;
block->GetStatistics(&stats);
printf("My virtual block has %llu bytes used by %u virtual allocations\n",
    stats.AllocationBytes, stats.AllocationCount);

More detailed statistics can be obtained using function D3D12MA::VirtualBlock::CalculateStatistics(), but they are slower to calculate.

You can also request a full list of allocations and free regions as a string in JSON format by calling D3D12MA::VirtualBlock::BuildStatsString. Returned string must be later freed using D3D12MA::VirtualBlock::FreeStatsString. The format of this string may differ from the one returned by the main D3D12 allocator, but it is similar.

Additional considerations

Alternative, linear algorithm can be used with virtual allocator - see flag D3D12MA::VIRTUAL_BLOCK_FLAG_ALGORITHM_LINEAR and documentation: Linear allocation algorithm.

Note that the "virtual allocator" functionality is implemented on a level of individual memory blocks. Keeping track of a whole collection of blocks, allocating new ones when out of free space, deleting empty ones, and deciding which one to try first for a new allocation must be implemented by the user.

As an extra feature, the core allocation algorithm of the library is exposed through a simple and convenient API of "virtual allocator". It doesn't allocate any real GPU memory. It just keeps track of used and free regions of a "virtual block". You can use it to allocate your own memory or other objects, even completely unrelated to Vulkan. A common use case is sub-allocation of pieces of one large GPU buffer.

Creating virtual block

To use this functionality, there is no main "allocator" object. You don't need to have VmaAllocator object created. All you need to do is to create a separate VmaVirtualBlock object for each block of memory you want to be managed by the allocator:

1. Fill in VmaVirtualBlockCreateInfo structure.
2. Call vmaCreateVirtualBlock(). Get new VmaVirtualBlock object.

Example:

VmaVirtualBlockCreateInfo blockCreateInfo = {};
blockCreateInfo.size = 1048576; // 1 MB
 
VmaVirtualBlock block;
VkResult res = vmaCreateVirtualBlock(&blockCreateInfo, &block);

Making virtual allocations

VmaVirtualBlock object contains internal data structure that keeps track of free and occupied regions using the same code as the main Vulkan memory allocator. Similarly to VmaAllocation for standard GPU allocations, there is VmaVirtualAllocation type that represents an opaque handle to an allocation within the virtual block.

In order to make such allocation:

1. Fill in VmaVirtualAllocationCreateInfo structure.
2. Call vmaVirtualAllocate(). Get new VmaVirtualAllocation object that represents the allocation. You can also receive VkDeviceSize offset that was assigned to the allocation.

Example:

VmaVirtualAllocationCreateInfo allocCreateInfo = {};
allocCreateInfo.size = 4096; // 4 KB
 
VmaVirtualAllocation alloc;
VkDeviceSize offset;
res = vmaVirtualAllocate(block, &allocCreateInfo, &alloc, &offset);
if(res == VK_SUCCESS)
{
    // Use the 4 KB of your memory starting at offset.
}
else
{
    // Allocation failed - no space for it could be found. Handle this error!
}

Deallocation

When no longer needed, an allocation can be freed by calling vmaVirtualFree(). You can only pass to this function an allocation that was previously returned by vmaVirtualAllocate() called for the same VmaVirtualBlock.

When whole block is no longer needed, the block object can be released by calling vmaDestroyVirtualBlock(). All allocations must be freed before the block is destroyed, which is checked internally by an assert. However, if you don't want to call vmaVirtualFree() for each allocation, you can use vmaClearVirtualBlock() to free them all at once - a feature not available in normal Vulkan memory allocator. Example:

vmaVirtualFree(block, alloc);
vmaDestroyVirtualBlock(block);

Allocation parameters

You can attach a custom pointer to each allocation by using vmaSetVirtualAllocationUserData(). Its default value is null. It can be used to store any data that needs to be associated with that allocation - e.g. an index, a handle, or a pointer to some larger data structure containing more information. Example:

struct CustomAllocData
{
    std::string m_AllocName;
};
CustomAllocData* allocData = new CustomAllocData();
allocData->m_AllocName = "My allocation 1";
vmaSetVirtualAllocationUserData(block, alloc, allocData);

The pointer can later be fetched, along with allocation offset and size, by passing the allocation handle to function vmaGetVirtualAllocationInfo() and inspecting returned structure VmaVirtualAllocationInfo. If you allocated a new object to be used as the custom pointer, don't forget to delete that object before freeing the allocation! Example:

VmaVirtualAllocationInfo allocInfo;
vmaGetVirtualAllocationInfo(block, alloc, &allocInfo);
delete (CustomAllocData*)allocInfo.pUserData;
 
vmaVirtualFree(block, alloc);

Alignment and units

It feels natural to express sizes and offsets in bytes. If an offset of an allocation needs to be aligned to a multiply of some number (e.g. 4 bytes), you can fill optional member VmaVirtualAllocationCreateInfo::alignment to request it. Example:

VmaVirtualAllocationCreateInfo allocCreateInfo = {};
allocCreateInfo.size = 4096; // 4 KB
allocCreateInfo.alignment = 4; // Returned offset must be a multiply of 4 B
 
VmaVirtualAllocation alloc;
res = vmaVirtualAllocate(block, &allocCreateInfo, &alloc, nullptr);

Alignments of different allocations made from one block may vary. However, if all alignments and sizes are always multiply of some size e.g. 4 B or sizeof(MyDataStruct), you can express all sizes, alignments, and offsets in multiples of that size instead of individual bytes. It might be more convenient, but you need to make sure to use this new unit consistently in all the places:

• VmaVirtualBlockCreateInfo::size
• VmaVirtualAllocationCreateInfo::size and VmaVirtualAllocationCreateInfo::alignment
• Using offset returned by vmaVirtualAllocate() or in VmaVirtualAllocationInfo::offset

Statistics

You can obtain statistics of a virtual block using vmaGetVirtualBlockStatistics() (to get brief statistics that are fast to calculate) or vmaCalculateVirtualBlockStatistics() (to get more detailed statistics, slower to calculate). The functions fill structures VmaStatistics, VmaDetailedStatistics respectively - same as used by the normal Vulkan memory allocator. Example:

VmaStatistics stats;
vmaGetVirtualBlockStatistics(block, &stats);
printf("My virtual block has %llu bytes used by %u virtual allocations\n",
    stats.allocationBytes, stats.allocationCount);

You can also request a full list of allocations and free regions as a string in JSON format by calling vmaBuildVirtualBlockStatsString(). Returned string must be later freed using vmaFreeVirtualBlockStatsString(). The format of this string differs from the one returned by the main Vulkan allocator, but it is similar.

Additional considerations

The "virtual allocator" functionality is implemented on a level of individual memory blocks. Keeping track of a whole collection of blocks, allocating new ones when out of free space, deleting empty ones, and deciding which one to try first for a new allocation must be implemented by the user.

Alternative allocation algorithms are supported, just like in custom pools of the real GPU memory. See enum VmaVirtualBlockCreateFlagBits to learn how to specify them (e.g. VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT). You can find their description in chapter Custom memory pools. Allocation strategies are also supported. See enum VmaVirtualAllocationCreateFlagBits to learn how to specify them (e.g. VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT).

Following features are supported only by the allocator of the real GPU memory and not by virtual allocations: buffer-image granularity, VMA_DEBUG_MARGIN, VMA_MIN_ALIGNMENT.