Device memory is memory that is visible to the device, for example the contents of opaque images that can be natively used by the device, or uniform buffer objects that reside in on-device memory.
Memory properties of a physical device describe the memory heaps and memory types available.
To query memory properties, call:
void vkGetPhysicalDeviceMemoryProperties( VkPhysicalDevice physicalDevice, VkPhysicalDeviceMemoryProperties* pMemoryProperties);
physicalDevice
is the handle to the device to query.
pMemoryProperties
points to an instance of
VkPhysicalDeviceMemoryProperties
structure in which the properties
are returned.
The VkPhysicalDeviceMemoryProperties
structure is defined as:
typedef struct VkPhysicalDeviceMemoryProperties { uint32_t memoryTypeCount; VkMemoryType memoryTypes[VK_MAX_MEMORY_TYPES]; uint32_t memoryHeapCount; VkMemoryHeap memoryHeaps[VK_MAX_MEMORY_HEAPS]; } VkPhysicalDeviceMemoryProperties;
memoryTypeCount
is the number of valid elements in the
memoryTypes
array.
memoryTypes
is an array of VkMemoryType
structures
describing the memory types that can be used to access memory
allocated from the heaps specified by memoryHeaps
.
memoryHeapCount
is the number of valid elements in the
memoryHeaps
array.
memoryHeaps
is an array of VkMemoryHeap
structures
describing the memory heaps from which memory can be allocated.
The VkPhysicalDeviceMemoryProperties
structure describes a number of
memory heaps as well as a number of memory types that can be used to
access memory allocated in those heaps.
Each heap describes a memory resource of a particular size, and each memory
type describes a set of memory properties (e.g. host cached vs uncached)
that can be used with a given memory heap.
Allocations using a particular memory type will consume resources from the
heap indicated by that memory type’s heap index.
More than one memory type may share each heap, and the heaps and memory
types provide a mechanism to advertise an accurate size of the physical
memory resources while allowing the memory to be used with a variety of
different properties.
The number of memory heaps is given by memoryHeapCount
and is less
than or equal to VK_MAX_MEMORY_HEAPS
.
Each heap is described by an element of the memoryHeaps
array, as a
VkMemoryHeap
structure.
The number of memory types available across all memory heaps is given by
memoryTypeCount
and is less than or equal to
VK_MAX_MEMORY_TYPES
.
Each memory type is described by an element of the memoryTypes
array,
as a VkMemoryType
structure.
At least one heap must include VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
in
VkMemoryHeap
::flags
.
If there are multiple heaps that all have similar performance
characteristics, they may all include
VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
.
In a unified memory architecture (UMA) system, there is often only a single
memory heap which is considered to be equally “local” to the host and to
the device, and such an implementation must advertise the heap as
device-local.
Each memory type returned by vkGetPhysicalDeviceMemoryProperties
must
have its propertyFlags
set to one of the following values:
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_CACHED_BIT
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_CACHED_BIT
|
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
|
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
|
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_CACHED_BIT
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
|
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
|
VK_MEMORY_PROPERTY_HOST_CACHED_BIT
|
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
|
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
There must be at least one memory type with both the
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
and
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
bits set in its
propertyFlags
.
There must be at least one memory type with the
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
bit set in its
propertyFlags
.
The memory types are sorted according to a preorder which serves to aid in easily selecting an appropriate memory type. Given two memory types X and Y, the preorder defines X ≤ Y if:
Memory types are ordered in the list such that X is assigned a lesser
memoryTypeIndex
than Y if (X ≤ Y) ∧ ¬ (Y ≤ X)
according to the preorder.
Note that the list of all allowed memory property flag combinations above
satisfies this preorder, but other orders would as well.
The goal of this ordering is to enable applications to use a simple search
loop in selecting the proper memory type, along the lines of:
// Find a memory type in "memoryTypeBits" that includes all of "properties" int32_t FindProperties(uint32_t memoryTypeBits, VkMemoryPropertyFlags properties) { for (int32_t i = 0; i < memoryTypeCount; ++i) { if ((memoryTypeBits & (1 << i)) && ((memoryTypes[i].propertyFlags & properties) == properties)) return i; } return -1; } // Try to find an optimal memory type, or if it does not exist // find any compatible memory type VkMemoryRequirements memoryRequirements; vkGetImageMemoryRequirements(device, image, &memoryRequirements); int32_t memoryType = FindProperties(memoryRequirements.memoryTypeBits, optimalProperties); if (memoryType == -1) memoryType = FindProperties(memoryRequirements.memoryTypeBits, requiredProperties);
The loop will find the first supported memory type that has all bits
requested in properties
set.
If there is no exact match, it will find a closest match (i.e. a memory type
with the fewest additional bits set), which has some additional bits set but
which are not detrimental to the behaviors requested by properties
.
The application can first search for the optimal properties, e.g. a memory
type that is device-local or supports coherent cached accesses, as
appropriate for the intended usage, and if such a memory type is not present
can fallback to searching for a less optimal but guaranteed set of
properties such as "0" or "host-visible and coherent".
The VkMemoryHeap
structure is defined as:
typedef struct VkMemoryHeap { VkDeviceSize size; VkMemoryHeapFlags flags; } VkMemoryHeap;
size
is the total memory size in bytes in the heap.
flags
is a bitmask of attribute flags for the heap.
The bits specified in flags
are:
typedef enum VkMemoryHeapFlagBits { VK_MEMORY_HEAP_DEVICE_LOCAL_BIT = 0x00000001, } VkMemoryHeapFlagBits;
flags
contains VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
, it means
the heap corresponds to device local memory.
Device local memory may have different performance characteristics
than host local memory, and may support different memory property
flags.
The VkMemoryType
structure is defined as:
typedef struct VkMemoryType { VkMemoryPropertyFlags propertyFlags; uint32_t heapIndex; } VkMemoryType;
heapIndex
describes which memory heap this memory type corresponds
to, and must be less than memoryHeapCount
from the
VkPhysicalDeviceMemoryProperties
structure.
propertyFlags
is a bitmask of properties for this memory type.
The bits specified in propertyFlags
are:
typedef enum VkMemoryPropertyFlagBits { VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT = 0x00000001, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT = 0x00000002, VK_MEMORY_PROPERTY_HOST_COHERENT_BIT = 0x00000004, VK_MEMORY_PROPERTY_HOST_CACHED_BIT = 0x00000008, VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT = 0x00000010, } VkMemoryPropertyFlagBits;
propertyFlags
has the
VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
bit set, memory allocated
with this type is the most efficient for device access.
This property will only be set for memory types belonging to heaps with
the VK_MEMORY_HEAP_DEVICE_LOCAL_BIT
set.
propertyFlags
has the
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
bit set, memory allocated
with this type can be mapped for host access using vkMapMemory
.
propertyFlags
has the
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
bit set, host cache
management commands vkFlushMappedMemoryRanges
and
vkInvalidateMappedMemoryRanges
are not needed to make host writes
visible to the device or device writes visible to the host,
respectively.
propertyFlags
has the VK_MEMORY_PROPERTY_HOST_CACHED_BIT
bit set, memory allocated with this type is cached on the host.
Host memory accesses to uncached memory are slower than to cached
memory, however uncached memory is always host coherent.
propertyFlags
has the
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
bit set, the memory type
only allows device access to the memory.
Memory types must not have both
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
and
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
set.
Additionally, the object’s backing memory may be provided by the
implementation lazily as specified in Lazily Allocated Memory.
A Vulkan device operates on data in device memory via memory objects that
are represented in the API by a VkDeviceMemory
handle.
Memory objects are represented by VkDeviceMemory
handles:
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDeviceMemory)
To allocate memory objects, call:
VkResult vkAllocateMemory( VkDevice device, const VkMemoryAllocateInfo* pAllocateInfo, const VkAllocationCallbacks* pAllocator, VkDeviceMemory* pMemory);
device
is the logical device that owns the memory.
pAllocateInfo
is a pointer to an instance of the
VkMemoryAllocateInfo
structure describing parameters of the
allocation.
A successful returned allocation must use the requested parameters — no substitution is permitted by the implementation.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.
pMemory
is a pointer to a VkDeviceMemory
handle in which
information about the allocated memory is returned.
Allocations returned by vkAllocateMemory
are guaranteed to meet any
alignment requirement by the implementation.
For example, if an implementation requires 128 byte alignment for images and
64 byte alignment for buffers, the device memory returned through this
mechanism would be 128-byte aligned.
This ensures that applications can correctly suballocate objects of
different types (with potentially different alignment requirements) in the
same memory object.
When memory is allocated, its contents are undefined.
There is an implementation-dependent maximum number of memory allocations
which can be simultaneously created on a device.
This is specified by the
maxMemoryAllocationCount
member of the VkPhysicalDeviceLimits
structure.
If maxMemoryAllocationCount
is exceeded, vkAllocateMemory
will
return VK_ERROR_TOO_MANY_OBJECTS
.
![]() | Note |
---|---|
Some platforms may have a limit on the maximum size of a single allocation.
For example, certain systems may fail to create allocations with a size
greater than or equal to 4GB.
Such a limit is implementation-dependent, and if such a failure occurs then
the error |
The VkMemoryAllocateInfo
structure is defined as:
typedef struct VkMemoryAllocateInfo { VkStructureType sType; const void* pNext; VkDeviceSize allocationSize; uint32_t memoryTypeIndex; } VkMemoryAllocateInfo;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
allocationSize
is the size of the allocation in bytes
memoryTypeIndex
is the memory type index, which selects the
properties of the memory to be allocated, as well as the heap the memory
will come from.
To free a memory object, call:
void vkFreeMemory( VkDevice device, VkDeviceMemory memory, const VkAllocationCallbacks* pAllocator);
device
is the logical device that owns the memory.
memory
is the VkDeviceMemory
object to be freed.
pAllocator
controls host memory allocation as described in the
Memory Allocation chapter.
Before freeing a memory object, an application must ensure the memory object is no longer in use by the device—for example by command buffers queued for execution. The memory can remain bound to images or buffers at the time the memory object is freed, but any further use of them (on host or device) for anything other than destroying those objects will result in undefined behavior. If there are still any bound images or buffers, the memory may not be immediately released by the implementation, but must be released by the time all bound images and buffers have been destroyed. Once memory is released, it is returned to the heap from which it was allocated.
How memory objects are bound to Images and Buffers is described in detail in the Resource Memory Association section.
If a memory object is mapped at the time it is freed, it is implicitly unmapped.
Memory objects created with vkAllocateMemory
are not directly host
accessible.
Memory objects created with the memory property
VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
are considered mappable.
Memory objects must be mappable in order to be successfully mapped on the
host.
To retrieve a host virtual address pointer to a region of a mappable memory object, call:
VkResult vkMapMemory( VkDevice device, VkDeviceMemory memory, VkDeviceSize offset, VkDeviceSize size, VkMemoryMapFlags flags, void** ppData);
device
is the logical device that owns the memory.
memory
is the VkDeviceMemory
object to be mapped.
offset
is a zero-based byte offset from the beginning of the
memory object.
size
is the size of the memory range to map, or
VK_WHOLE_SIZE
to map from offset
to the end of the
allocation.
flags
is reserved for future use.
ppData
points to a pointer in which is returned a host-accessible
pointer to the beginning of the mapped range.
This pointer minus offset
must be aligned to at least
VkPhysicalDeviceLimits
::minMemoryMapAlignment
.
It is an application error to call vkMapMemory
on a memory object that
is already mapped.
![]() | Note |
---|---|
|
vkMapMemory
does not check whether the device memory is currently in
use before returning the host-accessible pointer.
The application must guarantee that any previously submitted command that
writes to this range has completed before the host reads from or writes to
that range, and that any previously submitted command that reads from that
range has completed before the host writes to that region (see
here for details on fulfilling
such a guarantee).
If the device memory was allocated without the
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
set, these guarantees must be
made for an extended range: the application must round down the start of
the range to the nearest multiple of
VkPhysicalDeviceLimits
::nonCoherentAtomSize
, and round the end
of the range up to the nearest multiple of
VkPhysicalDeviceLimits
::nonCoherentAtomSize
.
While a range of device memory is mapped for host access, the application is responsible for synchronizing both device and host access to that memory range.
![]() | Note |
---|---|
It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on Synchronization and Cache Control as they are crucial to maintaining memory access ordering. |
Two commands are provided to enable applications to work with non-coherent
memory allocations: vkFlushMappedMemoryRanges
and
vkInvalidateMappedMemoryRanges
.
![]() | Note |
---|---|
If the memory object was created with the
|
To flush ranges of non-coherent memory from the host caches, call:
VkResult vkFlushMappedMemoryRanges( VkDevice device, uint32_t memoryRangeCount, const VkMappedMemoryRange* pMemoryRanges);
device
is the logical device that owns the memory ranges.
memoryRangeCount
is the length of the pMemoryRanges
array.
pMemoryRanges
is a pointer to an array of
VkMappedMemoryRange
structures describing the memory ranges to
flush.
vkFlushMappedMemoryRanges
must be used to guarantee that host writes
to non-coherent memory are visible to the device.
It must be called after the host writes to non-coherent memory have
completed and before command buffers that will read or write any of those
memory locations are submitted to a queue.
![]() | Note |
---|---|
Unmapping non-coherent memory does not implicitly flush the mapped memory, and host writes that have not been flushed may not ever be visible to the device. |
To invalidate ranges of non-coherent memory from the host caches, call:
VkResult vkInvalidateMappedMemoryRanges( VkDevice device, uint32_t memoryRangeCount, const VkMappedMemoryRange* pMemoryRanges);
device
is the logical device that owns the memory ranges.
memoryRangeCount
is the length of the pMemoryRanges
array.
pMemoryRanges
is a pointer to an array of
VkMappedMemoryRange
structures describing the memory ranges to
invalidate.
vkInvalidateMappedMemoryRanges
must be used to guarantee that device
writes to non-coherent memory are visible to the host.
It must be called after command buffers that execute and flush (via memory
barriers) the device writes have completed, and before the host will read or
write any of those locations.
If a range of non-coherent memory is written by the host and then
invalidated without first being flushed, its contents are undefined.
![]() | Note |
---|---|
Mapping non-coherent memory does not implicitly invalidate the mapped memory, and device writes that have not been invalidated must be made visible before the host reads or overwrites them. |
The VkMappedMemoryRange
structure is defined as:
typedef struct VkMappedMemoryRange { VkStructureType sType; const void* pNext; VkDeviceMemory memory; VkDeviceSize offset; VkDeviceSize size; } VkMappedMemoryRange;
sType
is the type of this structure.
pNext
is NULL
or a pointer to an extension-specific structure.
memory
is the memory object to which this range belongs.
offset
is the zero-based byte offset from the beginning of the
memory object.
size
is either the size of range, or VK_WHOLE_SIZE
to affect
the range from offset
to the end of the current mapping of the
allocation.
![]() | editing-note |
---|---|
TODO (Tobias) - There’s a circular section reference between this next section and the synchronization section. The information is all covered by both places, but it seems a bit weird to have them reference each other. Not sure how to resolve it. |
Host-visible memory types that advertise the
VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
property still require
memory barriers between host and
device in order to be coherent, but do not require additional cache
management operations to achieve coherency.
For host writes to be seen by subsequent command buffer operations, a
pipeline barrier from a source of VK_ACCESS_HOST_WRITE_BIT
and
VK_PIPELINE_STAGE_HOST_BIT
to a destination of the relevant device
pipeline stages and
access types must be performed.
Note that such a barrier is performed
implicitly upon each command
buffer submission, so an explicit barrier is only rarely needed (e.g. if a
command buffer waits upon an event signaled by the host, where the host
wrote some data after submission).
A pipeline barrier is required to make writes visible to subsequent reads
on the host.
To unmap a memory object once host access to it is no longer needed by the application, call:
void vkUnmapMemory( VkDevice device, VkDeviceMemory memory);
device
is the logical device that owns the memory.
memory
is the memory object to be unmapped.
If the memory object is allocated from a heap with the
VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
bit set, that object’s backing
memory may be provided by the implementation lazily.
The actual committed size of the memory may initially be as small as zero
(or as large as the requested size), and monotonically increases as
additional memory is needed.
A memory type with this flag set is only allowed to be bound to a
VkImage
whose usage flags include
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
.
![]() | Note |
---|---|
Using lazily allocated memory objects for framebuffer attachments that are not needed once a render pass instance has completed may allow some implementations to never allocate memory for such attachments. |
To determine the amount of lazily-allocated memory that is currently committed for a memory object, call:
void vkGetDeviceMemoryCommitment( VkDevice device, VkDeviceMemory memory, VkDeviceSize* pCommittedMemoryInBytes);
device
is the logical device that owns the memory.
memory
is the memory object being queried.
pCommittedMemoryInBytes
is a pointer to a VkDeviceSize
value in which the number of bytes currently committed is returned, on
success.
The implementation may update the commitment at any time, and the value returned by this query may be out of date.
The implementation guarantees to allocate any committed memory from the heapIndex indicated by the memory type that the memory object was created with.