Vulkan Memory Allocator: Virtual allocator

Vulkan Memory Allocator

Classes | Typedefs | Enumerations | Functions
Virtual allocator

API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory. More...

## Classes
struct | VmaVirtualBlockCreateInfo
| Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock(). More...
struct | VmaVirtualAllocationCreateInfo
| Parameters of created virtual allocation to be passed to vmaVirtualAllocate(). More...
struct | VmaVirtualAllocationInfo
| Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo(). More...
struct | VmaVirtualAllocation
| Represents single memory allocation done inside VmaVirtualBlock. More...
struct | VmaVirtualBlock
| Handle to a virtual block object that allows to use core allocation algorithm without allocating any real GPU memory. More...

## Typedefs
typedef enum VmaVirtualBlockCreateFlagBits | VmaVirtualBlockCreateFlagBits
| Flags to be passed as VmaVirtualBlockCreateInfo::flags. More...
typedef VkFlags | VmaVirtualBlockCreateFlags
| Flags to be passed as VmaVirtualBlockCreateInfo::flags. See VmaVirtualBlockCreateFlagBits. More...
typedef enum VmaVirtualAllocationCreateFlagBits | VmaVirtualAllocationCreateFlagBits
| Flags to be passed as VmaVirtualAllocationCreateInfo::flags. More...
typedef VkFlags | VmaVirtualAllocationCreateFlags
| Flags to be passed as VmaVirtualAllocationCreateInfo::flags. See VmaVirtualAllocationCreateFlagBits. More...
typedef struct VmaVirtualBlockCreateInfo | VmaVirtualBlockCreateInfo
| Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock(). More...
typedef struct VmaVirtualAllocationCreateInfo | VmaVirtualAllocationCreateInfo
| Parameters of created virtual allocation to be passed to vmaVirtualAllocate(). More...
typedef struct VmaVirtualAllocationInfo | VmaVirtualAllocationInfo
| Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo(). More...

## Enumerations
enum | VmaVirtualBlockCreateFlagBits { VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT = 0x00000001 , VMA_VIRTUAL_BLOCK_CREATE_ALGORITHM_MASK , VMA_VIRTUAL_BLOCK_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF }
| Flags to be passed as VmaVirtualBlockCreateInfo::flags. More...
enum | VmaVirtualAllocationCreateFlagBits { VMA_VIRTUAL_ALLOCATION_CREATE_UPPER_ADDRESS_BIT = VMA_ALLOCATION_CREATE_UPPER_ADDRESS_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_OFFSET_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_OFFSET_BIT , VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MASK = VMA_ALLOCATION_CREATE_STRATEGY_MASK , VMA_VIRTUAL_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF }
| Flags to be passed as VmaVirtualAllocationCreateInfo::flags. More...

## Functions
| VK_DEFINE_NON_DISPATCHABLE_HANDLE (VmaVirtualAllocation)
VkResult | vmaCreateVirtualBlock (const VmaVirtualBlockCreateInfo *pCreateInfo, VmaVirtualBlock *pVirtualBlock)
| Creates new VmaVirtualBlock object. More...
void | vmaDestroyVirtualBlock (VmaVirtualBlock virtualBlock)
| Destroys VmaVirtualBlock object. More...
VkBool32 | vmaIsVirtualBlockEmpty (VmaVirtualBlock virtualBlock)
| Returns true of the VmaVirtualBlock is empty - contains 0 virtual allocations and has all its space available for new allocations. More...
void | vmaGetVirtualAllocationInfo (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, VmaVirtualAllocationInfo *pVirtualAllocInfo)
| Returns information about a specific virtual allocation within a virtual block, like its size and `pUserData` pointer. More...
VkResult | vmaVirtualAllocate (VmaVirtualBlock virtualBlock, const VmaVirtualAllocationCreateInfo *pCreateInfo, VmaVirtualAllocation *pAllocation, VkDeviceSize *pOffset)
| Allocates new virtual allocation inside given VmaVirtualBlock. More...
void | vmaVirtualFree (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation)
| Frees virtual allocation inside given VmaVirtualBlock. More...
void | vmaClearVirtualBlock (VmaVirtualBlock virtualBlock)
| Frees all virtual allocations inside given VmaVirtualBlock. More...
void | vmaSetVirtualAllocationUserData (VmaVirtualBlock virtualBlock, VmaVirtualAllocation allocation, void *pUserData)
| Changes custom pointer associated with given virtual allocation. More...
void | vmaGetVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaStatistics *pStats)
| Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock. More...
void | vmaCalculateVirtualBlockStatistics (VmaVirtualBlock virtualBlock, VmaDetailedStatistics *pStats)
| Calculates and returns detailed statistics about virtual allocations and memory usage in given VmaVirtualBlock. More...

## Detailed Description

API elements related to the mechanism of Virtual allocator - using the core allocation algorithm for user-defined purpose without allocating any real GPU memory.

## Typedef Documentation

## ◆ VmaVirtualAllocationCreateFlagBits

typedef enum VmaVirtualAllocationCreateFlagBits VmaVirtualAllocationCreateFlagBits

Flags to be passed as VmaVirtualAllocationCreateInfo::flags.

## ◆ VmaVirtualAllocationCreateFlags

typedef VkFlags VmaVirtualAllocationCreateFlags

Flags to be passed as VmaVirtualAllocationCreateInfo::flags. See VmaVirtualAllocationCreateFlagBits.

## ◆ VmaVirtualAllocationCreateInfo

typedef struct VmaVirtualAllocationCreateInfo VmaVirtualAllocationCreateInfo

Parameters of created virtual allocation to be passed to vmaVirtualAllocate().

## ◆ VmaVirtualAllocationInfo

typedef struct VmaVirtualAllocationInfo VmaVirtualAllocationInfo

Parameters of an existing virtual allocation, returned by vmaGetVirtualAllocationInfo().

## ◆ VmaVirtualBlockCreateFlagBits

typedef enum VmaVirtualBlockCreateFlagBits VmaVirtualBlockCreateFlagBits

Flags to be passed as VmaVirtualBlockCreateInfo::flags.

## ◆ VmaVirtualBlockCreateFlags

typedef VkFlags VmaVirtualBlockCreateFlags

Flags to be passed as VmaVirtualBlockCreateInfo::flags. See VmaVirtualBlockCreateFlagBits.

## ◆ VmaVirtualBlockCreateInfo

typedef struct VmaVirtualBlockCreateInfo VmaVirtualBlockCreateInfo

Parameters of created VmaVirtualBlock object to be passed to vmaCreateVirtualBlock().

## Enumeration Type Documentation

## ◆ VmaVirtualAllocationCreateFlagBits

enum VmaVirtualAllocationCreateFlagBits

Flags to be passed as VmaVirtualAllocationCreateInfo::flags.

Enumerator
VMA_VIRTUAL_ALLOCATION_CREATE_UPPER_ADDRESS_BIT | Allocation will be created from upper stack in a double stack pool. This flag is only allowed for virtual blocks created with VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT flag.
VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT | Allocation strategy that tries to minimize memory usage.
VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT | Allocation strategy that tries to minimize allocation time.
VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MIN_OFFSET_BIT | Allocation strategy that chooses always the lowest offset in available space. This is not the most efficient strategy but achieves highly packed data.
VMA_VIRTUAL_ALLOCATION_CREATE_STRATEGY_MASK | A bit mask to extract only `STRATEGY` bits from entire set of flags. These strategy flags are binary compatible with equivalent flags in VmaAllocationCreateFlagBits.
VMA_VIRTUAL_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM |

## ◆ VmaVirtualBlockCreateFlagBits

enum VmaVirtualBlockCreateFlagBits

Flags to be passed as VmaVirtualBlockCreateInfo::flags.

Enumerator
VMA_VIRTUAL_BLOCK_CREATE_LINEAR_ALGORITHM_BIT | Enables alternative, linear allocation algorithm in this virtual block. Specify this flag to enable linear allocation algorithm, which always creates new allocations after last one and doesn't reuse space from allocations freed in between. It trades memory consumption for simplified algorithm and data structure, which has better performance and uses less memory for metadata. By using this flag, you can achieve behavior of free-at-once, stack, ring buffer, and double stack. For details, see documentation chapter Linear allocation algorithm.
VMA_VIRTUAL_BLOCK_CREATE_ALGORITHM_MASK | Bit mask to extract only `ALGORITHM` bits from entire set of flags.
VMA_VIRTUAL_BLOCK_CREATE_FLAG_BITS_MAX_ENUM |

## Function Documentation

## ◆ VK_DEFINE_NON_DISPATCHABLE_HANDLE()

VK_DEFINE_NON_DISPATCHABLE_HANDLE | ( | VmaVirtualAllocation |  | ) |

## ◆ vmaCalculateVirtualBlockStatistics()

void vmaCalculateVirtualBlockStatistics | ( | VmaVirtualBlock | virtualBlock,
|  | VmaDetailedStatistics * | pStats
| ) |  |

Calculates and returns detailed statistics about virtual allocations and memory usage in given VmaVirtualBlock.

This function is slow to call. Use for debugging purposes. For less detailed statistics, see vmaGetVirtualBlockStatistics().

## ◆ vmaClearVirtualBlock()

void vmaClearVirtualBlock | ( | VmaVirtualBlock | virtualBlock | ) |

Frees all virtual allocations inside given VmaVirtualBlock.

You must either call this function or free each virtual allocation individually with vmaVirtualFree() before destroying a virtual block. Otherwise, an assert is called.

If you keep pointer to some additional metadata associated with your virtual allocation in its `pUserData`, don't forget to free it as well.

## ◆ vmaCreateVirtualBlock()

VkResult vmaCreateVirtualBlock | ( | const VmaVirtualBlockCreateInfo * | pCreateInfo,
|  | VmaVirtualBlock * | pVirtualBlock
| ) |  |

Creates new VmaVirtualBlock object.

Parameters

  | pCreateInfo | Parameters for creation.
  [out] | pVirtualBlock | Returned virtual block object or `VMA_NULL` if creation failed.

## ◆ vmaDestroyVirtualBlock()

void vmaDestroyVirtualBlock | ( | VmaVirtualBlock | virtualBlock | ) |

Destroys VmaVirtualBlock object.

Please note that you should consciously handle virtual allocations that could remain unfreed in the block. You should either free them individually using vmaVirtualFree() or call vmaClearVirtualBlock() if you are sure this is what you want. If you do neither, an assert is called.

If you keep pointers to some additional metadata associated with your virtual allocations in their `pUserData`, don't forget to free them.

## ◆ vmaGetVirtualAllocationInfo()

void vmaGetVirtualAllocationInfo | ( | VmaVirtualBlock | virtualBlock,
|  | VmaVirtualAllocation | allocation,
|  | VmaVirtualAllocationInfo * | pVirtualAllocInfo
| ) |  |

Returns information about a specific virtual allocation within a virtual block, like its size and `pUserData` pointer.

## ◆ vmaGetVirtualBlockStatistics()

void vmaGetVirtualBlockStatistics | ( | VmaVirtualBlock | virtualBlock,
|  | VmaStatistics * | pStats
| ) |  |

Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock.

This function is fast to call. For more detailed statistics, see vmaCalculateVirtualBlockStatistics().

## ◆ vmaIsVirtualBlockEmpty()

VkBool32 vmaIsVirtualBlockEmpty | ( | VmaVirtualBlock | virtualBlock | ) |

Returns true of the VmaVirtualBlock is empty - contains 0 virtual allocations and has all its space available for new allocations.

## ◆ vmaSetVirtualAllocationUserData()

void vmaSetVirtualAllocationUserData | ( | VmaVirtualBlock | virtualBlock,
|  | VmaVirtualAllocation | allocation,
|  | void * | pUserData
| ) |  |

Changes custom pointer associated with given virtual allocation.

## ◆ vmaVirtualAllocate()

VkResult vmaVirtualAllocate | ( | VmaVirtualBlock | virtualBlock,
|  | const VmaVirtualAllocationCreateInfo * | pCreateInfo,
|  | VmaVirtualAllocation * | pAllocation,
|  | VkDeviceSize * | pOffset
| ) |  |

Allocates new virtual allocation inside given VmaVirtualBlock.

If the allocation fails due to not enough free space available, `VK_ERROR_OUT_OF_DEVICE_MEMORY` is returned (despite the function doesn't ever allocate actual GPU memory). `pAllocation` is then set to `VK_NULL_HANDLE` and `pOffset`, if not null, it set to `UINT64_MAX`.

Parameters

  | virtualBlock | Virtual block
  | pCreateInfo | Parameters for the allocation
  [out] | pAllocation | Returned handle of the new allocation
  [out] | pOffset | Returned offset of the new allocation. Optional, can be null.

## ◆ vmaVirtualFree()

void vmaVirtualFree | ( | VmaVirtualBlock | virtualBlock,
|  | VmaVirtualAllocation | allocation
| ) |  |

Frees virtual allocation inside given VmaVirtualBlock.

It is correct to call this function with `allocation == VK_NULL_HANDLE` - it does nothing.