VkMemoryAllocateInfo(3)

# VkMemoryAllocateInfo(3) Manual Page

## Name

VkMemoryAllocateInfo - Structure containing parameters of a memory allocation

## C Specification

The `VkMemoryAllocateInfo` structure is defined as:

    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 an extension-specific 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

An instance of the VkMemoryAllocateInfo structure defines a memory import operation if the `pNext` chain contains an instance of one of the following structures:

- VkImportMemoryWin32HandleInfoKHR with 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

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.

When performing a memory import operation, it is the responsibility of the application to ensure the external handles meet all valid usage requirements. However, implementations must perform sufficient validation of external handles 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`.

Valid Usage

- If the `pNext` chain contains an instance of `VkExportMemoryAllocateInfo`, 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 contain an instance of VkMemoryDedicatedAllocateInfo or VkDedicatedAllocationMemoryAllocateInfoNV with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE.

- If the `pNext` chain contains an instance of VkExportMemoryAllocateInfo, it must not contain an instance of VkExportMemoryAllocateInfoNV or VkExportMemoryWin32HandleInfoNV.

- If the `pNext` chain contains an instance of VkImportMemoryWin32HandleInfoKHR, it must not contain an instance of VkImportMemoryWin32HandleInfoNV.

- 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_KHR`, then the values of `allocationSize` and `memoryTypeIndex` must match those specified when the memory object 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 VkMemoryAllocateFlagsInfo must match that specified when the memory object 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 vkAllocateMemory must match the list of physical devices that comprise the logical device on which the memory 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 vkGetMemoryWin32HandlePropertiesKHR.

- 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_KHR` or `VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR`, then the values of `allocationSize` and `memoryTypeIndex` must match those specified when the memory object being imported was created.

- 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` must match the size reported in the memory requirements of the `image` or `buffer` member of the instance of `VkDedicatedAllocationMemoryAllocateInfoNV` included in the `pNext` chain.

- 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 external handle 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 vkGetMemoryFdPropertiesKHR.

- If the protected memory feature is not enabled, the `VkMemoryAllocateInfo`::`memoryTypeIndex` must not indicate a memory type that reports `VK_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 vkGetMemoryHostPointerPropertiesEXT

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

- If the parameters define an import operation and the external handle is a host pointer, the `pNext` chain must not contain an instance of VkDedicatedAllocationMemoryAllocateInfoNV with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE.

- If the parameters define an import operation and the external handle is a host pointer, the `pNext` chain must not contain an instance of VkMemoryDedicatedAllocateInfo with either its `image` or `buffer` field set to a value other than VK_NULL_HANDLE.

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

- 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 contain an instance of VkMemoryDedicatedAllocateInfo 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`.

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

- If the parameters do not define an import operation, and the `pNext` chain contains an instance of `VkExportMemoryAllocateInfo` with `VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID` included in its `handleTypes` member, and the `pNext` contains an instance of VkMemoryDedicatedAllocateInfo with `image` not equal to VK_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 an instance of 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_COLOR_OUTPUT` 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 an instance of 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.

- If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes an instance of VkMemoryDedicatedAllocateInfo 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.

- If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes an instance of VkMemoryDedicatedAllocateInfo 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.

- If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes an instance of VkMemoryDedicatedAllocateInfo 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.

- If the parameters define an import operation, the external handle is an Android hardware buffer, and the `pNext` chain includes an instance of VkMemoryDedicatedAllocateInfo 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`.

- If VkMemoryOpaqueCaptureAddressAllocateInfoKHR::`opaqueCaptureAddress` is not zero, `VkMemoryAllocateFlagsInfo`::`flags` must include `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR`

- If `VkMemoryAllocateFlagsInfo`::`flags` includes `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR`, the bufferDeviceAddressCaptureReplay feature must be enabled

- If `VkMemoryAllocateFlagsInfo`::`flags` includes `VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT_KHR`, the bufferDeviceAddress feature must be enabled

- If the `pNext` chain contains an instance of `VkImportMemoryHostPointerInfoEXT`, VkMemoryOpaqueCaptureAddressAllocateInfoKHR::`opaqueCaptureAddress` must be zero

- If the parameters define an import operation, VkMemoryOpaqueCaptureAddressAllocateInfoKHR::`opaqueCaptureAddress` must be zero

Valid Usage (Implicit)

- `sType` must be `VK_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 VkDedicatedAllocationMemoryAllocateInfoNV, VkExportMemoryAllocateInfo, VkExportMemoryAllocateInfoNV, VkExportMemoryWin32HandleInfoKHR, VkExportMemoryWin32HandleInfoNV, VkImportAndroidHardwareBufferInfoANDROID, VkImportMemoryFdInfoKHR, VkImportMemoryHostPointerInfoEXT, VkImportMemoryWin32HandleInfoKHR, VkImportMemoryWin32HandleInfoNV, VkMemoryAllocateFlagsInfo, VkMemoryDedicatedAllocateInfo, VkMemoryOpaqueCaptureAddressAllocateInfoKHR, or VkMemoryPriorityAllocateInfoEXT

- Each `sType` member in the `pNext` chain must be unique

## See Also

`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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.