VkMemoryAllocateInfo(3)

# VkMemoryAllocateInfo(3) Manual Page

## Name

VkMemoryAllocateInfo - Structure containing parameters of a memory allocation

Loading… please wait.

## C Specification

The `VkMemoryAllocateInfo` structure is defined as:

    // Provided by VK_VERSION_1_0
    typedef struct VkMemoryAllocateInfo {
        VkStructureType    sType;
        const void*        pNext;
        VkDeviceSize       allocationSize;
        uint32_t           memoryTypeIndex;
    } VkMemoryAllocateInfo;

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `allocationSize` is the size of the allocation in bytes.

- `memoryTypeIndex` is an index identifying a memory type from the `memoryTypes` array of the VkPhysicalDeviceMemoryProperties structure.

## 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 `VkMemoryAllocateInfo` structure defines a memory import operation if its `pNext` chain includes one of the following structures:

- VkImportMemoryWin32HandleInfoKHR with a non-zero `handleType` value

- VkImportMemoryFdInfoKHR with a non-zero `handleType` value

- VkImportMemoryHostPointerInfoEXT with a non-zero `handleType` value

- VkImportAndroidHardwareBufferInfoANDROID with a non-`NULL` `buffer` value

- VkImportMemoryZirconHandleInfoFUCHSIA with a non-zero `handleType` value

- VkImportMemoryBufferCollectionFUCHSIA

If the parameters define an import operation and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT`, `VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT`, or `VK_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, it must affect the following per-process values:

- VkPhysicalDeviceMaintenance3Properties::`maxMemoryAllocationCount`

- VkPhysicalDeviceMemoryBudgetPropertiesEXT::`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 `VK_ERROR_INVALID_EXTERNAL_HANDLE`. If the parameters define an export operation and the external handle type is `VK_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 client to know the memory type index before allocating.

Valid Usage

- VUID-VkMemoryAllocateInfo-None-06657
  The parameters must not define more than one import operation

- VUID-VkMemoryAllocateInfo-allocationSize-07897
  If the parameters do not define an import or export operation, `allocationSize` must be greater than `0`

- VUID-VkMemoryAllocateInfo-allocationSize-07899
  If the parameters define an export operation and the handle type is not `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, `allocationSize` must be greater than `0`

- VUID-VkMemoryAllocateInfo-buffer-06380
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA, and VkMemoryDedicatedAllocateInfo::`buffer` is present and non-NULL, VkImportMemoryBufferCollectionFUCHSIA::`collection` and VkImportMemoryBufferCollectionFUCHSIA::`index` must match VkBufferCollectionBufferCreateInfoFUCHSIA::`collection` and VkBufferCollectionBufferCreateInfoFUCHSIA::`index`, respectively, of the VkBufferCollectionBufferCreateInfoFUCHSIA structure used to create the VkMemoryDedicatedAllocateInfo::`buffer`

- VUID-VkMemoryAllocateInfo-image-06381
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA, and VkMemoryDedicatedAllocateInfo::`image` is present and non-NULL, VkImportMemoryBufferCollectionFUCHSIA::`collection` and VkImportMemoryBufferCollectionFUCHSIA::`index` must match VkBufferCollectionImageCreateInfoFUCHSIA::`collection` and VkBufferCollectionImageCreateInfoFUCHSIA::`index`, respectively, of the VkBufferCollectionImageCreateInfoFUCHSIA structure used to create the VkMemoryDedicatedAllocateInfo::`image`

- VUID-VkMemoryAllocateInfo-allocationSize-06382
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA, `allocationSize` must match VkMemoryRequirements::`size` value retrieved by vkGetImageMemoryRequirements or vkGetBufferMemoryRequirements for image-based or buffer-based collections respectively

- VUID-VkMemoryAllocateInfo-pNext-06383
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA, the `pNext` chain must include a VkMemoryDedicatedAllocateInfo structure with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE

- VUID-VkMemoryAllocateInfo-image-06384
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA and VkMemoryDedicatedAllocateInfo::`image` is not VK_NULL_HANDLE, the `image` must be created with a VkBufferCollectionImageCreateInfoFUCHSIA structure chained to its VkImageCreateInfo::`pNext` pointer

- VUID-VkMemoryAllocateInfo-buffer-06385
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA and VkMemoryDedicatedAllocateInfo::`buffer` is not VK_NULL_HANDLE, the `buffer` must be created with a VkBufferCollectionBufferCreateInfoFUCHSIA structure chained to its VkBufferCreateInfo::`pNext` pointer

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-06386
  If the parameters define an import operation from an VkBufferCollectionFUCHSIA, `memoryTypeIndex` must be from VkBufferCollectionPropertiesFUCHSIA as retrieved by vkGetBufferCollectionPropertiesFUCHSIA

- VUID-VkMemoryAllocateInfo-pNext-00639
  If the `pNext` chain includes a `VkExportMemoryAllocateInfo` structure, and any of the handle types specified in `VkExportMemoryAllocateInfo`::`handleTypes` require a dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 in `VkExternalImageFormatProperties`::`externalMemoryProperties.externalMemoryFeatures` or `VkExternalBufferProperties`::`externalMemoryProperties.externalMemoryFeatures`, the `pNext` chain must include a `VkMemoryDedicatedAllocateInfo` or `VkDedicatedAllocationMemoryAllocateInfoNV` structure with either its `image` or `buffer` member set to a value other than VK_NULL_HANDLE

- VUID-VkMemoryAllocateInfo-pNext-00640
  If the `pNext` chain includes a VkExportMemoryAllocateInfo structure, it must not include a VkExportMemoryAllocateInfoNV or VkExportMemoryWin32HandleInfoNV structure

- VUID-VkMemoryAllocateInfo-pNext-00641
  If the `pNext` chain includes a VkImportMemoryWin32HandleInfoKHR structure, it must not include a VkImportMemoryWin32HandleInfoNV structure

- VUID-VkMemoryAllocateInfo-allocationSize-01742
  If the parameters define an import operation, the external handle specified was created by the Vulkan API, and the external handle type is `VK_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

- VUID-VkMemoryAllocateInfo-None-00643
  If the parameters define an import operation and the external handle specified was created by the Vulkan API, the device mask specified by VkMemoryAllocateFlagsInfo must match the mask specified when the payload being imported was allocated

- VUID-VkMemoryAllocateInfo-None-00644
  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 vkAllocateMemory must match the list of physical devices that comprise the logical device on which the payload was originally allocated

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-00645
  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 vkGetMemoryWin32HandlePropertiesKHR

- VUID-VkMemoryAllocateInfo-allocationSize-01743
  If the parameters define an import operation, the external handle was created by the Vulkan API, and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT` or `VK_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

- VUID-VkMemoryAllocateInfo-allocationSize-00647
  If the parameters define an import operation and the external handle type is `VK_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

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-00648
  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 vkGetMemoryFdPropertiesKHR

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-01872
  If the `protectedMemory` feature is not enabled, the `VkMemoryAllocateInfo`::`memoryTypeIndex` must not indicate a memory type that reports `VK_MEMORY_PROPERTY_PROTECTED_BIT`

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744
  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 vkGetMemoryHostPointerPropertiesEXT

- VUID-VkMemoryAllocateInfo-allocationSize-01745
  If the parameters define an import operation and the external handle is a host pointer, `allocationSize` must be an integer multiple of `VkPhysicalDeviceExternalMemoryHostPropertiesEXT`::`minImportedHostPointerAlignment`

- VUID-VkMemoryAllocateInfo-pNext-02805
  If the parameters define an import operation and the external handle is a host pointer, the `pNext` chain must not include a VkDedicatedAllocationMemoryAllocateInfoNV structure with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE

- VUID-VkMemoryAllocateInfo-pNext-02806
  If the parameters define an import operation and the external handle is a host pointer, the `pNext` chain must not include a VkMemoryDedicatedAllocateInfo structure with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE

- VUID-VkMemoryAllocateInfo-allocationSize-02383
  If the parameters define an import operation and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, `allocationSize` must be the size returned by vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer

- VUID-VkMemoryAllocateInfo-pNext-02384
  If the parameters define an import operation and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, and the `pNext` chain does not include a VkMemoryDedicatedAllocateInfo structure or VkMemoryDedicatedAllocateInfo::`image` is VK_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`

- VUID-VkMemoryAllocateInfo-memoryTypeIndex-02385
  If the parameters define an import operation and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, `memoryTypeIndex` must be one of those returned by vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer

- VUID-VkMemoryAllocateInfo-pNext-01874
  If the parameters do not define an import operation, and the `pNext` chain includes a `VkExportMemoryAllocateInfo` structure with `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID` included in its `handleTypes` member, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `image` not equal to VK_NULL_HANDLE, then `allocationSize` must be `0`

- VUID-VkMemoryAllocateInfo-pNext-07900
  If the parameters define an export operation, the handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, and the `pNext` does not include a VkMemoryDedicatedAllocateInfo structure, `allocationSize` must be greater than `0`

- VUID-VkMemoryAllocateInfo-pNext-07901
  If the parameters define an export operation, the handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID`, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `buffer` set to a valid VkBuffer object, `allocationSize` must be greater than `0`

- VUID-VkMemoryAllocateInfo-pNext-02386
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo with `image` that is not VK_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`

- VUID-VkMemoryAllocateInfo-pNext-02387
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo with `image` that is not VK_NULL_HANDLE, the format of `image` must be `VK_FORMAT_UNDEFINED` or the format returned by vkGetAndroidHardwareBufferPropertiesANDROID in VkAndroidHardwareBufferFormatPropertiesANDROID::`format` for the Android hardware buffer

- VUID-VkMemoryAllocateInfo-pNext-02388
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `image` that is not VK_NULL_HANDLE, the width, height, and array layer dimensions of `image` and the Android hardware buffer’s `AHardwareBuffer_Desc` must be identical

- VUID-VkMemoryAllocateInfo-pNext-02389
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `image` that is not VK_NULL_HANDLE, and the Android hardware buffer’s AHardwareBuffer::`usage` includes `AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE`, the `image` must have a complete mipmap chain

- VUID-VkMemoryAllocateInfo-pNext-02586
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `image` that is not VK_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

- VUID-VkMemoryAllocateInfo-pNext-02390
  If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes a VkMemoryDedicatedAllocateInfo structure with `image` that is not VK_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`

- VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03329
  If VkMemoryOpaqueCaptureAddressAllocateInfo::`opaqueCaptureAddress` is not zero, `VkMemoryAllocateFlagsInfo`::`flags` must include `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT`

- VUID-VkMemoryAllocateInfo-flags-03330
  If `VkMemoryAllocateFlagsInfo`::`flags` includes `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT`, the `bufferDeviceAddressCaptureReplay` feature must be enabled

- VUID-VkMemoryAllocateInfo-flags-03331
  If `VkMemoryAllocateFlagsInfo`::`flags` includes `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT`, the `bufferDeviceAddress` feature must be enabled

- VUID-VkMemoryAllocateInfo-pNext-03332
  If the `pNext` chain includes a `VkImportMemoryHostPointerInfoEXT` structure, VkMemoryOpaqueCaptureAddressAllocateInfo::`opaqueCaptureAddress` must be zero

- VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03333
  If the parameters define an import operation, VkMemoryOpaqueCaptureAddressAllocateInfo::`opaqueCaptureAddress` must be zero

- VUID-VkMemoryAllocateInfo-None-04749
  If the parameters define an import operation and the external handle type is `VK_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 VkMemoryZirconHandlePropertiesFUCHSIA structure populated by a call to vkGetMemoryZirconHandlePropertiesFUCHSIA

- VUID-VkMemoryAllocateInfo-allocationSize-07902
  If the parameters define an import operation and the external handle type is `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA`, the value of `allocationSize` must be greater than `0`

- VUID-VkMemoryAllocateInfo-allocationSize-07903
  If the parameters define an import operation and the external handle type is `VK_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

- VUID-VkMemoryAllocateInfo-pNext-06780
  If the `pNext` chain includes a VkExportMetalObjectCreateInfoEXT structure, its `exportObjectType` member must be `VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT`

Valid Usage (Implicit)

- VUID-VkMemoryAllocateInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO`

- VUID-VkMemoryAllocateInfo-pNext-pNext
  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 VkDedicatedAllocationMemoryAllocateInfoNV, VkExportMemoryAllocateInfo, VkExportMemoryAllocateInfoNV, VkExportMemoryWin32HandleInfoKHR, VkExportMemoryWin32HandleInfoNV, VkExportMetalObjectCreateInfoEXT, VkImportAndroidHardwareBufferInfoANDROID, VkImportMemoryBufferCollectionFUCHSIA, VkImportMemoryFdInfoKHR, VkImportMemoryHostPointerInfoEXT, VkImportMemoryWin32HandleInfoKHR, VkImportMemoryWin32HandleInfoNV, VkImportMemoryZirconHandleInfoFUCHSIA, VkImportMetalBufferInfoEXT, VkMemoryAllocateFlagsInfo, VkMemoryDedicatedAllocateInfo, VkMemoryOpaqueCaptureAddressAllocateInfo, or VkMemoryPriorityAllocateInfoEXT

- VUID-VkMemoryAllocateInfo-sType-unique
  The `sType` value of each struct in the `pNext` chain must be unique, with the exception of structures of type VkExportMetalObjectCreateInfoEXT

## See Also

VK_VERSION_1_0, VkDeviceSize, VkStructureType, vkAllocateMemory

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0