Layer 1 Choosing Memory Type

Classes
struct	VmaAllocationCreateInfo

Typedefs
typedef enum VmaMemoryUsage	VmaMemoryUsage
typedef enum VmaAllocationCreateFlagBits	VmaAllocationCreateFlagBits
	Flags to be passed as VmaAllocationCreateInfo::flags. More...
typedef VkFlags	VmaAllocationCreateFlags
typedef struct VmaAllocationCreateInfo	VmaAllocationCreateInfo

Enumerations
enum	VmaMemoryUsage {   VMA_MEMORY_USAGE_UNKNOWN = 0, VMA_MEMORY_USAGE_GPU_ONLY = 1, VMA_MEMORY_USAGE_CPU_ONLY = 2, VMA_MEMORY_USAGE_CPU_TO_GPU = 3,   VMA_MEMORY_USAGE_GPU_TO_CPU = 4, VMA_MEMORY_USAGE_MAX_ENUM = 0x7FFFFFFF }
enum	VmaAllocationCreateFlagBits {   VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT = 0x00000001, VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT = 0x00000002, VMA_ALLOCATION_CREATE_PERSISTENT_MAP_BIT = 0x00000004, VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT = 0x00000008,   VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT = 0x00000010, VMA_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF }
	Flags to be passed as VmaAllocationCreateInfo::flags. More...

Functions
VkResult	vmaFindMemoryTypeIndex (VmaAllocator allocator, uint32_t memoryTypeBits, const VmaAllocationCreateInfo *pAllocationCreateInfo, uint32_t *pMemoryTypeIndex)

Detailed Description

Typedef Documentation

VmaAllocationCreateFlagBits

typedef enum VmaAllocationCreateFlagBits VmaAllocationCreateFlagBits

Flags to be passed as VmaAllocationCreateInfo::flags.

VmaAllocationCreateFlags

typedef VkFlags VmaAllocationCreateFlags

VmaAllocationCreateInfo

typedef struct VmaAllocationCreateInfo VmaAllocationCreateInfo

VmaMemoryUsage

typedef enum VmaMemoryUsage VmaMemoryUsage

Enumeration Type Documentation

VmaAllocationCreateFlagBits

enum VmaAllocationCreateFlagBits

Flags to be passed as VmaAllocationCreateInfo::flags.

Enumerator
VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT	Set this flag if the allocation should have its own memory block. Use it for special, big resources, like fullscreen images used as attachments. This flag must also be used for host visible resources that you want to map simultaneously because otherwise they might end up as regions of the same VkDeviceMemory, while mapping same VkDeviceMemory multiple times simultaneously is illegal. You should not use this flag if VmaAllocationCreateInfo::pool is not null.
VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT	Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such block. If new allocation cannot be placed in any of the existing blocks, allocation fails with VK_ERROR_OUT_OF_DEVICE_MEMORY error. You should not use VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT and VMA_ALLOCATION_CREATE_NEVER_ALLOCATE_BIT at the same time. It makes no sense. If VmaAllocationCreateInfo::pool is not null, this flag is implied and ignored.
VMA_ALLOCATION_CREATE_PERSISTENT_MAP_BIT	Set this flag to use a memory that will be persistently mapped and retrieve pointer to it. Pointer to mapped memory will be returned through VmaAllocationInfo::pMappedData. You cannot map the memory on your own as multiple mappings of a single VkDeviceMemory are illegal. If VmaAllocationCreateInfo::pool is not null, usage of this flag must match usage of flag VMA_POOL_CREATE_PERSISTENT_MAP_BIT used during pool creation. Is it valid to use this flag for allocation made from memory type that is not HOST_VISIBLE. This flag is then ignored and memory is not mapped. This is useful if you need an allocation that is efficient to use on GPU (DEVICE_LOCAL) and still want to map it directly if possible on platforms that support it (e.g. Intel GPU).
VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT	Allocation created with this flag can become lost as a result of another allocation with VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT flag, so you must check it before use. To check if allocation is not lost, call vmaGetAllocationInfo() and check if VmaAllocationInfo::deviceMemory is not VK_NULL_HANDLE. For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.
VMA_ALLOCATION_CREATE_CAN_MAKE_OTHER_LOST_BIT	While creating allocation using this flag, other allocations that were created with flag VMA_ALLOCATION_CREATE_CAN_BECOME_LOST_BIT can become lost. For details about supporting lost allocations, see Lost Allocations chapter of User Guide on Main Page.
VMA_ALLOCATION_CREATE_FLAG_BITS_MAX_ENUM

VmaMemoryUsage

enum VmaMemoryUsage

Enumerator
VMA_MEMORY_USAGE_UNKNOWN	No intended memory usage specified.
VMA_MEMORY_USAGE_GPU_ONLY	Memory will be used on device only, so faster access from the device is preferred. No need to be mappable on host.
VMA_MEMORY_USAGE_CPU_ONLY	Memory will be mapped on host. Could be used for transfer to/from device. Guarantees to be HOST_VISIBLE and HOST_COHERENT.
VMA_MEMORY_USAGE_CPU_TO_GPU	Memory will be used for frequent (dynamic) updates from host and reads on device (upload). Guarantees to be HOST_VISIBLE.
VMA_MEMORY_USAGE_GPU_TO_CPU	Memory will be used for frequent writing on device and readback on host (download). Guarantees to be HOST_VISIBLE.
VMA_MEMORY_USAGE_MAX_ENUM

Function Documentation

vmaFindMemoryTypeIndex()

VkResult vmaFindMemoryTypeIndex	(	VmaAllocator	allocator,
		uint32_t	memoryTypeBits,
		const VmaAllocationCreateInfo *	pAllocationCreateInfo,
		uint32_t *	pMemoryTypeIndex
	)

This algorithm tries to find a memory type that:

• Is allowed by memoryTypeBits.
• Contains all the flags from pAllocationCreateInfo->requiredFlags.
• Matches intended usage.
• Has as many flags from pAllocationCreateInfo->preferredFlags as possible.

Returns

Returns VK_ERROR_FEATURE_NOT_PRESENT if not found. Receiving such result from this function or any other allocating function probably means that your device doesn't support any memory type with requested features for the specific type of resource you want to use it for. Please check parameters of your resource, like image layout (OPTIMAL versus LINEAR) or mip level count.