Class VmaAllocationCreateFlags

java.lang.Object

club.doki7.vma.bitmask.VmaAllocationCreateFlags

public final class VmaAllocationCreateFlags
extends Object

Flags to be passed as VmaAllocationCreateInfo::flags.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CAN_ALIAS	Set this flag if the allocated memory will have aliasing resources.
static final int	DEDICATED_MEMORY	Set this flag if the allocation should have its own memory block.
static final int	DONT_BIND	Create both buffer/image and allocation, but don't bind them together.
static final int	FLAG_BITS_MAX_ENUM
static final int	HOST_ACCESS_ALLOW_TRANSFER_INSTEAD	Together with VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT, it says that despite request for host access, a not-HOST_VISIBLE memory type can be selected if it may improve performance.
static final int	HOST_ACCESS_RANDOM	Requests possibility to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT).
static final int	HOST_ACCESS_SEQUENTIAL_WRITE	Requests possibility to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT).
static final int	MAPPED	Set this flag to use a memory that will be persistently mapped and retrieve pointer to it.
static final int	NEVER_ALLOCATE	Set this flag to only try to allocate from existing VkDeviceMemory blocks and never create new such block.
static final int	STRATEGY_BEST_FIT	Alias to VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT.
static final int	STRATEGY_FIRST_FIT	Alias to VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT.
static final int	STRATEGY_MASK	A bit mask to extract only STRATEGY bits from entire set of flags.
static final int	STRATEGY_MIN_MEMORY	Allocation strategy that chooses smallest possible free range for the allocation to minimize memory usage and fragmentation, possibly at the expense of allocation time.
static final int	STRATEGY_MIN_OFFSET	Allocation strategy that chooses always the lowest offset in available space.
static final int	STRATEGY_MIN_TIME	Allocation strategy that chooses first suitable free range for the allocation - not necessarily in terms of the smallest offset but the one that is easiest and fastest to find to minimize allocation time, possibly at the expense of allocation quality.
static final int	UPPER_ADDRESS	Allocation will be created from upper stack in a double stack pool.
static final int	USER_DATA_COPY_STRING
static final int	WITHIN_BUDGET	Create allocation only if additional device memory required for it, if any, won't exceed memory budget.

Method Summary

Modifier and Type	Method	Description
static String	explain(int flags)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CAN_ALIAS

public static final int CAN_ALIAS

Set this flag if the allocated memory will have aliasing resources.

Usage of this flag prevents supplying VkMemoryDedicatedAllocateInfoKHR when VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT is specified. Otherwise created dedicated memory will not be suitable for aliasing resources, resulting in Vulkan Validation Layer errors.

See Also:

• Constant Field Values

DEDICATED_MEMORY

public static final int DEDICATED_MEMORY

Set this flag if the allocation should have its own memory block.

Use it for special, big resources, like fullscreen images used as attachments.

If you use this flag while creating a buffer or an image, VkMemoryDedicatedAllocateInfo structure is applied if possible.

See Also:

• Constant Field Values

DONT_BIND

public static final int DONT_BIND

Create both buffer/image and allocation, but don't bind them together. It is useful when you want to bind yourself to do some more advanced binding, e.g. using some extensions. The flag is meaningful only with functions that bind by default: vmaCreateBuffer(), vmaCreateImage(). Otherwise it is ignored.

If you want to make sure the new buffer/image is not tied to the new memory allocation through VkMemoryDedicatedAllocateInfoKHR structure in case the allocation ends up in its own memory block, use also flag VMA_ALLOCATION_CREATE_CAN_ALIAS_BIT.

See Also:

• Constant Field Values

FLAG_BITS_MAX_ENUM

public static final int FLAG_BITS_MAX_ENUM

See Also:

• Constant Field Values

HOST_ACCESS_ALLOW_TRANSFER_INSTEAD

public static final int HOST_ACCESS_ALLOW_TRANSFER_INSTEAD

Together with VMA_ALLOCATION_CREATE_HOST_ACCESS_SEQUENTIAL_WRITE_BIT or VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT, it says that despite request for host access, a not-HOST_VISIBLE memory type can be selected if it may improve performance.

By using this flag, you declare that you will check if the allocation ended up in a HOST_VISIBLE memory type (e.g. using vmaGetAllocationMemoryProperties()) and if not, you will create some "staging" buffer and issue an explicit transfer to write/read your data. To prepare for this possibility, don't forget to add appropriate flags like VK_BUFFER_USAGE_TRANSFER_DST_BIT, VK_BUFFER_USAGE_TRANSFER_SRC_BIT to the parameters of created buffer or image.

See Also:

• Constant Field Values

HOST_ACCESS_RANDOM

public static final int HOST_ACCESS_RANDOM

Requests possibility to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT).

• If you use VMA_MEMORY_USAGE_AUTO or other VMA_MEMORY_USAGE_AUTO* value, you must use this flag to be able to map the allocation. Otherwise, mapping is incorrect.
• If you use other value of VmaMemoryUsage, this flag is ignored and mapping is always possible in memory types that are HOST_VISIBLE. This includes allocations created in custom_memory_pools.

Declares that mapped memory can be read, written, and accessed in random order, so a HOST_CACHED memory type is preferred.

See Also:

• Constant Field Values

HOST_ACCESS_SEQUENTIAL_WRITE

public static final int HOST_ACCESS_SEQUENTIAL_WRITE

Requests possibility to map the allocation (using vmaMapMemory() or VMA_ALLOCATION_CREATE_MAPPED_BIT).

• If you use VMA_MEMORY_USAGE_AUTO or other VMA_MEMORY_USAGE_AUTO* value, you must use this flag to be able to map the allocation. Otherwise, mapping is incorrect.
• If you use other value of VmaMemoryUsage, this flag is ignored and mapping is always possible in memory types that are HOST_VISIBLE. This includes allocations created in custom_memory_pools.

Declares that mapped memory will only be written sequentially, e.g. using memcpy() or a loop writing number-by-number, never read or accessed randomly, so a memory type can be selected that is uncached and write-combined.

Warning: Violating this declaration may work correctly, but will likely be very slow. Watch out for implicit reads introduced by doing e.g. pMappedData[i] += x; Better prepare your data in a local variable and memcpy() it to the mapped pointer all at once.

See Also:

• Constant Field Values

MAPPED

public static final int MAPPED

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.

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

See Also:

• Constant Field Values

NEVER_ALLOCATE

public static final int NEVER_ALLOCATE

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.

See Also:

• Constant Field Values

STRATEGY_MIN_MEMORY

public static final int STRATEGY_MIN_MEMORY

Allocation strategy that chooses smallest possible free range for the allocation to minimize memory usage and fragmentation, possibly at the expense of allocation time.

See Also:

• Constant Field Values

STRATEGY_MIN_OFFSET

public static final int STRATEGY_MIN_OFFSET

Allocation strategy that chooses always the lowest offset in available space. This is not the most efficient strategy but achieves highly packed data. Used internally by defragmentation, not recommended in typical usage.

See Also:

• Constant Field Values

STRATEGY_MIN_TIME

public static final int STRATEGY_MIN_TIME

Allocation strategy that chooses first suitable free range for the allocation - not necessarily in terms of the smallest offset but the one that is easiest and fastest to find to minimize allocation time, possibly at the expense of allocation quality.

See Also:

• Constant Field Values

UPPER_ADDRESS

public static final int UPPER_ADDRESS

Allocation will be created from upper stack in a double stack pool.

This flag is only allowed for custom pools created with VMA_POOL_CREATE_LINEAR_ALGORITHM_BIT flag.

See Also:

• Constant Field Values

USER_DATA_COPY_STRING

public static final int USER_DATA_COPY_STRING

See Also:

• Constant Field Values

WITHIN_BUDGET

public static final int WITHIN_BUDGET

Create allocation only if additional device memory required for it, if any, won't exceed memory budget. Otherwise return VK_ERROR_OUT_OF_DEVICE_MEMORY.

See Also:

• Constant Field Values

STRATEGY_BEST_FIT

public static final int STRATEGY_BEST_FIT

Alias to VMA_ALLOCATION_CREATE_STRATEGY_MIN_MEMORY_BIT.

See Also:

• Constant Field Values

STRATEGY_FIRST_FIT

public static final int STRATEGY_FIRST_FIT

Alias to VMA_ALLOCATION_CREATE_STRATEGY_MIN_TIME_BIT.

See Also:

• Constant Field Values

STRATEGY_MASK

public static final int STRATEGY_MASK

A bit mask to extract only STRATEGY bits from entire set of flags.

See Also:

• Constant Field Values

Method Details

explain

public static String explain(@EnumType(VmaAllocationCreateFlags.class)
 int flags)