vkAllocateMemory - Allocate device memory

Description

Allocations returned by allocateMemory are guaranteed to meet any alignment requirement of 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 with the following constraint:

• The contents of unprotected memory must not be a function of data protected memory objects, even if those memory objects were previously freed.

Note

The contents of memory allocated by one application should not be a function of data from protected memory objects of another application, even if those memory objects were previously freed.

The maximum number of valid memory allocations that can exist simultaneously within a Device may be restricted by implementation- or platform-dependent limits. The maxMemoryAllocationCount feature describes the number of allocations that can exist simultaneously before encountering these internal limits.

Note

For historical reasons, if maxMemoryAllocationCount is exceeded, some implementations may return ERROR_TOO_MANY_OBJECTS. Exceeding this limit will result in undefined behavior, and an application should not rely on the use of the returned error code in order to identify when the limit is reached.

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 ERROR_OUT_OF_DEVICE_MEMORY must be returned. This limit is advertised in PhysicalDeviceMaintenance3Properties::maxMemoryAllocationSize.

The cumulative memory size allocated to a heap can be limited by the size of the specified heap. In such cases, allocated memory is tracked on a per-device and per-heap basis. Some platforms allow overallocation into other heaps. The overallocation behavior can be specified through the VK_AMD_memory_overallocation_behavior extension.

Valid Usage

• pAllocateInfo->allocationSize must be less than or equal to PhysicalDeviceMemoryProperties::memoryHeaps[memindex].size where memindex = PhysicalDeviceMemoryProperties::memoryTypes[pAllocateInfo->memoryTypeIndex].heapIndex as returned by getPhysicalDeviceMemoryProperties for the PhysicalDevice that device was created from

• pAllocateInfo->memoryTypeIndex must be less than PhysicalDeviceMemoryProperties::memoryTypeCount as returned by getPhysicalDeviceMemoryProperties for the PhysicalDevice that device was created from
• If the deviceCoherentMemory feature is not enabled, pAllocateInfo->memoryTypeIndex must not identify a memory type supporting MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
• There must be less than PhysicalDeviceLimits::maxMemoryAllocationCount device memory allocations currently allocated on the device.

Valid Usage (Implicit)

• device must be a valid Device handle

• pAllocateInfo must be a valid pointer to a valid MemoryAllocateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pMemory must be a valid pointer to a DeviceMemory handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INVALID_EXTERNAL_HANDLE
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

See Also

AllocationCallbacks, Device, DeviceMemory, MemoryAllocateInfo

A convenience wrapper to make a compatible pair of calls to allocateMemory and freeMemory

To ensure that freeMemory is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkFreeMemory - Free device memory

Description

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 in the pending state. Memory can be freed whilst still bound to resources, but those resources must not be used afterwards. Freeing a memory object releases the reference it held, if any, to its payload. If there are still any bound images or buffers, the memory object’s payload may not be immediately released by the implementation, but must be released by the time all bound images and buffers have been destroyed. Once all references to a payload are 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.

Note

As described below, host writes are not implicitly flushed when the memory object is unmapped, but the implementation must guarantee that writes that have not been flushed do not affect any other memory.

Valid Usage

• All submitted commands that refer to memory (via images or buffers) must have completed execution

Valid Usage (Implicit)

• device must be a valid Device handle

• If memory is not NULL_HANDLE, memory must be a valid DeviceMemory handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If memory is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to memory must be externally synchronized

See Also

AllocationCallbacks, Device, DeviceMemory

vkMapMemory - Map a memory object into application address space

Description

After a successful call to mapMemory the memory object memory is considered to be currently host mapped.

Note

It is an application error to call mapMemory on a memory object that is already host mapped.

Note

mapMemory will fail if the implementation is unable to allocate an appropriately sized contiguous virtual address range, e.g. due to virtual address space fragmentation or platform limits. In such cases, mapMemory must return ERROR_MEMORY_MAP_FAILED. The application can improve the likelihood of success by reducing the size of the mapped range and/or removing unneeded mappings using unmapMemory.

mapMemory 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 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 PhysicalDeviceLimits::nonCoherentAtomSize, and round the end of the range up to the nearest multiple of PhysicalDeviceLimits::nonCoherentAtomSize.

While a range of device memory is host mapped, 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.

Valid Usage

• memory must not be currently host mapped

• offset must be less than the size of memory
• If size is not equal to WHOLE_SIZE, size must be greater than 0
• If size is not equal to WHOLE_SIZE, size must be less than or equal to the size of the memory minus offset
• memory must have been created with a memory type that reports MEMORY_PROPERTY_HOST_VISIBLE_BIT
• memory must not have been allocated with multiple instances

Valid Usage (Implicit)

• device must be a valid Device handle

• memory must be a valid DeviceMemory handle
• flags must be 0
• ppData must be a valid pointer to a pointer value
• memory must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to memory must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_MEMORY_MAP_FAILED

See Also

Device, DeviceMemory, DeviceSize, MemoryMapFlags

A convenience wrapper to make a compatible pair of calls to mapMemory and unmapMemory

To ensure that unmapMemory is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkUnmapMemory - Unmap a previously mapped memory object

Valid Usage

• memory must be currently host mapped

Valid Usage (Implicit)

• device must be a valid Device handle

• memory must be a valid DeviceMemory handle
• memory must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to memory must be externally synchronized

See Also

Device, DeviceMemory

vkFlushMappedMemoryRanges - Flush mapped memory ranges

Description

flushMappedMemoryRanges guarantees that host writes to the memory ranges described by pMemoryRanges are made available to the host memory domain, such that they can be made available to the device memory domain via memory domain operations using the ACCESS_HOST_WRITE_BIT access type.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is flushed if any byte in that set has been written by the host since it was first host mapped, or the last time it was flushed. If pMemoryRanges includes sets of nonCoherentAtomSize bytes where no bytes have been written by the host, those bytes must not be flushed.

Unmapping non-coherent memory does not implicitly flush the host mapped memory, and host writes that have not been flushed may not ever be visible to the device. However, implementations must ensure that writes that have not been flushed do not become visible to any other memory.

Note

The above guarantee avoids a potential memory corruption in scenarios where host writes to a mapped memory object have not been flushed before the memory is unmapped (or freed), and the virtual address range is subsequently reused for a different mapping (or memory allocation).

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, MappedMemoryRange

vkInvalidateMappedMemoryRanges - Invalidate ranges of mapped memory objects

Description

invalidateMappedMemoryRanges guarantees that device writes to the memory ranges described by pMemoryRanges, which have been made available to the host memory domain using the ACCESS_HOST_WRITE_BIT and ACCESS_HOST_READ_BIT access types, are made visible to the host. If a range of non-coherent memory is written by the host and then invalidated without first being flushed, its contents are undefined.

Within each range described by pMemoryRanges, each set of nonCoherentAtomSize bytes in that range is invalidated if any byte in that set has been written by the device since it was first host mapped, or the last time it was invalidated.

Note

Mapping non-coherent memory does not implicitly invalidate that memory.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, MappedMemoryRange

vkGetDeviceMemoryCommitment - Query the current commitment for a VkDeviceMemory

Description

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.

Valid Usage (Implicit)

See Also

Device, DeviceMemory, DeviceSize

VkMemoryAllocateInfo - Structure containing parameters of a memory allocation

Description

The internal data of an allocated device memory object must include a reference to implementation-specific resources, referred to as the memory object’s payload. Applications can also import and export that internal data to and from device memory objects to share data between Vulkan instances and other compatible APIs. A MemoryAllocateInfo structure defines a memory import operation if its pNext chain includes one of the following structures:

• ImportMemoryWin32HandleInfoKHR with non-zero handleType value
• ImportMemoryFdInfoKHR with a non-zero handleType value
• ImportMemoryHostPointerInfoEXT with a non-zero handleType value
• ImportAndroidHardwareBufferInfoANDROID with a non-NULL buffer value

If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, allocationSize is ignored. The implementation must query the size of these allocations from the OS.

Whether device memory objects constructed via a memory import operation hold a reference to their payload depends on the properties of the handle type used to perform the import, as defined below for each valid handle type. Importing memory must not modify the content of the memory. Implementations must ensure that importing memory does not enable the importing Vulkan instance to access any memory or resources in other Vulkan instances other than that corresponding to the memory object imported. Implementations must also ensure accessing imported memory which has not been initialized does not allow the importing Vulkan instance to obtain data from the exporting Vulkan instance or vice-versa.

Note

How exported and imported memory is isolated is left to the implementation, but applications should be aware that such isolation may prevent implementations from placing multiple exportable memory objects in the same physical or virtual page. Hence, applications should avoid creating many small external memory objects whenever possible.

Importing memory must not increase overall heap usage within a system. However, they must affect the following per-process values: * PhysicalDeviceMaintenance3Properties::maxMemoryAllocationCount * PhysicalDeviceMemoryBudgetPropertiesEXT::heapUsage

When performing a memory import operation, it is the responsibility of the application to ensure the external handles and their associated payloads meet all valid usage requirements. However, implementations must perform sufficient validation of external handles and payloads to ensure that the operation results in a valid memory object which will not cause program termination, device loss, queue stalls, or corruption of other resources when used as allowed according to its allocation parameters. If the external handle provided does not meet these requirements, the implementation must fail the memory import operation with the error code ERROR_INVALID_EXTERNAL_HANDLE.

Valid Usage

• If the pNext chain includes a ExportMemoryAllocateInfo structure, and any of the handle types specified in ExportMemoryAllocateInfo::handleTypes require a dedicated allocation, as reported by getPhysicalDeviceImageFormatProperties2 in ExternalImageFormatProperties::externalMemoryProperties.externalMemoryFeatures or ExternalBufferProperties::externalMemoryProperties.externalMemoryFeatures, the pNext chain must include a MemoryDedicatedAllocateInfo or DedicatedAllocationMemoryAllocateInfoNV structure with either its image or buffer member set to a value other than NULL_HANDLE.

• If the pNext chain includes a ExportMemoryAllocateInfo structure, it must not include a ExportMemoryAllocateInfoNV or ExportMemoryWin32HandleInfoNV structure
• If the pNext chain includes a ImportMemoryWin32HandleInfoKHR structure, it must not include a ImportMemoryWin32HandleInfoNV structure
• If the parameters define an import operation, the external handle specified was created by the Vulkan API, and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR, then the values of allocationSize and memoryTypeIndex must match those specified when the payload being imported was created.
• If the parameters define an import operation and the external handle specified was created by the Vulkan API, the device mask specified by MemoryAllocateFlagsInfo must match that specified when the payload being imported was allocated.
• If the parameters define an import operation and the external handle specified was created by the Vulkan API, the list of physical devices that comprise the logical device passed to allocateMemory must match the list of physical devices that comprise the logical device on which the payload was originally allocated.
• If the parameters define an import operation and the external handle is an NT handle or a global share handle created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by getMemoryWin32HandlePropertiesKHR
• If the parameters define an import operation, the external handle was created by the Vulkan API, and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR or EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR, then the values of allocationSize and memoryTypeIndex must match those specified when the payload being imported was created.
• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, allocationSize must match the size specified when creating the Direct3D 12 heap from which the payload was extracted.
• If the parameters define an import operation and the external handle is a POSIX file descriptor created outside of the Vulkan API, the value of memoryTypeIndex must be one of those returned by getMemoryFdPropertiesKHR
• If the protected memory feature is not enabled, the MemoryAllocateInfo::memoryTypeIndex must not indicate a memory type that reports MEMORY_PROPERTY_PROTECTED_BIT
• If the parameters define an import operation and the external handle is a host pointer, the value of memoryTypeIndex must be one of those returned by getMemoryHostPointerPropertiesEXT
• If the parameters define an import operation and the external handle is a host pointer, allocationSize must be an integer multiple of PhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment
• If the parameters define an import operation and the external handle is a host pointer, the pNext chain must not include a DedicatedAllocationMemoryAllocateInfoNV structure with either its image or buffer field set to a value other than NULL_HANDLE
• If the parameters define an import operation and the external handle is a host pointer, the pNext chain must not include a MemoryDedicatedAllocateInfo structure with either its image or buffer field set to a value other than NULL_HANDLE
• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, allocationSize must be the size returned by getAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer
• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext chain does not include a MemoryDedicatedAllocateInfo structure or MemoryDedicatedAllocateInfo::image is NULL_HANDLE, the Android hardware buffer must have a AHardwareBuffer_Desc::format of AHARDWAREBUFFER_FORMAT_BLOB and a AHardwareBuffer_Desc::usage that includes AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER
• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, memoryTypeIndex must be one of those returned by getAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer
• If the parameters do not define an import operation, and the pNext chain includes a ExportMemoryAllocateInfo structure with EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID included in its handleTypes member, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image not equal to NULL_HANDLE, then allocationSize must be 0, otherwise allocationSize must be greater than 0
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo with image that is not NULL_HANDLE, the Android hardware buffer’s AHardwareBuffer::usage must include at least one of AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER or AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo with image that is not NULL_HANDLE, the format of image must be FORMAT_UNDEFINED or the format returned by getAndroidHardwareBufferPropertiesANDROID in AndroidHardwareBufferFormatPropertiesANDROID::format for the Android hardware buffer
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, the width, height, and array layer dimensions of image and the Android hardware buffer’s AHardwareBuffer_Desc must be identical
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, and the Android hardware buffer’s AHardwareBuffer::usage includes AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have a complete mipmap chain
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, and the Android hardware buffer’s AHardwareBuffer::usage does not include AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have exactly one mipmap level
• If the parameters define an import operation, the external handle is an Android hardware buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, each bit set in the usage of image must be listed in AHardwareBuffer Usage Equivalence, and if there is a corresponding AHARDWAREBUFFER_USAGE bit listed that bit must be included in the Android hardware buffer’s AHardwareBuffer_Desc::usage
• If MemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress is not zero, MemoryAllocateFlagsInfo::flags must include MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
• If MemoryAllocateFlagsInfo::flags includes MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the bufferDeviceAddressCaptureReplay feature must be enabled
• If MemoryAllocateFlagsInfo::flags includes MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT, the bufferDeviceAddress feature must be enabled
• If the pNext chain includes a ImportMemoryHostPointerInfoEXT structure, MemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress must be zero
• If the parameters define an import operation, MemoryOpaqueCaptureAddressAllocateInfo::opaqueCaptureAddress must be zero

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DedicatedAllocationMemoryAllocateInfoNV, ExportMemoryAllocateInfo, ExportMemoryAllocateInfoNV, ExportMemoryWin32HandleInfoKHR, ExportMemoryWin32HandleInfoNV, ImportAndroidHardwareBufferInfoANDROID, ImportMemoryFdInfoKHR, ImportMemoryHostPointerInfoEXT, ImportMemoryWin32HandleInfoKHR, ImportMemoryWin32HandleInfoNV, MemoryAllocateFlagsInfo, MemoryDedicatedAllocateInfo, MemoryOpaqueCaptureAddressAllocateInfo, or MemoryPriorityAllocateInfoEXT
• The sType value of each struct in the pNext chain must be unique

See Also

DeviceSize, StructureType, allocateMemory

VkMappedMemoryRange - Structure specifying a mapped memory range

Valid Usage

• memory must be currently host mapped

• If size is not equal to WHOLE_SIZE, offset and size must specify a range contained within the currently mapped range of memory
• If size is equal to WHOLE_SIZE, offset must be within the currently mapped range of memory
• If size is equal to WHOLE_SIZE, the end of the current mapping of memory must be a multiple of PhysicalDeviceLimits::nonCoherentAtomSize bytes from the beginning of the memory object
• offset must be a multiple of PhysicalDeviceLimits::nonCoherentAtomSize
• If size is not equal to WHOLE_SIZE, size must either be a multiple of PhysicalDeviceLimits::nonCoherentAtomSize, or offset plus size must equal the size of memory

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_MAPPED_MEMORY_RANGE

• pNext must be NULL
• memory must be a valid DeviceMemory handle

See Also

DeviceMemory, DeviceSize, StructureType, flushMappedMemoryRanges, invalidateMappedMemoryRanges

VkMemoryMapFlags - Reserved for future use

Description

MemoryMapFlags is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

mapMemory