Vulkan.Core10.Memory

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 the contents of data protected memory objects, even if those memory objects were previously freed.

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.

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.

Many protected memory implementations involve complex hardware and system software support, and often have additional and much lower limits on the number of simultaneous protected memory allocations (from memory types with the MEMORY_PROPERTY_PROTECTED_BIT property) than for non-protected memory allocations. These limits can be system-wide, and depend on a variety of factors outside of the Vulkan implementation, so they cannot be queried in Vulkan. Applications should use as few allocations as possible from such memory types by suballocating aggressively, and be prepared for allocation failure even when there is apparently plenty of capacity remaining in the memory heap. As a guideline, the Vulkan conformance test suite requires that at least 80 minimum-size allocations can exist concurrently when no other uses of protected memory are active in the system.

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.

If the memoryTypeIndex belongs to a heap with the MEMORY_HEAP_TILE_MEMORY_BIT_QCOM bit included in its properties, this allocation is backed by tile memory, which is an on device cache. Unlike other heaps, allocations out of the tile memory will always have a starting address at the start of the heap and its contents are aliased with all other DeviceMemory objects bound to the same range while executing within the same tile memory scope.

If the PhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pageableDeviceLocalMemory feature is enabled, memory allocations made from a heap that includes MEMORY_HEAP_DEVICE_LOCAL_BIT in MemoryHeap::flags may be transparently moved to host-local memory allowing multiple applications to share device-local memory. If there is no space left in device-local memory when this new allocation is made, other allocations may be moved out transparently to make room. The operating system will determine which allocations to move to device-local memory or host-local memory based on platform-specific criteria. To help the operating system make good choices, the application should set the appropriate memory priority with MemoryPriorityAllocateInfoEXT and adjust it as necessary with setDeviceMemoryPriorityEXT. Higher priority allocations will moved to device-local memory first.

Memory allocations made on heaps without the MEMORY_HEAP_DEVICE_LOCAL_BIT property will not be transparently promoted to device-local memory by the operating system.

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

• If the tileMemoryHeap feature is not enabled, pAllocateInfo->memoryTypeIndex must not identify a memory type that corresponds to a MemoryHeap with the MEMORY_HEAP_TILE_MEMORY_BIT_QCOM property

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

• The device must have been created with at least 1 queue

Return Codes

Success

• SUCCESS

Failure

• ERROR_INVALID_EXTERNAL_HANDLE

• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, 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.

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

VK_VERSION_1_0, 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.

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

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.

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.

Calling mapMemory is equivalent to calling mapMemory2 with an empty pNext chain.

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

• MEMORY_MAP_PLACED_BIT_EXT must not be set in flags

Valid Usage (Implicit)

• device must be a valid Device handle

• memory must be a valid DeviceMemory handle

• flags must be a valid combination of MemoryMapFlagBits values

• 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_MEMORY_MAP_FAILED

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, 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

Description

Calling unmapMemory is equivalent to calling unmapMemory2 with an empty pNext chain and flags set to zero.

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

VK_VERSION_1_0, 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.

The first synchronization scope includes all host operations that happened-before it, as defined by the host memory model.

Some systems allow writes that do not directly integrate with the host memory model; these have to be synchronized by the application manually. One example of this is non-temporal store instructions on x86; to ensure these happen-before submission, applications should call _mm_sfence().

The second synchronization scope is empty.

The first access scope includes host writes to the specified memory ranges.

When a host write to a memory location is made available in this way, each whole aligned set of nonCoherentAtomSize bytes that the memory location exists in will also be made available as if they were written by the host. For example, with a nonCoherentAtomSize of 128, if an application writes to the first byte of a memory object via a host mapping, the first 128 bytes of the memory object will be made available by this command. While the value of the following 127 bytes will be unchanged, this does count as an access for the purpose of synchronization, so care must be taken to avoid data races.

The second access scope is empty.

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.

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_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, 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.

The first synchronization scope includes all host operations that happened-before it, as defined by the host memory model.

This function does not synchronize with device operations directly - other host synchronization operations that depend on device operations such as waitForFences must be executed beforehand. So for any non-coherent device write to be made visible to the host, there has to be a dependency chain along the following lines:

1. Device write

2. Device memory barrier including host reads in its second scope

3. Signal on the device (e.g. a fence signal operation)

4. Wait on the host (e.g. waitForFences)

5. invalidateMappedMemoryRanges

The second synchronization scope includes all host operations that happen-after it, as defined by the host memory model.

The first access scope is empty.

The second access scope includes host reads to the specified memory ranges.

When a device write to a memory location is made visible to the host in this way, each whole aligned set of nonCoherentAtomSize bytes that the memory location exists in will also be made visible as if they were written by the device. For example, with a nonCoherentAtomSize of 128, if an application writes to the first byte of a memory object on the device, the first 128 bytes of the memory object will be made visible by this command. While the value of the following 127 bytes will be unchanged, this does count as an access for the purpose of synchronization, so care must be taken to avoid data races.

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, 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

VK_VERSION_1_0, 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 a 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

• ImportMemoryZirconHandleInfoFUCHSIA with a non-zero handleType value

• ImportMemoryBufferCollectionFUCHSIA

• ImportScreenBufferInfoQNX with a non-NULL buffer value

• ImportMemoryMetalHandleInfoEXT with a non-zero handleType 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.

If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT, 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.

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, it must affect the following per-process values:

• PhysicalDeviceLimits::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. If the parameters define an export operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, implementations should not strictly follow memoryTypeIndex. Instead, they should modify the allocation internally to use the required memory type for the application’s given usage. This is because for an export operation, there is currently no way for the application to know the memory type index before allocating.

Valid Usage

• If the parameters do not define an import or export operation, allocationSize must be greater than 0

• The parameters must not define more than one import operation

• If the parameters define an export operation and the handle type is not EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID , allocationSize must be greater than 0

• If the parameters define an import operation from an BufferCollectionFUCHSIA, and MemoryDedicatedAllocateInfo::buffer is present and non-NULL, ImportMemoryBufferCollectionFUCHSIA::collection and ImportMemoryBufferCollectionFUCHSIA::index must match BufferCollectionBufferCreateInfoFUCHSIA::collection and BufferCollectionBufferCreateInfoFUCHSIA::index, respectively, of the BufferCollectionBufferCreateInfoFUCHSIA structure used to create the MemoryDedicatedAllocateInfo::buffer

• If the parameters define an import operation from an BufferCollectionFUCHSIA, and MemoryDedicatedAllocateInfo::image is present and non-NULL, ImportMemoryBufferCollectionFUCHSIA::collection and ImportMemoryBufferCollectionFUCHSIA::index must match BufferCollectionImageCreateInfoFUCHSIA::collection and BufferCollectionImageCreateInfoFUCHSIA::index, respectively, of the BufferCollectionImageCreateInfoFUCHSIA structure used to create the MemoryDedicatedAllocateInfo::image

• If the parameters define an import operation from an BufferCollectionFUCHSIA, allocationSize must match MemoryRequirements::size value retrieved by getImageMemoryRequirements or getBufferMemoryRequirements for image-based or buffer-based collections respectively

• If the parameters define an import operation from an BufferCollectionFUCHSIA, the pNext chain must 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 from an BufferCollectionFUCHSIA and MemoryDedicatedAllocateInfo::image is not NULL_HANDLE, the image must be created with a BufferCollectionImageCreateInfoFUCHSIA structure chained to its ImageCreateInfo::pNext pointer

• If the parameters define an import operation from an BufferCollectionFUCHSIA and MemoryDedicatedAllocateInfo::buffer is not NULL_HANDLE, the buffer must be created with a BufferCollectionBufferCreateInfoFUCHSIA structure chained to its BufferCreateInfo::pNext pointer

• If the parameters define an import operation from an BufferCollectionFUCHSIA, memoryTypeIndex must be from BufferCollectionPropertiesFUCHSIA as retrieved by getBufferCollectionPropertiesFUCHSIA

• 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 by getPhysicalDeviceExternalBufferProperties in 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, and any of the handle types specified in ExportMemoryAllocateInfo::handleTypes require a dedicated allocation, as reported by getPhysicalDeviceExternalTensorPropertiesARM in ExternalTensorPropertiesARM::externalMemoryProperties.externalMemoryFeatures, the pNext chain must include a MemoryDedicatedAllocateInfoTensorARM structure with its tensor 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, 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 the mask 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 or EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, 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 protectedMemory 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

• If the parameters define an export operation, the handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext does not include a MemoryDedicatedAllocateInfo structure, allocationSize must be greater than 0

• If the parameters define an export operation, the handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with buffer set to a valid Buffer object, 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, AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE or AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER

• 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 the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, PhysicalDeviceExternalMemoryScreenBufferFeaturesQNX::screenBufferImport must be enabled

• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, allocationSize must be the size returned by getScreenBufferPropertiesQNX for the QNX Screen buffer

• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, memoryTypeIndex must be one of those returned by getScreenBufferPropertiesQNX for the QNX Screen buffer

• If the parameters define an import operation, the external handle is a QNX Screen buffer, and the pNext chain includes a MemoryDedicatedAllocateInfo with image that is not NULL_HANDLE, the QNX Screen’s buffer must be a valid QNX Screen buffer

• If the parameters define an import operation, the external handle is an QNX Screen 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 getScreenBufferPropertiesQNX in ScreenBufferFormatPropertiesQNX::format for the QNX Screen buffer

• If the parameters define an import operation, the external handle is a QNX Screen 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 QNX Screen buffer’s Screen_buffer must be identical

• If the parameters define an import operation and the external handle is a EXTERNAL_MEMORY_HANDLE_TYPE_MTLTEXTURE_BIT_EXT, then pNext must include a MemoryDedicatedAllocateInfo with image that is not NULL_HANDLE

• If the parameters define an import operation, the external handle is a Metal MTLTexture, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, the width, height, array layer dimensions, and mipmap levels of image and the Metal MTLTexture’s must be identical

• If the parameters define an import operation, the external handle is a Metal MTLTexture, and the pNext chain includes a MemoryDedicatedAllocateInfo structure with image that is not NULL_HANDLE, allocationSize must be 0

• 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

• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of memoryTypeIndex must be an index identifying a memory type from the memoryTypeBits field of the MemoryZirconHandlePropertiesFUCHSIA structure populated by a call to getMemoryZirconHandlePropertiesFUCHSIA

• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of allocationSize must be greater than 0

• If the parameters define an import operation and the external handle type is EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the value of allocationSize must be less than or equal to the size of the VMO as determined by zx_vmo_get_size(handle) where handle is the VMO handle to the imported external memory

• If the pNext chain includes a ExportMetalObjectCreateInfoEXT structure, its exportObjectType member must be EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT

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, ExportMetalObjectCreateInfoEXT, ImportAndroidHardwareBufferInfoANDROID, ImportMemoryBufferCollectionFUCHSIA, ImportMemoryFdInfoKHR, ImportMemoryHostPointerInfoEXT, ImportMemoryMetalHandleInfoEXT, ImportMemoryWin32HandleInfoKHR, ImportMemoryWin32HandleInfoNV, ImportMemoryZirconHandleInfoFUCHSIA, ImportMetalBufferInfoEXT, VkImportNativeBufferInfoOHOS, ImportScreenBufferInfoQNX, MemoryAllocateFlagsInfo, MemoryDedicatedAllocateInfo, MemoryDedicatedAllocateInfoTensorARM, MemoryOpaqueCaptureAddressAllocateInfo, or MemoryPriorityAllocateInfoEXT

• The sType value of each structure in the pNext chain must be unique, with the exception of structures of type ExportMetalObjectCreateInfoEXT

See Also

VK_VERSION_1_0, 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

• offset must be a multiple of PhysicalDeviceLimits::nonCoherentAtomSize

• If size is equal to WHOLE_SIZE, the end of the current mapping of memory must either be a multiple of PhysicalDeviceLimits::nonCoherentAtomSize bytes from the beginning of the memory object, or be equal to the end of the memory object

• 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

VK_VERSION_1_0, DeviceMemory, DeviceSize, StructureType, flushMappedMemoryRanges, invalidateMappedMemoryRanges

VkMemoryMapFlagBits - Bitmask specifying additional parameters of a memory map

Description

• MEMORY_MAP_PLACED_BIT_EXT requests that the implementation place the memory map at the virtual address specified by the application via MemoryMapPlacedInfoEXT::pPlacedAddress, replacing any existing mapping at that address. This flag must not be used with mapMemory as there is no way to specify the placement address.

See Also

VK_VERSION_1_0, MemoryMapFlags