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.

typedef VkFlags	VmaVirtualBlockCreateFlags
	Flags to be passed as VmaVirtualBlockCreateInfo::flags. See VmaVirtualBlockCreateFlagBits.

typedef enum VmaVirtualAllocationCreateFlagBits	VmaVirtualAllocationCreateFlagBits
	Flags to be passed as VmaVirtualAllocationCreateInfo::flags.

typedef VkFlags	VmaVirtualAllocationCreateFlags
	Flags to be passed as VmaVirtualAllocationCreateInfo::flags. See VmaVirtualAllocationCreateFlagBits.

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

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

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

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
VMA_CALL_PRE VkResult VMA_CALL_POST	vmaCreateVirtualBlock (const VmaVirtualBlockCreateInfo VMA_NOT_NULL pCreateInfo, VmaVirtualBlock VMA_NULLABLE VMA_NOT_NULL pVirtualBlock)
	Creates new VmaVirtualBlock object. More...

VMA_CALL_PRE void VMA_CALL_POST	vmaDestroyVirtualBlock (VmaVirtualBlock VMA_NULLABLE virtualBlock)
	Destroys VmaVirtualBlock object. More...

VMA_CALL_PRE VkBool32 VMA_CALL_POST	vmaIsVirtualBlockEmpty (VmaVirtualBlock VMA_NOT_NULL virtualBlock)
	Returns true of the VmaVirtualBlock is empty - contains 0 virtual allocations and has all its space available for new allocations.

VMA_CALL_PRE void VMA_CALL_POST	vmaGetVirtualAllocationInfo (VmaVirtualBlock VMA_NOT_NULL virtualBlock, VmaVirtualAllocation VMA_NOT_NULL_NON_DISPATCHABLE allocation, VmaVirtualAllocationInfo *VMA_NOT_NULL pVirtualAllocInfo)
	Returns information about a specific virtual allocation within a virtual block, like its size and `pUserData` pointer.

VMA_CALL_PRE VkResult VMA_CALL_POST	vmaVirtualAllocate (VmaVirtualBlock VMA_NOT_NULL virtualBlock, const VmaVirtualAllocationCreateInfo VMA_NOT_NULL pCreateInfo, VmaVirtualAllocation VMA_NULLABLE_NON_DISPATCHABLE VMA_NOT_NULL pAllocation, VkDeviceSize *VMA_NULLABLE pOffset)
	Allocates new virtual allocation inside given VmaVirtualBlock. More...

VMA_CALL_PRE void VMA_CALL_POST	vmaVirtualFree (VmaVirtualBlock VMA_NOT_NULL virtualBlock, VmaVirtualAllocation VMA_NULLABLE_NON_DISPATCHABLE allocation)
	Frees virtual allocation inside given VmaVirtualBlock. More...

VMA_CALL_PRE void VMA_CALL_POST	vmaClearVirtualBlock (VmaVirtualBlock VMA_NOT_NULL virtualBlock)
	Frees all virtual allocations inside given VmaVirtualBlock. More...

VMA_CALL_PRE void VMA_CALL_POST	vmaSetVirtualAllocationUserData (VmaVirtualBlock VMA_NOT_NULL virtualBlock, VmaVirtualAllocation VMA_NOT_NULL_NON_DISPATCHABLE allocation, void *VMA_NULLABLE pUserData)
	Changes custom pointer associated with given virtual allocation.

VMA_CALL_PRE void VMA_CALL_POST	vmaGetVirtualBlockStatistics (VmaVirtualBlock VMA_NOT_NULL virtualBlock, VmaStatistics *VMA_NOT_NULL pStats)
	Calculates and returns statistics about virtual allocations and memory usage in given VmaVirtualBlock. More...

VMA_CALL_PRE void VMA_CALL_POST	vmaCalculateVirtualBlockStatistics (VmaVirtualBlock VMA_NOT_NULL virtualBlock, VmaDetailedStatistics *VMA_NOT_NULL 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.

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.

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

Function Documentation

◆ vmaCalculateVirtualBlockStatistics()

VMA_CALL_PRE void VMA_CALL_POST vmaCalculateVirtualBlockStatistics	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		VmaDetailedStatistics *VMA_NOT_NULL	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()

VMA_CALL_PRE void VMA_CALL_POST vmaClearVirtualBlock ( VmaVirtualBlock VMA_NOT_NULL 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()

VMA_CALL_PRE VkResult VMA_CALL_POST vmaCreateVirtualBlock	(	const VmaVirtualBlockCreateInfo *VMA_NOT_NULL	pCreateInfo,
		VmaVirtualBlock VMA_NULLABLE *VMA_NOT_NULL	pVirtualBlock
	)

Creates new VmaVirtualBlock object.

Parameters

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

◆ vmaDestroyVirtualBlock()

VMA_CALL_PRE void VMA_CALL_POST vmaDestroyVirtualBlock ( VmaVirtualBlock VMA_NULLABLE 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.

◆ vmaGetVirtualBlockStatistics()

VMA_CALL_PRE void VMA_CALL_POST vmaGetVirtualBlockStatistics	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		VmaStatistics *VMA_NOT_NULL	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().

◆ vmaVirtualAllocate()

VMA_CALL_PRE VkResult VMA_CALL_POST vmaVirtualAllocate	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		const VmaVirtualAllocationCreateInfo *VMA_NOT_NULL	pCreateInfo,
		VmaVirtualAllocation VMA_NULLABLE_NON_DISPATCHABLE *VMA_NOT_NULL	pAllocation,
		VkDeviceSize *VMA_NULLABLE	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()

VMA_CALL_PRE void VMA_CALL_POST vmaVirtualFree	(	VmaVirtualBlock VMA_NOT_NULL	virtualBlock,
		VmaVirtualAllocation VMA_NULLABLE_NON_DISPATCHABLE	allocation
	)

Frees virtual allocation inside given VmaVirtualBlock.

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

Classes

Typedefs

Enumerations

Functions