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_BUDDY_ALGORITHM_BIT = 0x00000002 , VMA_VIRTUAL_BLOCK_CREATE_TLSF_ALGORITHM_BIT = 0x00000004 , 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_FRAGMENTATION_BIT = VMA_ALLOCATION_CREATE_STRATEGY_MIN_FRAGMENTATION_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	vmaCalculateVirtualBlockStats (VmaVirtualBlock virtualBlock, VmaStatInfo *pStatInfo)
	Calculates and returns 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_FRAGMENTATION_BIT	Allocation strategy that tries to minimize memory fragmentation.
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_BUDDY_ALGORITHM_BIT	Enables alternative, buddy allocation algorithm in this virtual block. It operates on a tree of blocks, each having size that is a power of two and a half of its parent's size. Comparing to default algorithm, this one provides faster allocation and deallocation and decreased external fragmentation, at the expense of more memory wasted (internal fragmentation). For details, see documentation chapter Buddy allocation algorithm.
VMA_VIRTUAL_BLOCK_CREATE_TLSF_ALGORITHM_BIT	Enables alternative, TLSF allocation algorithm in virtual block. This algorithm is based on 2-level lists dividing address space into smaller chunks. The first level is aligned to power of two which serves as buckets for requested memory to fall into, and the second level is lineary subdivided into lists of free memory. This algorithm aims to achieve bounded response time even in the worst case scenario. Allocation time can be sometimes slightly longer than compared to other algorithms but in return the application can avoid stalls in case of fragmentation, giving predictable results, suitable for real-time use cases.
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 )

◆ vmaCalculateVirtualBlockStats()

void vmaCalculateVirtualBlockStats	(	VmaVirtualBlock	virtualBlock,
		VmaStatInfo *	pStatInfo
	)

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

◆ 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.

◆ 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.

There is no handle type for a virtual allocation. Virtual allocations within a specific virtual block are uniquely identified by their offsets.

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).

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.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ VmaVirtualAllocationCreateFlagBits

◆ VmaVirtualAllocationCreateFlags

◆ VmaVirtualAllocationCreateInfo

◆ VmaVirtualAllocationInfo

◆ VmaVirtualBlockCreateFlagBits

◆ VmaVirtualBlockCreateFlags

◆ VmaVirtualBlockCreateInfo

Enumeration Type Documentation

◆ VmaVirtualAllocationCreateFlagBits

◆ VmaVirtualBlockCreateFlagBits

Function Documentation

◆ VK_DEFINE_NON_DISPATCHABLE_HANDLE()

◆ vmaCalculateVirtualBlockStats()

◆ vmaClearVirtualBlock()

◆ vmaCreateVirtualBlock()

◆ vmaDestroyVirtualBlock()

◆ vmaGetVirtualAllocationInfo()

◆ vmaIsVirtualBlockEmpty()

◆ vmaSetVirtualAllocationUserData()

◆ vmaVirtualAllocate()

◆ vmaVirtualFree()