// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ [[memory]] = Memory Allocation Vulkan memory is broken up into two categories, _host memory_ and _device memory_. [[memory-host]] == Host Memory Host memory is memory needed by the Vulkan implementation for non-device-visible storage. [NOTE] .Note ==== This memory may: be used to store the implementation's representation and state of Vulkan objects. ==== [[memory-allocation]] Vulkan provides applications the opportunity to perform host memory allocations on behalf of the Vulkan implementation. If this feature is not used, the implementation will perform its own memory allocations. Since most memory allocations are off the critical path, this is not meant as a performance feature. Rather, this can: be useful for certain embedded systems, for debugging purposes (e.g. putting a guard page after all host allocations), or for memory allocation logging. [open,refpage='VkAllocationCallbacks',desc='Structure containing callback function pointers for memory allocation',type='structs'] -- Allocators are provided by the application as a pointer to a sname:VkAllocationCallbacks structure: include::{generated}/api/structs/VkAllocationCallbacks.txt[] * pname:pUserData is a value to be interpreted by the implementation of the callbacks. When any of the callbacks in sname:VkAllocationCallbacks are called, the Vulkan implementation will pass this value as the first parameter to the callback. This value can: vary each time an allocator is passed into a command, even when the same object takes an allocator in multiple commands. * pname:pfnAllocation is a pointer to an application-defined memory allocation function of type tlink:PFN_vkAllocationFunction. * pname:pfnReallocation is a pointer to an application-defined memory reallocation function of type tlink:PFN_vkReallocationFunction. * pname:pfnFree is a pointer to an application-defined memory free function of type tlink:PFN_vkFreeFunction. * pname:pfnInternalAllocation is a pointer to an application-defined function that is called by the implementation when the implementation makes internal allocations, and it is of type tlink:PFN_vkInternalAllocationNotification. * pname:pfnInternalFree is a pointer to an application-defined function that is called by the implementation when the implementation frees internal allocations, and it is of type tlink:PFN_vkInternalFreeNotification. .Valid Usage **** * [[VUID-VkAllocationCallbacks-pfnAllocation-00632]] pname:pfnAllocation must: be a valid pointer to a valid user-defined tlink:PFN_vkAllocationFunction * [[VUID-VkAllocationCallbacks-pfnReallocation-00633]] pname:pfnReallocation must: be a valid pointer to a valid user-defined tlink:PFN_vkReallocationFunction * [[VUID-VkAllocationCallbacks-pfnFree-00634]] pname:pfnFree must: be a valid pointer to a valid user-defined tlink:PFN_vkFreeFunction * [[VUID-VkAllocationCallbacks-pfnInternalAllocation-00635]] If either of pname:pfnInternalAllocation or pname:pfnInternalFree is not `NULL`, both must: be valid callbacks **** include::{generated}/validity/structs/VkAllocationCallbacks.txt[] -- [open,refpage='PFN_vkAllocationFunction',desc='Application-defined memory allocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] -- The type of pname:pfnAllocation is: include::{generated}/api/funcpointers/PFN_vkAllocationFunction.txt[] * pname:pUserData is the value specified for slink:VkAllocationCallbacks::pname:pUserData in the allocator specified by the application. * pname:size is the size in bytes of the requested allocation. * pname:alignment is the requested alignment of the allocation in bytes and must: be a power of two. * pname:allocationScope is a elink:VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described <>. [[vkAllocationFunction_return_rules]] If pname:pfnAllocation is unable to allocate the requested memory, it must: return `NULL`. If the allocation was successful, it must: return a valid pointer to memory allocation containing at least pname:size bytes, and with the pointer value being a multiple of pname:alignment. [NOTE] .Note ==== Correct Vulkan operation cannot: be assumed if the application does not follow these rules. For example, pname:pfnAllocation (or pname:pfnReallocation) could cause termination of running Vulkan instance(s) on a failed allocation for debugging purposes, either directly or indirectly. In these circumstances, it cannot: be assumed that any part of any affected slink:VkInstance objects are going to operate correctly (even flink:vkDestroyInstance), and the application must: ensure it cleans up properly via other means (e.g. process termination). ==== If pname:pfnAllocation returns `NULL`, and if the implementation is unable to continue correct processing of the current command without the requested allocation, it must: treat this as a run-time error, and generate ename:VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command in which the condition was detected, as described in <>. If the implementation is able to continue correct processing of the current command without the requested allocation, then it may: do so, and must: not generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed allocation. -- [open,refpage='PFN_vkReallocationFunction',desc='Application-defined memory reallocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] -- The type of pname:pfnReallocation is: include::{generated}/api/funcpointers/PFN_vkReallocationFunction.txt[] * pname:pUserData is the value specified for slink:VkAllocationCallbacks::pname:pUserData in the allocator specified by the application. * pname:pOriginal must: be either `NULL` or a pointer previously returned by pname:pfnReallocation or pname:pfnAllocation of the same allocator. * pname:size is the size in bytes of the requested allocation. * pname:alignment is the requested alignment of the allocation in bytes and must: be a power of two. * pname:allocationScope is a elink:VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described <>. pname:pfnReallocation must: return an allocation with enough space for pname:size bytes, and the contents of the original allocation from bytes zero to [eq]#min(original size, new size) - 1# must: be preserved in the returned allocation. If pname:size is larger than the old size, the contents of the additional space are undefined:. If satisfying these requirements involves creating a new allocation, then the old allocation should: be freed. If pname:pOriginal is `NULL`, then pname:pfnReallocation must: behave equivalently to a call to tlink:PFN_vkAllocationFunction with the same parameter values (without pname:pOriginal). If pname:size is zero, then pname:pfnReallocation must: behave equivalently to a call to tlink:PFN_vkFreeFunction with the same pname:pUserData parameter value, and pname:pMemory equal to pname:pOriginal. If pname:pOriginal is non-`NULL`, the implementation must: ensure that pname:alignment is equal to the pname:alignment used to originally allocate pname:pOriginal. If this function fails and pname:pOriginal is non-`NULL` the application must: not free the old allocation. pname:pfnReallocation must: follow the same <>. -- [open,refpage='PFN_vkFreeFunction',desc='Application-defined memory free function',type='funcpointers',xrefs='VkAllocationCallbacks'] -- The type of pname:pfnFree is: include::{generated}/api/funcpointers/PFN_vkFreeFunction.txt[] * pname:pUserData is the value specified for slink:VkAllocationCallbacks::pname:pUserData in the allocator specified by the application. * pname:pMemory is the allocation to be freed. pname:pMemory may: be `NULL`, which the callback must: handle safely. If pname:pMemory is non-`NULL`, it must: be a pointer previously allocated by pname:pfnAllocation or pname:pfnReallocation. The application should: free this memory. -- [open,refpage='PFN_vkInternalAllocationNotification',desc='Application-defined memory allocation notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] -- The type of pname:pfnInternalAllocation is: include::{generated}/api/funcpointers/PFN_vkInternalAllocationNotification.txt[] * pname:pUserData is the value specified for slink:VkAllocationCallbacks::pname:pUserData in the allocator specified by the application. * pname:size is the requested size of an allocation. * pname:allocationType is a elink:VkInternalAllocationType value specifying the requested type of an allocation. * pname:allocationScope is a elink:VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described <>. This is a purely informational callback. -- [open,refpage='PFN_vkInternalFreeNotification',desc='Application-defined memory free notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] -- The type of pname:pfnInternalFree is: include::{generated}/api/funcpointers/PFN_vkInternalFreeNotification.txt[] * pname:pUserData is the value specified for slink:VkAllocationCallbacks::pname:pUserData in the allocator specified by the application. * pname:size is the requested size of an allocation. * pname:allocationType is a elink:VkInternalAllocationType value specifying the requested type of an allocation. * pname:allocationScope is a elink:VkSystemAllocationScope value specifying the allocation scope of the lifetime of the allocation, as described <>. -- [open,refpage='VkSystemAllocationScope',desc='Allocation scope',type='enums',xrefs='VkAllocationCallbacks'] -- [[memory-host-allocation-scope]] Each allocation has an _allocation scope_ which defines its lifetime and which object it is associated with. Possible values passed to the pname:allocationScope parameter of the callback functions specified by slink:VkAllocationCallbacks, indicating the allocation scope, are: include::{generated}/api/enums/VkSystemAllocationScope.txt[] * ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND specifies that the allocation is scoped to the duration of the Vulkan command. * ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT specifies that the allocation is scoped to the lifetime of the Vulkan object that is being created or used. * ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE specifies that the allocation is scoped to the lifetime of a sname:VkPipelineCache ifdef::VK_EXT_validation_cache[] or sname:VkValidationCacheEXT endif::VK_EXT_validation_cache[] object. * ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE specifies that the allocation is scoped to the lifetime of the Vulkan device. * ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE specifies that the allocation is scoped to the lifetime of the Vulkan instance. Most Vulkan commands operate on a single object, or there is a sole object that is being created or manipulated. When an allocation uses an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the object being created or manipulated. When an implementation requires host memory, it will make callbacks to the application using the most specific allocator and allocation scope available: * If an allocation is scoped to the duration of a command, the allocator will use the ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND allocation scope. The most specific allocator available is used: if the object being created or manipulated has an allocator, that object's allocator will be used, else if the parent sname:VkDevice has an allocator it will be used, else if the parent sname:VkInstance has an allocator it will be used. Else, * If an allocation is associated with an object of type ifdef::VK_EXT_validation_cache[] sname:VkValidationCacheEXT or endif::VK_EXT_validation_cache[] sname:VkPipelineCache, the allocator will use the ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE allocation scope. The most specific allocator available is used (cache, else device, else instance). Else, * If an allocation is scoped to the lifetime of an object, that object is being created or manipulated by the command, and that object's type is not sname:VkDevice or sname:VkInstance, the allocator will use an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT. The most specific allocator available is used (object, else device, else instance). Else, * If an allocation is scoped to the lifetime of a device, the allocator will use an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE. The most specific allocator available is used (device, else instance). Else, * If the allocation is scoped to the lifetime of an instance and the instance has an allocator, its allocator will be used with an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE. * Otherwise an implementation will allocate memory through an alternative mechanism that is unspecified. -- Objects that are allocated from pools do not specify their own allocator. When an implementation requires host memory for such an object, that memory is sourced from the object's parent pool's allocator. The application is not expected to handle allocating memory that is intended for execution by the host due to the complexities of differing security implementations across multiple platforms. The implementation will allocate such memory internally and invoke an application provided informational callback when these _internal allocations_ are allocated and freed. Upon allocation of executable memory, pname:pfnInternalAllocation will be called. Upon freeing executable memory, pname:pfnInternalFree will be called. An implementation will only call an informational callback for executable memory allocations and frees. [open,refpage='VkInternalAllocationType',desc='Allocation type',type='enums',xrefs='PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification'] -- The pname:allocationType parameter to the pname:pfnInternalAllocation and pname:pfnInternalFree functions may: be one of the following values: include::{generated}/api/enums/VkInternalAllocationType.txt[] * ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the allocation is intended for execution by the host. -- An implementation must: only make calls into an application-provided allocator during the execution of an API command. An implementation must: only make calls into an application-provided allocator from the same thread that called the provoking API command. The implementation should: not synchronize calls to any of the callbacks. If synchronization is needed, the callbacks must: provide it themselves. The informational callbacks are subject to the same restrictions as the allocation callbacks. If an implementation intends to make calls through a sname:VkAllocationCallbacks structure between the time a ftext:vkCreate* command returns and the time a corresponding ftext:vkDestroy* command begins, that implementation must: save a copy of the allocator before the ftext:vkCreate* command returns. The callback functions and any data structures they rely upon must: remain valid for the lifetime of the object they are associated with. If an allocator is provided to a ftext:vkCreate* command, a _compatible_ allocator must: be provided to the corresponding ftext:vkDestroy* command. Two sname:VkAllocationCallbacks structures are compatible if memory allocated with pname:pfnAllocation or pname:pfnReallocation in each can: be freed with pname:pfnReallocation or pname:pfnFree in the other. An allocator must: not be provided to a ftext:vkDestroy* command if an allocator was not provided to the corresponding ftext:vkCreate* command. If a non-`NULL` allocator is used, the pname:pfnAllocation, pname:pfnReallocation and pname:pfnFree members must: be non-`NULL` and point to valid implementations of the callbacks. An application can: choose to not provide informational callbacks by setting both pname:pfnInternalAllocation and pname:pfnInternalFree to `NULL`. pname:pfnInternalAllocation and pname:pfnInternalFree must: either both be `NULL` or both be non-`NULL`. If pname:pfnAllocation or pname:pfnReallocation fail, the implementation may: fail object creation and/or generate an ename:VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate. Allocation callbacks must: not call any Vulkan commands. The following sets of rules define when an implementation is permitted to call the allocator callbacks. pname:pfnAllocation or pname:pfnReallocation may: be called in the following situations: * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be allocated from any API command. * Allocations scoped to a command may: be allocated from any API command. * Allocations scoped to a sname:VkPipelineCache may: only be allocated from: ** fname:vkCreatePipelineCache ** fname:vkMergePipelineCaches for pname:dstCache ** fname:vkCreateGraphicsPipelines for pname:pipelineCache ** fname:vkCreateComputePipelines for pname:pipelineCache ifdef::VK_EXT_validation_cache[] * Allocations scoped to a sname:VkValidationCacheEXT may: only be allocated from: ** fname:vkCreateValidationCacheEXT ** fname:vkMergeValidationCachesEXT for pname:dstCache ** fname:vkCreateShaderModule for pname:validationCache in sname:VkShaderModuleValidationCacheCreateInfoEXT endif::VK_EXT_validation_cache[] * Allocations scoped to a sname:VkDescriptorPool may: only be allocated from: ** any command that takes the pool as a direct argument ** fname:vkAllocateDescriptorSets for the pname:descriptorPool member of its pname:pAllocateInfo parameter ** fname:vkCreateDescriptorPool * Allocations scoped to a sname:VkCommandPool may: only be allocated from: ** any command that takes the pool as a direct argument ** fname:vkCreateCommandPool ** fname:vkAllocateCommandBuffers for the pname:commandPool member of its pname:pAllocateInfo parameter ** any ftext:vkCmd* command whose pname:commandBuffer was allocated from that sname:VkCommandPool * Allocations scoped to any other object may: only be allocated in that object's ftext:vkCreate* command. pname:pfnFree may: be called in the following situations: * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be freed from any API command. * Allocations scoped to a command must: be freed by any API command which allocates such memory. * Allocations scoped to a sname:VkPipelineCache may: be freed from fname:vkDestroyPipelineCache. ifdef::VK_EXT_validation_cache[] * Allocations scoped to a sname:VkValidationCacheEXT may: be freed from fname:vkDestroyValidationCacheEXT. endif::VK_EXT_validation_cache[] * Allocations scoped to a sname:VkDescriptorPool may: be freed from ** any command that takes the pool as a direct argument * Allocations scoped to a sname:VkCommandPool may: be freed from: ** any command that takes the pool as a direct argument ** fname:vkResetCommandBuffer whose pname:commandBuffer was allocated from that sname:VkCommandPool * Allocations scoped to any other object may: be freed in that object's ftext:vkDestroy* command. * Any command that allocates host memory may: also free host memory of the same scope. [[memory-device]] == Device Memory _Device memory_ is memory that is visible to the device -- for example the contents of the image or buffer objects, which can: be natively used by the device. Memory properties of a physical device describe the memory heaps and memory types available. [open,refpage='vkGetPhysicalDeviceMemoryProperties',desc='Reports memory information for the specified physical device',type='protos'] -- To query memory properties, call: include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties.txt[] * pname:physicalDevice is the handle to the device to query. * pname:pMemoryProperties points to an instance of sname:VkPhysicalDeviceMemoryProperties structure in which the properties are returned. include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[] -- [open,refpage='VkPhysicalDeviceMemoryProperties',desc='Structure specifying physical device memory properties',type='structs'] -- The sname:VkPhysicalDeviceMemoryProperties structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties.txt[] * pname:memoryTypeCount is the number of valid elements in the pname:memoryTypes array. * pname:memoryTypes is an array of slink:VkMemoryType structures describing the _memory types_ that can: be used to access memory allocated from the heaps specified by pname:memoryHeaps. * pname:memoryHeapCount is the number of valid elements in the pname:memoryHeaps array. * pname:memoryHeaps is an array of slink:VkMemoryHeap structures describing the _memory heaps_ from which memory can: be allocated. The sname:VkPhysicalDeviceMemoryProperties structure describes a number of _memory heaps_ as well as a number of _memory types_ that can: be used to access memory allocated in those heaps. Each heap describes a memory resource of a particular size, and each memory type describes a set of memory properties (e.g. host cached vs uncached) that can: be used with a given memory heap. Allocations using a particular memory type will consume resources from the heap indicated by that memory type's heap index. More than one memory type may: share each heap, and the heaps and memory types provide a mechanism to advertise an accurate size of the physical memory resources while allowing the memory to be used with a variety of different properties. The number of memory heaps is given by pname:memoryHeapCount and is less than or equal to ename:VK_MAX_MEMORY_HEAPS. Each heap is described by an element of the pname:memoryHeaps array as a slink:VkMemoryHeap structure. The number of memory types available across all memory heaps is given by pname:memoryTypeCount and is less than or equal to ename:VK_MAX_MEMORY_TYPES. Each memory type is described by an element of the pname:memoryTypes array as a slink:VkMemoryType structure. At least one heap must: include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in slink:VkMemoryHeap::pname:flags. If there are multiple heaps that all have similar performance characteristics, they may: all include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT. In a unified memory architecture (UMA) system there is often only a single memory heap which is considered to be equally "`local`" to the host and to the device, and such an implementation must: advertise the heap as device-local. [[memory-device-bitmask-list]] Each memory type returned by flink:vkGetPhysicalDeviceMemoryProperties must: have its pname:propertyFlags set to one of the following values: * 0 * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | + ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | + ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT ifdef::VK_VERSION_1_1[] * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT | ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT endif::VK_VERSION_1_1[] There must: be at least one memory type with both the ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bits set in its pname:propertyFlags. There must: be at least one memory type with the ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set in its pname:propertyFlags. For each pair of elements *X* and *Y* returned in pname:memoryTypes, *X* must: be placed at a lower index position than *Y* if: * either the set of bit flags returned in the pname:propertyFlags member of *X* is a strict subset of the set of bit flags returned in the pname:propertyFlags member of *Y*. * or the pname:propertyFlags members of *X* and *Y* are equal, and *X* belongs to a memory heap with greater performance (as determined in an implementation-specific manner). [NOTE] .Note ==== There is no ordering requirement between *X* and *Y* elements for the case their pname:propertyFlags members are not in a subset relation. That potentially allows more than one possible way to order the same set of memory types. Notice that the <> is written in a valid order. But if instead ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the list would still be in a valid order. ==== This ordering requirement enables applications to use a simple search loop to select the desired memory type along the lines of: [source,c++] --------------------------------------------------- // Find a memory in `memoryTypeBitsRequirement` that includes all of `requiredProperties` int32_t findProperties(const VkPhysicalDeviceMemoryProperties* pMemoryProperties, uint32_t memoryTypeBitsRequirement, VkMemoryPropertyFlags requiredProperties) { const uint32_t memoryCount = pMemoryProperties->memoryTypeCount; for (uint32_t memoryIndex = 0; memoryIndex < memoryCount; ++memoryIndex) { const uint32_t memoryTypeBits = (1 << memoryIndex); const bool isRequiredMemoryType = memoryTypeBitsRequirement & memoryTypeBits; const VkMemoryPropertyFlags properties = pMemoryProperties->memoryTypes[memoryIndex].propertyFlags; const bool hasRequiredProperties = (properties & requiredProperties) == requiredProperties; if (isRequiredMemoryType && hasRequiredProperties) return static_cast(memoryIndex); } // failed to find memory type return -1; } // Try to find an optimal memory type, or if it does not exist try fallback memory type // `device` is the VkDevice // `image` is the VkImage that requires memory to be bound // `memoryProperties` properties as returned by vkGetPhysicalDeviceMemoryProperties // `requiredProperties` are the property flags that must be present // `optimalProperties` are the property flags that are preferred by the application VkMemoryRequirements memoryRequirements; vkGetImageMemoryRequirements(device, image, &memoryRequirements); int32_t memoryType = findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, optimalProperties); if (memoryType == -1) // not found; try fallback properties memoryType = findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, requiredProperties); --------------------------------------------------- include::{generated}/validity/structs/VkPhysicalDeviceMemoryProperties.txt[] -- ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [open,refpage='vkGetPhysicalDeviceMemoryProperties2',desc='Reports memory information for the specified physical device',type='protos'] -- To query memory properties, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties2.txt[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] ifdef::VK_KHR_get_physical_device_properties2[] include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[] endif::VK_KHR_get_physical_device_properties2[] * pname:physicalDevice is the handle to the device to query. * pname:pMemoryProperties points to an instance of sname:VkPhysicalDeviceMemoryProperties2 structure in which the properties are returned. fname:vkGetPhysicalDeviceMemoryProperties2 behaves similarly to flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return extended information in a pname:pNext chain of output structures. include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties2.txt[] -- [open,refpage='VkPhysicalDeviceMemoryProperties2',desc='Structure specifying physical device memory properties',type='structs'] -- The sname:VkPhysicalDeviceMemoryProperties2 structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2.txt[] ifdef::VK_KHR_get_physical_device_properties2[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[] endif::VK_KHR_get_physical_device_properties2[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memoryProperties is a structure of type slink:VkPhysicalDeviceMemoryProperties which is populated with the same values as in flink:vkGetPhysicalDeviceMemoryProperties. include::{generated}/validity/structs/VkPhysicalDeviceMemoryProperties2.txt[] -- endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [open,refpage='VkMemoryHeap',desc='Structure specifying a memory heap',type='structs'] -- The sname:VkMemoryHeap structure is defined as: include::{generated}/api/structs/VkMemoryHeap.txt[] * pname:size is the total memory size in bytes in the heap. * pname:flags is a bitmask of elink:VkMemoryHeapFlagBits specifying attribute flags for the heap. include::{generated}/validity/structs/VkMemoryHeap.txt[] -- [open,refpage='VkMemoryHeapFlagBits',desc='Bitmask specifying attribute flags for a heap',type='enums'] -- Bits which may: be set in slink:VkMemoryHeap::pname:flags, indicating attribute flags for the heap, are: include::{generated}/api/enums/VkMemoryHeapFlagBits.txt[] * ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT specifies that the heap corresponds to device local memory. Device local memory may: have different performance characteristics than host local memory, and may: support different memory property flags. ifdef::VK_KHR_device_group_creation[] * ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT specifies that in a logical device representing more than one physical device, there is a per-physical device instance of the heap memory. By default, an allocation from such a heap will be replicated to each physical device's instance of the heap. endif::VK_KHR_device_group_creation[] -- [open,refpage='VkMemoryHeapFlags',desc='Bitmask of VkMemoryHeapFlagBits',type='flags'] -- include::{generated}/api/flags/VkMemoryHeapFlags.txt[] tname:VkMemoryHeapFlags is a bitmask type for setting a mask of zero or more elink:VkMemoryHeapFlagBits. -- [open,refpage='VkMemoryType',desc='Structure specifying memory type',type='structs'] -- The sname:VkMemoryType structure is defined as: include::{generated}/api/structs/VkMemoryType.txt[] * pname:heapIndex describes which memory heap this memory type corresponds to, and must: be less than pname:memoryHeapCount from the slink:VkPhysicalDeviceMemoryProperties structure. * pname:propertyFlags is a bitmask of elink:VkMemoryPropertyFlagBits of properties for this memory type. include::{generated}/validity/structs/VkMemoryType.txt[] -- [open,refpage='VkMemoryPropertyFlagBits',desc='Bitmask specifying properties for a memory type',type='enums'] -- Bits which may: be set in slink:VkMemoryType::pname:propertyFlags, indicating properties of a memory heap, are: include::{generated}/api/enums/VkMemoryPropertyFlagBits.txt[] * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit specifies that memory allocated with this type is the most efficient for device access. This property will be set if and only if the memory type belongs to a heap with the ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set. * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit specifies that memory allocated with this type can: be mapped for host access using flink:vkMapMemory. * ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit specifies that the host cache management commands flink:vkFlushMappedMemoryRanges and flink:vkInvalidateMappedMemoryRanges are not needed to flush host writes to the device or make device writes visible to the host, respectively. * ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit specifies that memory allocated with this type is cached on the host. Host memory accesses to uncached memory are slower than to cached memory, however uncached memory is always host coherent. * ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit specifies that the memory type only allows device access to the memory. Memory types must: not have both ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. Additionally, the object's backing memory may: be provided by the implementation lazily as specified in <>. ifdef::VK_VERSION_1_1[] * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT bit specifies that the memory type only allows device access to the memory, and allows protected queue operations to access the memory. Memory types must: not have ename:VK_MEMORY_PROPERTY_PROTECTED_BIT set and any of ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set, or ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, or ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT set. endif::VK_VERSION_1_1[] -- [open,refpage='VkMemoryPropertyFlags',desc='Bitmask of VkMemoryPropertyFlagBits',type='flags'] -- include::{generated}/api/flags/VkMemoryPropertyFlags.txt[] tname:VkMemoryPropertyFlags is a bitmask type for setting a mask of zero or more elink:VkMemoryPropertyFlagBits. -- ifdef::VK_EXT_memory_budget[] [open,refpage='VkPhysicalDeviceMemoryBudgetPropertiesEXT',desc='Structure specifying physical device memory budget and usage',type='structs'] -- If the sname:VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is included in the pname:pNext chain of slink:VkPhysicalDeviceMemoryProperties2, it is filled with the current memory budgets and usages. The sname:VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceMemoryBudgetPropertiesEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:heapBudget is an array of memory budgets, with one element for each memory heap. A heap's budget is a rough estimate of how much memory the process can: allocate from that heap before allocations may: fail or cause performance degradation. The budget includes any currently allocated device memory. * pname:heapUsage is an array of memory usage, with one element for each memory heap. A heap's usage is an estimate of how much memory the process is currently using in that heap. The values returned in this structure are not invariant. The pname:heapBudget and pname:heapUsage values must: be zero for array elements greater than or equal to slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeapCount. The pname:heapBudget value must: be non-zero for array elements less than slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeapCount. The pname:heapBudget value must: be less than or equal to slink:VkMemoryHeap::pname:size for each heap. include::{generated}/validity/structs/VkPhysicalDeviceMemoryBudgetPropertiesEXT.txt[] -- endif::VK_EXT_memory_budget[] [open,refpage='VkDeviceMemory',desc='Opaque handle to a device memory object',type='handles'] -- A Vulkan device operates on data in device memory via memory objects that are represented in the API by a sname:VkDeviceMemory handle: include::{generated}/api/handles/VkDeviceMemory.txt[] -- [open,refpage='vkAllocateMemory',desc='Allocate device memory',type='protos'] -- To allocate memory objects, call: include::{generated}/api/protos/vkAllocateMemory.txt[] * pname:device is the logical device that owns the memory. * pname:pAllocateInfo is a pointer to an instance of the slink:VkMemoryAllocateInfo structure describing parameters of the allocation. A successful returned allocation must: use the requested parameters -- no substitution is permitted by the implementation. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pMemory is a pointer to a slink:VkDeviceMemory handle in which information about the allocated memory is returned. Allocations returned by fname:vkAllocateMemory 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. ifndef::VK_VERSION_1_1[] When memory is allocated, its contents are undefined:. endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1[] 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] .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. ==== endif::VK_VERSION_1_1[] The maximum number of valid memory allocations that can: exist simultaneously within a slink:VkDevice may: be restricted by implementation- or platform-dependent limits. If a call to flink:vkAllocateMemory would cause the total number of allocations to exceed these limits, such a call will fail and must: return ename:VK_ERROR_TOO_MANY_OBJECTS. The <> feature describes the number of allocations that can: exist simultaneously before encountering these internal limits. 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 ename:VK_ERROR_OUT_OF_DEVICE_MEMORY must: be returned. ifdef::VK_KHR_maintenance3[] This limit is advertised in slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationSize. endif::VK_KHR_maintenance3[] ifdef::VK_AMD_memory_overallocation_behavior[] 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 `<>` extension. endif::VK_AMD_memory_overallocation_behavior[] .Valid Usage **** * [[VUID-vkAllocateMemory-pAllocateInfo-01713]] pname:pAllocateInfo\->pname:allocationSize must: be less than or equal to slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps[pname:pAllocateInfo\->pname:memoryTypeIndex].pname:size as returned by flink:vkGetPhysicalDeviceMemoryProperties for the slink:VkPhysicalDevice that pname:device was created from. * [[VUID-vkAllocateMemory-pAllocateInfo-01714]] pname:pAllocateInfo\->pname:memoryTypeIndex must: be less than slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypeCount as returned by flink:vkGetPhysicalDeviceMemoryProperties for the slink:VkPhysicalDevice that pname:device was created from. **** include::{generated}/validity/protos/vkAllocateMemory.txt[] -- [open,refpage='VkMemoryAllocateInfo',desc='Structure containing parameters of a memory allocation',type='structs'] -- The sname:VkMemoryAllocateInfo structure is defined as: include::{generated}/api/structs/VkMemoryAllocateInfo.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:allocationSize is the size of the allocation in bytes * pname:memoryTypeIndex is an index identifying a memory type from the pname:memoryTypes array of the slink:VkPhysicalDeviceMemoryProperties structure ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[] An instance of the slink:VkMemoryAllocateInfo structure defines a memory import operation if the pname:pNext chain contains an instance of one of the following structures: ifdef::VK_KHR_external_memory_win32[] * slink:VkImportMemoryWin32HandleInfoKHR with non-zero pname:handleType value endif::VK_KHR_external_memory_win32[] ifdef::VK_KHR_external_memory_fd[] * slink:VkImportMemoryFdInfoKHR with a non-zero pname:handleType value endif::VK_KHR_external_memory_fd[] ifdef::VK_EXT_external_memory_host[] * slink:VkImportMemoryHostPointerInfoEXT with a non-zero pname:handleType value endif::VK_EXT_external_memory_host[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * slink:VkImportAndroidHardwareBufferInfoANDROID with a non-`NULL` pname:buffer value endif::VK_ANDROID_external_memory_android_hardware_buffer[] 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] .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 ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[] .Valid Usage **** ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-VkMemoryAllocateInfo-allocationSize-00638]] pname:allocationSize must: be greater than `0` endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_KHR_external_memory[] ifdef::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[] * [[VUID-VkMemoryAllocateInfo-pNext-00639]] If the pname:pNext chain contains an instance of sname:VkExportMemoryAllocateInfo, and any of the handle types specified in sname:VkExportMemoryAllocateInfo::pname:handleTypes require a dedicated allocation, as reported by flink:vkGetPhysicalDeviceImageFormatProperties2 in sname:VkExternalImageFormatProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures or sname:VkExternalBufferProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures, the pname:pNext chain must contain an instance of ifdef::VK_KHR_dedicated_allocation[slink:VkMemoryDedicatedAllocateInfo] ifdef::VK_KHR_dedicated_allocation[] ifdef::VK_NV_dedicated_allocation[or] endif::VK_KHR_dedicated_allocation[] ifdef::VK_NV_dedicated_allocation[slink:VkDedicatedAllocationMemoryAllocateInfoNV] with either its pname:image or pname:buffer field set to a value other than dlink:VK_NULL_HANDLE. endif::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[] endif::VK_KHR_external_memory[] ifdef::VK_KHR_external_memory[] ifdef::VK_NV_external_memory[] * [[VUID-VkMemoryAllocateInfo-pNext-00640]] If the pname:pNext chain contains an instance of slink:VkExportMemoryAllocateInfo, it must: not contain an instance of slink:VkExportMemoryAllocateInfoNV or slink:VkExportMemoryWin32HandleInfoNV. endif::VK_NV_external_memory[] endif::VK_KHR_external_memory[] ifdef::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[] * [[VUID-VkMemoryAllocateInfo-pNext-00641]] If the pname:pNext chain contains an instance of slink:VkImportMemoryWin32HandleInfoKHR, it must: not contain an instance of slink:VkImportMemoryWin32HandleInfoNV. endif::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[] ifdef::VK_KHR_external_memory_fd[] * [[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 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR, then the values of pname:allocationSize and pname:memoryTypeIndex must: match those specified when the memory object being imported was created. endif::VK_KHR_external_memory_fd[] ifdef::VK_KHR_external_memory+VK_KHR_device_group[] * [[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 slink:VkMemoryAllocateFlagsInfo must: match that specified when the memory object 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 flink:vkAllocateMemory must: match the list of physical devices that comprise the logical device on which the memory was originally allocated. endif::VK_KHR_external_memory+VK_KHR_device_group[] ifdef::VK_KHR_external_memory_win32[] * [[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 pname:memoryTypeIndex must: be one of those returned by flink: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 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR, then the values of pname:allocationSize and pname:memoryTypeIndex must: match those specified when the memory object being imported was created. * [[VUID-VkMemoryAllocateInfo-allocationSize-00646]] If the parameters define an import operation and the external handle type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, pname:allocationSize must: match the size reported in the memory requirements of the pname:image or pname:buffer member of the instance of sname:VkDedicatedAllocationMemoryAllocateInfoNV included in the pname:pNext chain. * [[VUID-VkMemoryAllocateInfo-allocationSize-00647]] If the parameters define an import operation and the external handle type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, pname:allocationSize must: match the size specified when creating the Direct3D 12 heap from which the external handle was extracted. endif::VK_KHR_external_memory_win32[] ifdef::VK_KHR_external_memory_fd[] * [[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 pname:memoryTypeIndex must: be one of those returned by flink:vkGetMemoryFdPropertiesKHR. endif::VK_KHR_external_memory_fd[] ifdef::VK_VERSION_1_1[] * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01872]] If the protected memory feature is not enabled, the sname:VkMemoryAllocateInfo::pname:memoryTypeIndex must: not indicate a memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT. endif::VK_VERSION_1_1[] ifdef::VK_EXT_external_memory_host[] * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744]] If the parameters define an import operation and the external handle is a host pointer, the value of pname:memoryTypeIndex must: be one of those returned by flink:vkGetMemoryHostPointerPropertiesEXT * [[VUID-VkMemoryAllocateInfo-allocationSize-01745]] If the parameters define an import operation and the external handle is a host pointer, pname:allocationSize must: be an integer multiple of sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment endif::VK_EXT_external_memory_host[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-VkMemoryAllocateInfo-allocationSize-02383]] If the parameters define an import operation and the external handle type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, pname:allocationSize must: be the size returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer. * [[VUID-VkMemoryAllocateInfo-pNext-02384]] If the parameters define an import operation and the external handle type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, and the pname:pNext chain does not contain an instance of slink:VkMemoryDedicatedAllocateInfo or slink:VkMemoryDedicatedAllocateInfo::pname:image is dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a code:AHardwareBuffer_Desc::code:format of code:AHARDWAREBUFFER_FORMAT_BLOB and a code:AHardwareBuffer_Desc::code:usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER. * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-02385]] If the parameters define an import operation and the external handle type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, pname:memoryTypeIndex must: be one of those returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android hardware buffer. * [[VUID-VkMemoryAllocateInfo-pNext-01874]] If the parameters do not define an import operation, and the pname:pNext chain contains an instance of sname:VkExportMemoryAllocateInfo with ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID included in its pname:handleTypes member, and the pname:pNext contains an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image not equal to dlink:VK_NULL_HANDLE, then pname:allocationSize must: be `0`, otherwise pname: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 pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, the Android hardware buffer's dlink:AHardwareBuffer::code:usage must: include at least one of code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE. * [[VUID-VkMemoryAllocateInfo-pNext-02387]] If the parameters define an import operation, the external handle is an Android hardware buffer, and the pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, the format of pname:image must: be ename:VK_FORMAT_UNDEFINED or the format returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID in slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname: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 pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, the width, height, and array layer dimensions of pname:image and the Android hardware buffer's code: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 pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, and the Android hardware buffer's dlink:AHardwareBuffer::code:usage includes code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname: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 pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, and the Android hardware buffer's dlink:AHardwareBuffer::code:usage does not include code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname: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 pname:pNext chain includes an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE, each bit set in the usage of pname:image must: be listed in <>, and if there is a corresponding code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in the Android hardware buffer's code:AHardwareBuffer_Desc::code:usage. endif::VK_ANDROID_external_memory_android_hardware_buffer[] **** include::{generated}/validity/structs/VkMemoryAllocateInfo.txt[] -- ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] [open,refpage='VkMemoryDedicatedAllocateInfo',desc='Specify a dedicated memory allocation resource',type='structs'] -- If the pname:pNext chain includes a sname:VkMemoryDedicatedAllocateInfo structure, then that structure includes a handle of the sole buffer or image resource that the memory can: be bound to. The sname:VkMemoryDedicatedAllocateInfo structure is defined as: include::{generated}/api/structs/VkMemoryDedicatedAllocateInfo.txt[] ifdef::VK_KHR_dedicated_allocation[] or the equivalent include::{generated}/api/structs/VkMemoryDedicatedAllocateInfoKHR.txt[] endif::VK_KHR_dedicated_allocation[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this memory will be bound to. * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this memory will be bound to. .Valid Usage **** * [[VUID-VkMemoryDedicatedAllocateInfo-image-01432]] At least one of pname:image and pname:buffer must: be dlink:VK_NULL_HANDLE * [[VUID-VkMemoryDedicatedAllocateInfo-image-01433]] If pname:image is not dlink:VK_NULL_HANDLE, sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the sname:VkMemoryRequirements::pname:size of the image * [[VUID-VkMemoryDedicatedAllocateInfo-image-01434]] If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: have been created without ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT set in sname:VkImageCreateInfo::pname:flags * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01435]] If pname:buffer is not dlink:VK_NULL_HANDLE, sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the sname:VkMemoryRequirements::pname:size of the buffer * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01436]] If pname:buffer is not dlink:VK_NULL_HANDLE, pname:buffer must: have been created without ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT set in slink:VkBufferCreateInfo::pname:flags ifdef::VK_KHR_external_memory_win32[] * [[VUID-VkMemoryDedicatedAllocateInfo-image-01876]] If pname:image is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation with handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the external handle was created by the Vulkan API, then the memory being imported must: also be a dedicated image allocation and pname:image must be identical to the image associated with the imported memory. * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01877]] If pname:buffer is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation with handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the external handle was created by the Vulkan API, then the memory being imported must: also be a dedicated buffer allocation and pname:buffer must be identical to the buffer associated with the imported memory. endif::VK_KHR_external_memory_win32[] ifdef::VK_KHR_external_memory_fd[] * [[VUID-VkMemoryDedicatedAllocateInfo-image-01878]] If pname:image is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation with handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory being imported must: also be a dedicated image allocation and pname:image must be identical to the image associated with the imported memory. * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01879]] If pname:buffer is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation with handle type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory being imported must: also be a dedicated buffer allocation and pname:buffer must be identical to the buffer associated with the imported memory. endif::VK_KHR_external_memory_fd[] ifdef::VK_KHR_sampler_ycbcr_conversion[] * [[VUID-VkMemoryDedicatedAllocateInfo-image-01797]] If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: not have been created with ename:VK_IMAGE_CREATE_DISJOINT_BIT set in slink:VkImageCreateInfo::pname:flags endif::VK_KHR_sampler_ycbcr_conversion[] **** include::{generated}/validity/structs/VkMemoryDedicatedAllocateInfo.txt[] -- endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] ifdef::VK_NV_dedicated_allocation[] [open,refpage='VkDedicatedAllocationMemoryAllocateInfoNV',desc='Specify a dedicated memory allocation resource',type='structs'] -- If the pname:pNext chain includes a sname:VkDedicatedAllocationMemoryAllocateInfoNV structure, then that structure includes a handle of the sole buffer or image resource that the memory can: be bound to. The sname:VkDedicatedAllocationMemoryAllocateInfoNV structure is defined as: include::{generated}/api/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this memory will be bound to. * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this memory will be bound to. .Valid Usage **** * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00649]] At least one of pname:image and pname:buffer must: be dlink:VK_NULL_HANDLE * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00650]] If pname:image is not dlink:VK_NULL_HANDLE, the image must: have been created with sname:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation equal to ename:VK_TRUE * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00651]] If pname:buffer is not dlink:VK_NULL_HANDLE, the buffer must: have been created with sname:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation equal to ename:VK_TRUE * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00652]] If pname:image is not dlink:VK_NULL_HANDLE, sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the sname:VkMemoryRequirements::pname:size of the image * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00653]] If pname:buffer is not dlink:VK_NULL_HANDLE, sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the sname:VkMemoryRequirements::pname:size of the buffer ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[] * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00654]] If pname:image is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation, the memory being imported must: also be a dedicated image allocation and pname:image must: be identical to the image associated with the imported memory. * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00655]] If pname:buffer is not dlink:VK_NULL_HANDLE and slink:VkMemoryAllocateInfo defines a memory import operation, the memory being imported must: also be a dedicated buffer allocation and pname:buffer must: be identical to the buffer associated with the imported memory. endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[] **** include::{generated}/validity/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[] -- endif::VK_NV_dedicated_allocation[] ifdef::VK_EXT_memory_priority[] [open,refpage='VkMemoryPriorityAllocateInfoEXT',desc='Specify a memory allocation priority',type='structs'] -- If the pname:pNext chain includes a sname:VkMemoryPriorityAllocateInfoEXT structure, then that structure includes a priority for the memory. The sname:VkMemoryPriorityAllocateInfoEXT structure is defined as: include::{generated}/api/structs/VkMemoryPriorityAllocateInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:priority is a floating-point value between `0` and `1`, indicating the priority of the allocation relative to other memory allocations. Larger values are higher priority. The granularity of the priorities is implementation-dependent. Memory allocations with higher priority may: be more likely to stay in device-local memory when the system is under memory pressure. If this structure is not included, it is as if the pname:priority value were `0.5`. .Valid Usage **** * [[VUID-VkMemoryPriorityAllocateInfoEXT-priority-02602]] pname:priority must: be between `0` and `1`, inclusive **** include::{generated}/validity/structs/VkMemoryPriorityAllocateInfoEXT.txt[] -- endif::VK_EXT_memory_priority[] ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] [open,refpage='VkExportMemoryAllocateInfo',desc='Specify exportable handle types for a device memory object',type='structs'] -- When allocating memory that may: be exported to another process or Vulkan instance, add a slink:VkExportMemoryAllocateInfo structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure, specifying the handle types that may: be exported. The slink:VkExportMemoryAllocateInfo structure is defined as: include::{generated}/api/structs/VkExportMemoryAllocateInfo.txt[] ifdef::VK_KHR_external_memory[] or the equivalent include::{generated}/api/structs/VkExportMemoryAllocateInfoKHR.txt[] endif::VK_KHR_external_memory[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:handleTypes is a bitmask of elink:VkExternalMemoryHandleTypeFlagBits specifying one or more memory handle types the application can: export from the resulting allocation. The application can: request multiple handle types for the same allocation. .Valid Usage **** * [[VUID-VkExportMemoryAllocateInfo-handleTypes-00656]] The bits in pname:handleTypes must: be supported and compatible, as reported by slink:VkExternalImageFormatProperties or slink:VkExternalBufferProperties. **** include::{generated}/validity/structs/VkExportMemoryAllocateInfo.txt[] -- endif::VK_VERSION_1_1,VK_KHR_external_memory[] ifdef::VK_KHR_external_memory_win32[] [open,refpage='VkExportMemoryWin32HandleInfoKHR',desc='Structure specifying additional attributes of Windows handles exported from a memory',type='structs'] -- To specify additional attributes of NT handles exported from a memory object, add the slink:VkExportMemoryWin32HandleInfoKHR structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkExportMemoryWin32HandleInfoKHR structure is defined as: include::{generated}/api/structs/VkExportMemoryWin32HandleInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:pAttributes is a pointer to a Windows code:SECURITY_ATTRIBUTES structure specifying security attributes of the handle. * pname:dwAccess is a code:DWORD specifying access rights of the handle. * pname:name is a NULL-terminated UTF-16 string to associate with the underlying resource referenced by NT handles exported from the created memory. If this structure is not present, or if pname:pAttributes is set to `NULL`, default security descriptor values will be used, and child processes created by the application will not inherit the handle, as described in the MSDN documentation for "`Synchronization Object Security and Access Rights`"^1^. Further, if the structure is not present, the access rights will be code:DXGI_SHARED_RESOURCE_READ | code:DXGI_SHARED_RESOURCE_WRITE for handles of the following types: ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT And code:GENERIC_ALL for handles of the following types: ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT 1:: https://msdn.microsoft.com/en-us/library/windows/desktop/ms686670.aspx .Valid Usage **** * [[VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657]] If slink:VkExportMemoryAllocateInfo::pname:handleTypes does not include ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, sname:VkExportMemoryWin32HandleInfoKHR must: not be in the pname:pNext chain of slink:VkMemoryAllocateInfo. **** include::{generated}/validity/structs/VkExportMemoryWin32HandleInfoKHR.txt[] -- [open,refpage='VkImportMemoryWin32HandleInfoKHR',desc='import Win32 memory created on the same physical device',type='structs'] -- To import memory from a Windows handle, add a slink:VkImportMemoryWin32HandleInfoKHR structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkImportMemoryWin32HandleInfoKHR structure is defined as: include::{generated}/api/structs/VkImportMemoryWin32HandleInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:handleType specifies the type of pname:handle or pname:name. * pname:handle is the external handle to import, or `NULL`. * pname:name is a NULL-terminated UTF-16 string naming the underlying memory resource to import, or `NULL`. Importing memory objects from Windows handles does not transfer ownership of the handle to the Vulkan implementation. For handle types defined as NT handles, the application must: release ownership using the code:CloseHandle system call when the handle is no longer needed. Applications can: import the same underlying memory into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance. In all cases, each import operation must: create a distinct sname:VkDeviceMemory object. .Valid Usage **** * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00658]] If pname:handleType is not `0`, it must: be supported for import, as reported by slink:VkExternalImageFormatProperties or slink:VkExternalBufferProperties. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-00659]] The memory from which pname:handle was exported, or the memory named by pname:name must: have been created on the same underlying physical device as pname:device. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00660]] If pname:handleType is not `0`, it must: be defined as an NT handle or a global share handle. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01439]] If pname:handleType is not ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, pname:name must: be `NULL`. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01440]] If pname:handleType is not `0` and pname:handle is `NULL`, pname:name must: name a valid memory resource of the type specified by pname:handleType. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00661]] If pname:handleType is not `0` and pname:name is `NULL`, pname:handle must: be a valid handle of the type specified by pname:handleType. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01441]] if pname:handle is not `NULL`, pname:name must be `NULL`. * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01518]] If pname:handle is not `NULL`, it must: obey any requirements listed for pname:handleType in <>. * [[VUID-VkImportMemoryWin32HandleInfoKHR-name-01519]] If pname:name is not `NULL`, it must: obey any requirements listed for pname:handleType in <>. **** include::{generated}/validity/structs/VkImportMemoryWin32HandleInfoKHR.txt[] -- [open,refpage='vkGetMemoryWin32HandleKHR',desc='Get a Windows HANDLE for a memory object',type='protos'] -- To export a Windows handle representing the underlying resources of a Vulkan device memory object, call: include::{generated}/api/protos/vkGetMemoryWin32HandleKHR.txt[] * pname:device is the logical device that created the device memory being exported. * pname:pGetWin32HandleInfo is a pointer to an instance of the slink:VkMemoryGetWin32HandleInfoKHR structure containing parameters of the export operation. * pname:pHandle will return the Windows handle representing the underlying resources of the device memory object. For handle types defined as NT handles, the handles returned by fname:vkGetMemoryWin32HandleKHR are owned by the application. To avoid leaking resources, the application must: release ownership of them using the code:CloseHandle system call when they are no longer needed. include::{generated}/validity/protos/vkGetMemoryWin32HandleKHR.txt[] -- [open,refpage='VkMemoryGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle semaphore export operation',type='structs'] -- The sname:VkMemoryGetWin32HandleInfoKHR structure is defined as: include::{generated}/api/structs/VkMemoryGetWin32HandleInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memory is the memory object from which the handle will be exported. * pname:handleType is the type of handle requested. The properties of the handle returned depend on the value of pname:handleType. See elink:VkExternalMemoryHandleTypeFlagBits for a description of the properties of the defined external memory handle types. .Valid Usage **** * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00662]] pname:handleType must: have been included in slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory was created. * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00663]] If pname:handleType is defined as an NT handle, flink:vkGetMemoryWin32HandleKHR must: be called no more than once for each valid unique combination of pname:memory and pname:handleType. * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00664]] pname:handleType must: be defined as an NT handle or a global share handle. **** include::{generated}/validity/structs/VkMemoryGetWin32HandleInfoKHR.txt[] -- [open,refpage='vkGetMemoryWin32HandlePropertiesKHR',desc='Get Properties of External Memory Win32 Handles',type='protos'] -- Windows memory handles compatible with Vulkan may: also be created by non-Vulkan APIs using methods beyond the scope of this specification. To determine the correct parameters to use when importing such handles, call: include::{generated}/api/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[] * pname:device is the logical device that will be importing pname:handle. * pname:handleType is the type of the handle pname:handle. * pname:handle is the handle which will be imported. * pname:pMemoryWin32HandleProperties will return properties of pname:handle. .Valid Usage **** * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handle-00665]] pname:handle must: be an external memory handle created outside of the Vulkan API. * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-00666]] pname:handleType must: not be one of the handle types defined as opaque. **** include::{generated}/validity/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[] -- [open,refpage='VkMemoryWin32HandlePropertiesKHR',desc='Properties of External Memory Windows Handles',type='structs'] -- The sname:VkMemoryWin32HandlePropertiesKHR structure returned is defined as: include::{generated}/api/structs/VkMemoryWin32HandlePropertiesKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified windows handle can: be imported as. include::{generated}/validity/structs/VkMemoryWin32HandlePropertiesKHR.txt[] -- endif::VK_KHR_external_memory_win32[] ifdef::VK_KHR_external_memory_fd[] [open,refpage='VkImportMemoryFdInfoKHR',desc='import memory created on the same physical device from a file descriptor',type='structs'] -- To import memory from a POSIX file descriptor handle, add a slink:VkImportMemoryFdInfoKHR structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkImportMemoryFdInfoKHR structure is defined as: include::{generated}/api/structs/VkImportMemoryFdInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:handleType specifies the handle type of pname:fd. * pname:fd is the external handle to import. Importing memory from a file descriptor transfers ownership of the file descriptor from the application to the Vulkan implementation. The application must: not perform any operations on the file descriptor after a successful import. Applications can: import the same underlying memory into multiple instances of Vulkan, into the same instance from which it was exported, and multiple times into a given Vulkan instance. In all cases, each import operation must: create a distinct sname:VkDeviceMemory object. .Valid Usage **** * [[VUID-VkImportMemoryFdInfoKHR-handleType-00667]] If pname:handleType is not `0`, it must: be supported for import, as reported by slink:VkExternalImageFormatProperties or slink:VkExternalBufferProperties. * [[VUID-VkImportMemoryFdInfoKHR-fd-00668]] The memory from which pname:fd was exported must: have been created on the same underlying physical device as pname:device. * [[VUID-VkImportMemoryFdInfoKHR-handleType-00669]] If pname:handleType is not `0`, it must: be defined as a POSIX file descriptor handle. * [[VUID-VkImportMemoryFdInfoKHR-handleType-00670]] If pname:handleType is not `0`, pname:fd must: be a valid handle of the type specified by pname:handleType. * [[VUID-VkImportMemoryFdInfoKHR-fd-01746]] The memory represented by pname:fd must: have been created from a physical device and driver that is compatible with pname:device and pname:handleType, as described in <>. * [[VUID-VkImportMemoryFdInfoKHR-fd-01520]] pname:fd must: obey any requirements listed for pname:handleType in <>. **** include::{generated}/validity/structs/VkImportMemoryFdInfoKHR.txt[] -- [open,refpage='vkGetMemoryFdKHR',desc='Get a POSIX file descriptor for a memory object',type='protos'] -- To export a POSIX file descriptor representing the underlying resources of a Vulkan device memory object, call: include::{generated}/api/protos/vkGetMemoryFdKHR.txt[] * pname:device is the logical device that created the device memory being exported. * pname:pGetFdInfo is a pointer to an instance of the slink:VkMemoryGetFdInfoKHR structure containing parameters of the export operation. * pname:pFd will return a file descriptor representing the underlying resources of the device memory object. Each call to fname:vkGetMemoryFdKHR must: create a new file descriptor and transfer ownership of it to the application. To avoid leaking resources, the application must: release ownership of the file descriptor using the code:close system call when it is no longer needed, or by importing a Vulkan memory object from it. Where supported by the operating system, the implementation must: set the file descriptor to be closed automatically when an code:execve system call is made. include::{generated}/validity/protos/vkGetMemoryFdKHR.txt[] -- [open,refpage='VkMemoryGetFdInfoKHR',desc='Structure describing a POSIX FD semaphore export operation',type='structs'] -- The sname:VkMemoryGetFdInfoKHR structure is defined as: include::{generated}/api/structs/VkMemoryGetFdInfoKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memory is the memory object from which the handle will be exported. * pname:handleType is the type of handle requested. The properties of the file descriptor exported depend on the value of pname:handleType. See elink:VkExternalMemoryHandleTypeFlagBits for a description of the properties of the defined external memory handle types. ifdef::VK_EXT_external_memory_dma_buf[] [NOTE] .Note ==== The size of the exported file may: be larger than the size requested by slink:VkMemoryAllocateInfo::allocationSize. If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT, then the application can: query the file's actual size with link:man:lseek(2)[lseek(2)]. ==== endif::VK_EXT_external_memory_dma_buf[] .Valid Usage **** * [[VUID-VkMemoryGetFdInfoKHR-handleType-00671]] pname:handleType must: have been included in slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory was created. * [[VUID-VkMemoryGetFdInfoKHR-handleType-00672]] pname:handleType must: be defined as a POSIX file descriptor handle. **** include::{generated}/validity/structs/VkMemoryGetFdInfoKHR.txt[] -- [open,refpage='vkGetMemoryFdPropertiesKHR',desc='Get Properties of External Memory File Descriptors',type='protos'] -- POSIX file descriptor memory handles compatible with Vulkan may: also be created by non-Vulkan APIs using methods beyond the scope of this specification. To determine the correct parameters to use when importing such handles, call: include::{generated}/api/protos/vkGetMemoryFdPropertiesKHR.txt[] * pname:device is the logical device that will be importing pname:fd. * pname:handleType is the type of the handle pname:fd. * pname:fd is the handle which will be imported. * pname:pMemoryFdProperties is a pointer to a slink:VkMemoryFdPropertiesKHR structure in which the properties of the handle pname:fd are returned. .Valid Usage **** * [[VUID-vkGetMemoryFdPropertiesKHR-fd-00673]] pname:fd must: be an external memory handle created outside of the Vulkan API. * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]] pname:handleType must: not be ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR. **** include::{generated}/validity/protos/vkGetMemoryFdPropertiesKHR.txt[] -- [open,refpage='VkMemoryFdPropertiesKHR',desc='Properties of External Memory File Descriptors',type='structs'] -- The sname:VkMemoryFdPropertiesKHR structure returned is defined as: include::{generated}/api/structs/VkMemoryFdPropertiesKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified file descriptor can: be imported as. include::{generated}/validity/structs/VkMemoryFdPropertiesKHR.txt[] -- endif::VK_KHR_external_memory_fd[] ifdef::VK_EXT_external_memory_host[] [open,refpage='VkImportMemoryHostPointerInfoEXT',desc='import memory from a host pointer',type='structs'] -- To import memory from a host pointer, add a slink:VkImportMemoryHostPointerInfoEXT structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkImportMemoryHostPointerInfoEXT structure is defined as: include::{generated}/api/structs/VkImportMemoryHostPointerInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:handleType specifies the handle type. * pname:pHostPointer is the host pointer to import from. Importing memory from a host pointer shares ownership of the memory between the host and the Vulkan implementation. The application can: continue to access the memory through the host pointer but it is the application's responsibility to synchronize device and non-device access to the underlying memory as defined in <>. Applications can: import the same underlying memory into multiple instances of Vulkan and multiple times into a given Vulkan instance. However, implementations may: fail to import the same underlying memory multiple times into a given physical device due to platform constraints. Importing memory from a particular host pointer may: not be possible due to additional platform-specific restrictions beyond the scope of this specification in which case the implementation must: fail the memory import operation with the error code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR. The application must: ensure that the imported memory range remains valid and accessible for the lifetime of the imported memory object. .Valid Usage **** * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01747]] If pname:handleType is not `0`, it must: be supported for import, as reported in slink:VkExternalMemoryPropertiesKHR * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01748]] If pname:handleType is not `0`, it must: be ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT * [[VUID-VkImportMemoryHostPointerInfoEXT-pHostPointer-01749]] pname:pHostPointer must: be a pointer aligned to an integer multiple of sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01750]] If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pname:pHostPointer must: be a pointer to pname:allocationSize number of bytes of host memory, where pname:allocationSize is the member of the sname:VkMemoryAllocateInfo structure this structure is chained to * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01751]] If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pname:pHostPointer must: be a pointer to pname:allocationSize number of bytes of host mapped foreign memory, where pname:allocationSize is the member of the sname:VkMemoryAllocateInfo structure this structure is chained to **** include::{generated}/validity/structs/VkImportMemoryHostPointerInfoEXT.txt[] -- [open,refpage='vkGetMemoryHostPointerPropertiesEXT',desc='Get properties of external memory host pointer',type='protos'] -- To determine the correct parameters to use when importing host pointers, call: include::{generated}/api/protos/vkGetMemoryHostPointerPropertiesEXT.txt[] * pname:device is the logical device that will be importing pname:pHostPointer. * pname:handleType is the type of the handle pname:pHostPointer. * pname:pHostPointer is the host pointer to import from. * pname:pMemoryHostPointerProperties is a pointer to a slink:VkMemoryHostPointerPropertiesEXT structure in which the host pointer properties are returned. .Valid Usage **** * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01752]] pname:handleType must: be ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT * [[VUID-vkGetMemoryHostPointerPropertiesEXT-pHostPointer-01753]] pname:pHostPointer must: be a pointer aligned to an integer multiple of sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01754]] If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pname:pHostPointer must: be a pointer to host memory * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01755]] If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pname:pHostPointer must: be a pointer to host mapped foreign memory **** include::{generated}/validity/protos/vkGetMemoryHostPointerPropertiesEXT.txt[] -- [open,refpage='VkMemoryHostPointerPropertiesEXT',desc='Properties of external memory host pointer',type='structs'] -- The sname:VkMemoryHostPointerPropertiesEXT structure is defined as: include::{generated}/api/structs/VkMemoryHostPointerPropertiesEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified host pointer can: be imported as. The value returned by pname:memoryTypeBits must: only include bits that identify memory types which are host visible. include::{generated}/validity/structs/VkMemoryHostPointerPropertiesEXT.txt[] -- endif::VK_EXT_external_memory_host[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] [open,refpage='VkImportAndroidHardwareBufferInfoANDROID',desc='Import memory from an Android hardware buffer',type='structs'] -- To import memory created outside of the current Vulkan instance from an Android hardware buffer, add a sname:VkImportAndroidHardwareBufferInfoANDROID structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkImportAndroidHardwareBufferInfoANDROID structure is defined as: include::{generated}/api/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:buffer is the Android hardware buffer to import. If the flink:vkAllocateMemory command succeeds, the implementation must: acquire a reference to the imported hardware buffer, which it must: release when the device memory object is freed. If the command fails, the implementation must: not retain a reference. .Valid Usage **** * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01880]] If pname:buffer is not `NULL`, Android hardware buffers must: be supported for import, as reported by slink:VkExternalImageFormatProperties or slink:VkExternalBufferProperties. * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01881]] If pname:buffer is not `NULL`, it must: be a valid Android hardware buffer object with code:AHardwareBuffer_Desc::code:format and code:AHardwareBuffer_Desc::code:usage compatible with Vulkan as described in <>. **** include::{generated}/validity/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] -- [open,refpage='vkGetMemoryAndroidHardwareBufferANDROID',desc='Get an Android hardware buffer for a memory object',type='protos'] -- To export an Android hardware buffer representing the underlying resources of a Vulkan device memory object, call: include::{generated}/api/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[] * pname:device is the logical device that created the device memory being exported. * pname:pInfo is a pointer to an instance of the slink:VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing parameters of the export operation. * pname:pBuffer will return an Android hardware buffer representing the underlying resources of the device memory object. Each call to fname:vkGetMemoryAndroidHardwareBufferANDROID must: return an Android hardware buffer with a new reference acquired in addition to the reference held by the slink:VkDeviceMemory. To avoid leaking resources, the application must: release the reference by calling code:AHardwareBuffer_release when it is no longer needed. When called with the same handle in slink:VkMemoryGetAndroidHardwareBufferInfoANDROID::pname:memory, fname:vkGetMemoryAndroidHardwareBufferANDROID must: return the same Android hardware buffer object. If the device memory was created by importing an Android hardware buffer, fname:vkGetMemoryAndroidHardwareBufferANDROID must: return that same Android hardware buffer object. include::{generated}/validity/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[] -- [open,refpage='VkMemoryGetAndroidHardwareBufferInfoANDROID',desc='Structure describing an Android hardware buffer memory export operation',type='structs'] -- The sname:VkMemoryGetAndroidHardwareBufferInfoANDROID structure is defined as: include::{generated}/api/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memory is the memory object from which the Android hardware buffer will be exported. .Valid Usage **** * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-handleTypes-01882]] ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID must: have been included in slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes when pname:memory was created. * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-01883]] If the pname:pNext chain of the slink:VkMemoryAllocateInfo used to allocate pname:memory included a slink:VkMemoryDedicatedAllocateInfo with non-`NULL` pname:image member, then that pname:image must: already be bound to pname:memory. **** include::{generated}/validity/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[] -- [open,refpage='vkGetAndroidHardwareBufferPropertiesANDROID',desc='Get Properties of External Memory Android Hardware Buffers',type='protos'] -- To determine the memory parameters to use when importing an Android hardware buffer, call: include::{generated}/api/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] * pname:device is the logical device that will be importing pname:buffer. * pname:buffer is the Android hardware buffer which will be imported. * pname:pProperties is a pointer to a slink:VkAndroidHardwareBufferPropertiesANDROID structure in which the properties of pname:buffer are returned. .Valid Usage **** * [[VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-01884]] pname:buffer must: be a valid Android hardware buffer object with at least one of the code:AHARDWAREBUFFER_USAGE_GPU_* flags in its code:AHardwareBuffer_Desc::code:usage **** include::{generated}/validity/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] -- [open,refpage='VkAndroidHardwareBufferPropertiesANDROID',desc='Properties of External Memory Android Hardware Buffers',type='structs'] -- The sname:VkAndroidHardwareBufferPropertiesANDROID structure returned is defined as: include::{generated}/api/structs/VkAndroidHardwareBufferPropertiesANDROID.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:allocationSize is the size of the external memory * pname:memoryTypeBits is a bitmask containing one bit set for every memory type which the specified Android hardware buffer can: be imported as. include::{generated}/validity/structs/VkAndroidHardwareBufferPropertiesANDROID.txt[] -- [open,refpage='VkAndroidHardwareBufferFormatPropertiesANDROID',desc='Structure describing the image format properties of an Android hardware buffer',type='structs'] -- To obtain format properties of an Android hardware buffer, include an instance of sname:VkAndroidHardwareBufferFormatPropertiesANDROID in the pname:pNext chain of the slink:VkAndroidHardwareBufferPropertiesANDROID instance passed to flink:vkGetAndroidHardwareBufferPropertiesANDROID. This structure is defined as: include::{generated}/api/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:format is the Vulkan format corresponding to the Android hardware buffer's format, or ename:VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan format. * pname:externalFormat is an implementation-defined external format identifier for use with slink:VkExternalFormatANDROID. It must: not be zero. * pname:formatFeatures describes the capabilities of this external format when used with an image bound to memory imported from pname:buffer. * pname:samplerYcbcrConversionComponents is the component swizzle that should: be used in slink:VkSamplerYcbcrConversionCreateInfo. * pname:suggestedYcbcrModel is a suggested color model to use in the slink:VkSamplerYcbcrConversionCreateInfo. * pname:suggestedYcbcrRange is a suggested numerical value range to use in slink:VkSamplerYcbcrConversionCreateInfo. * pname:suggestedXChromaOffset is a suggested X chroma offset to use in slink:VkSamplerYcbcrConversionCreateInfo. * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in slink:VkSamplerYcbcrConversionCreateInfo. If the Android hardware buffer has one of the formats listed in the <>, then pname:format must: have the equivalent Vulkan format listed in the table. Otherwise, pname:format may: be ename:VK_FORMAT_UNDEFINED, indicating the Android hardware buffer can: only be used with an external format. The pname:formatFeatures member must: include ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and at least one of ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, and should: include ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT. [NOTE] .Note ==== The pname:formatFeatures member only indicates the features available when using an <> created from the Android hardware buffer. Images from Android hardware buffers with a format other than ename:VK_FORMAT_UNDEFINED are subject to the format capabilities obtained from flink:vkGetPhysicalDeviceFormatProperties2, and flink:vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters. These sets of features are independent of each other, e.g. the external format will support sampler Y'C~B~C~R~ conversion even if the non-external format does not, and writing to non-external format images is possible but writing to external format images is not. ==== Android hardware buffers with the same external format must: have the same support for ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT, ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, and ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT. in pname:formatFeatures. Other format features may: differ between Android hardware buffers that have the same external format. This allows applications to use the same slink:VkSamplerYcbcrConversion object (and samplers and pipelines created from them) for any Android hardware buffers that have the same external format. If pname:format is not ename:VK_FORMAT_UNDEFINED, then the value of pname:samplerYcbcrConversionComponents must: be valid when used as the pname:components member of slink:VkSamplerYcbcrConversionCreateInfo with that format. If pname:format is ename:VK_FORMAT_UNDEFINED, all members of pname:samplerYcbcrConversionComponents must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY. Implementations may: not always be able to determine the color model, numerical range, or chroma offsets of the image contents, so the values in sname:VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions. Applications should: treat these values as sensible defaults to use in the absence of more reliable information obtained through some other means. If the underlying physical device is also usable via OpenGL ES with the https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`] extension, the implementation should: suggest values that will produce similar sampled values as would be obtained by sampling the same external image via code:samplerExternalOES in OpenGL ES using equivalent sampler parameters. [NOTE] .Note ==== Since https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`] does not require the same sampling and conversion calculations as Vulkan does, achieving identical results between APIs may: not be possible on some implementations. ==== include::{generated}/validity/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[] -- endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_NV_external_memory[] include::VK_NV_external_memory/allocate_memory.txt[] endif::VK_NV_external_memory[] ifdef::VK_NV_external_memory_win32[] include::VK_NV_external_memory_win32/handle_permissions.txt[] include::VK_NV_external_memory_win32/import_memory_win32.txt[] include::VK_NV_external_memory_win32/get_handle_win32.txt[] endif::VK_NV_external_memory_win32[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='VkMemoryAllocateFlagsInfo',desc='Structure controlling how many instances of memory will be allocated',type='structs'] -- If the pname:pNext chain of slink:VkMemoryAllocateInfo includes a sname:VkMemoryAllocateFlagsInfo structure, then that structure includes flags and a device mask controlling how many instances of the memory will be allocated. The sname:VkMemoryAllocateFlagsInfo structure is defined as: include::{generated}/api/structs/VkMemoryAllocateFlagsInfo.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/structs/VkMemoryAllocateFlagsInfoKHR.txt[] endif::VK_KHR_device_group[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is a bitmask of elink:VkMemoryAllocateFlagBits controlling the allocation. * pname:deviceMask is a mask of physical devices in the logical device, indicating that memory must: be allocated on each device in the mask, if ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set in pname:flags. If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is not set, the number of instances allocated depends on whether ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set in the memory heap. If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set, then memory is allocated for every physical device in the logical device (as if pname:deviceMask has bits set for all device indices). If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is not set, then a single instance of memory is allocated (as if pname:deviceMask is set to one). On some implementations, allocations from a multi-instance heap may: consume memory on all physical devices even if the pname:deviceMask excludes some devices. If slink:VkPhysicalDeviceGroupProperties::pname:subsetAllocation is ename:VK_TRUE, then memory is only consumed for the devices in the device mask. [NOTE] .Note ==== In practice, most allocations on a multi-instance heap will be allocated across all physical devices. Unicast allocation support is an optional optimization for a minority of allocations. ==== .Valid Usage **** * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00675]] If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask must: be a valid device mask. * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00676]] If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask must: not be zero **** include::{generated}/validity/structs/VkMemoryAllocateFlagsInfo.txt[] -- [open,refpage='VkMemoryAllocateFlagBits',desc='Bitmask specifying flags for a device memory allocation',type='enums'] -- Bits which can: be set in slink:VkMemoryAllocateFlagsInfo::pname:flags, controlling device memory allocation, are: include::{generated}/api/enums/VkMemoryAllocateFlagBits.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/enums/VkMemoryAllocateFlagBitsKHR.txt[] endif::VK_KHR_device_group[] * ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT specifies that memory will be allocated for the devices in slink:VkMemoryAllocateFlagsInfo::pname:deviceMask. -- [open,refpage='VkMemoryAllocateFlags',desc='Bitmask of VkMemoryAllocateFlagBits',type='flags'] -- include::{generated}/api/flags/VkMemoryAllocateFlags.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/flags/VkMemoryAllocateFlagsKHR.txt[] endif::VK_KHR_device_group[] tname:VkMemoryAllocateFlags is a bitmask type for setting a mask of zero or more elink:VkMemoryAllocateFlagBits. -- endif::VK_VERSION_1_1,VK_KHR_device_group[] [open,refpage='vkFreeMemory',desc='Free device memory',type='protos'] -- To free a memory object, call: include::{generated}/api/protos/vkFreeMemory.txt[] * pname:device is the logical device that owns the memory. * pname:memory is the slink:VkDeviceMemory object to be freed. * pname:pAllocator controls host memory allocation as described in the <> chapter. Before freeing a memory object, an application must: ensure the memory object is no longer in use by the device--for example by command buffers in the _pending state_. Memory can: be freed whilst still bound to resources, but those resources must: not be used afterwards. If there are still any bound images or buffers, the memory may: not be immediately released by the implementation, but must: be released by the time all bound images and buffers have been destroyed. Once memory is released, it is returned to the heap from which it was allocated. How memory objects are bound to Images and Buffers is described in detail in the <> section. If a memory object is mapped at the time it is freed, it is implicitly unmapped. [NOTE] .Note ==== As described <>, 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 **** * [[VUID-vkFreeMemory-memory-00677]] All submitted commands that refer to pname:memory (via images or buffers) must: have completed execution **** include::{generated}/validity/protos/vkFreeMemory.txt[] -- [[memory-device-hostaccess]] === Host Access to Device Memory Objects Memory objects created with flink:vkAllocateMemory are not directly host accessible. Memory objects created with the memory property ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered _mappable_. Memory objects must: be mappable in order to be successfully mapped on the host. [open,refpage='vkMapMemory',desc='Map a memory object into application address space',type='protos'] -- To retrieve a host virtual address pointer to a region of a mappable memory object, call: include::{generated}/api/protos/vkMapMemory.txt[] * pname:device is the logical device that owns the memory. * pname:memory is the slink:VkDeviceMemory object to be mapped. * pname:offset is a zero-based byte offset from the beginning of the memory object. * pname:size is the size of the memory range to map, or ename:VK_WHOLE_SIZE to map from pname:offset to the end of the allocation. * pname:flags is reserved for future use. * pname:ppData points to a pointer in which is returned a host-accessible pointer to the beginning of the mapped range. This pointer minus pname:offset must: be aligned to at least slink:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment. After a successful call to fname:vkMapMemory the memory object pname:memory is considered to be currently _host mapped_. It is an application error to call fname:vkMapMemory on a memory object that is already host mapped. [NOTE] .Note ==== fname:vkMapMemory 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, fname:vkMapMemory must: return ename:VK_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 flink:vkUnmapMemory. ==== [[memory-device-hostaccess-hazards]] fname:vkMapMemory does not check whether the device memory is currently in use before returning the host-accessible pointer. The application must: guarantee that any previously submitted command that writes to this range has completed before the host reads from or writes to that range, and that any previously submitted command that reads from that range has completed before the host writes to that region (see <> for details on fulfilling such a guarantee). If the device memory was allocated without the ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must: be made for an extended range: the application must: round down the start of the range to the nearest multiple of slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, and round the end of the range up to the nearest multiple of slink:VkPhysicalDeviceLimits::pname: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] .Note ==== It is important for the application developer to become meticulously familiar with all of the mechanisms described in the chapter on <> as they are crucial to maintaining memory access ordering. ==== .Valid Usage **** * [[VUID-vkMapMemory-memory-00678]] pname:memory must: not be currently host mapped * [[VUID-vkMapMemory-offset-00679]] pname:offset must: be less than the size of pname:memory * [[VUID-vkMapMemory-size-00680]] If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be greater than `0` * [[VUID-vkMapMemory-size-00681]] If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be less than or equal to the size of the pname:memory minus pname:offset * [[VUID-vkMapMemory-memory-00682]] pname:memory must: have been created with a memory type that reports ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT ifdef::VK_KHR_device_group[] * [[VUID-vkMapMemory-memory-00683]] pname:memory must: not have been allocated with multiple instances. endif::VK_KHR_device_group[] **** include::{generated}/validity/protos/vkMapMemory.txt[] -- [open,refpage='VkMemoryMapFlags',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkMemoryMapFlags.txt[] tname:VkMemoryMapFlags is a bitmask type for setting a mask, but is currently reserved for future use. -- Two commands are provided to enable applications to work with non-coherent memory allocations: fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges. [NOTE] .Note ==== If the memory object was created with the ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are unnecessary and may: have a performance cost. However, <> still need to be managed on the device. See the description of <> for more information. ==== ifdef::VK_EXT_external_memory_host[] [NOTE] .Note ==== While memory objects imported from a handle type of ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT are inherently mapped to host address space, they are not considered to be host mapped device memory unless they are explicitly host mapped using flink:vkMapMemory. That means flushing or invalidating host caches with respect to host accesses performed on such memory through the original host pointer specified at import time is the responsibility of the application and must: be performed with appropriate synchronization primitives provided by the platform which are outside the scope of Vulkan. fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges, however, can: still be used on such memory objects to synchronize host accesses performed through the host pointer of the host mapped device memory range returned by flink:vkMapMemory. ==== endif::VK_EXT_external_memory_host[] [open,refpage='vkFlushMappedMemoryRanges',desc='Flush mapped memory ranges',type='protos'] -- To flush ranges of non-coherent memory from the host caches, call: include::{generated}/api/protos/vkFlushMappedMemoryRanges.txt[] * pname:device is the logical device that owns the memory ranges. * pname:memoryRangeCount is the length of the pname:pMemoryRanges array. * pname:pMemoryRanges is a pointer to an array of slink:VkMappedMemoryRange structures describing the memory ranges to flush. fname:vkFlushMappedMemoryRanges guarantees that host writes to the memory ranges described by pname:pMemoryRanges are made available to the host memory domain, such that they can: be made available to the device memory domain via <> using the ename:VK_ACCESS_HOST_WRITE_BIT <>. Within each range described by pname:pMemoryRanges, each set of pname: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 pname:pMemoryRanges includes sets of pname:nonCoherentAtomSize bytes where no bytes have been written by the host, those bytes must: not be flushed. [[memory-device-unmap-does-not-flush]] 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] .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). ==== include::{generated}/validity/protos/vkFlushMappedMemoryRanges.txt[] -- [open,refpage='vkInvalidateMappedMemoryRanges',desc='Invalidate ranges of mapped memory objects',type='protos'] -- To invalidate ranges of non-coherent memory from the host caches, call: include::{generated}/api/protos/vkInvalidateMappedMemoryRanges.txt[] * pname:device is the logical device that owns the memory ranges. * pname:memoryRangeCount is the length of the pname:pMemoryRanges array. * pname:pMemoryRanges is a pointer to an array of slink:VkMappedMemoryRange structures describing the memory ranges to invalidate. fname:vkInvalidateMappedMemoryRanges guarantees that device writes to the memory ranges described by pname:pMemoryRanges, which have been made available to the host memory domain using the ename:VK_ACCESS_HOST_WRITE_BIT and ename:VK_ACCESS_HOST_READ_BIT <>, 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 pname:pMemoryRanges, each set of pname: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] .Note ==== Mapping non-coherent memory does not implicitly invalidate the mapped memory, and device writes that have not been invalidated must: be made visible before the host reads or overwrites them. ==== include::{generated}/validity/protos/vkInvalidateMappedMemoryRanges.txt[] -- [open,refpage='VkMappedMemoryRange',desc='Structure specifying a mapped memory range',type='structs'] -- The sname:VkMappedMemoryRange structure is defined as: include::{generated}/api/structs/VkMappedMemoryRange.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:memory is the memory object to which this range belongs. * pname:offset is the zero-based byte offset from the beginning of the memory object. * pname:size is either the size of range, or ename:VK_WHOLE_SIZE to affect the range from pname:offset to the end of the current mapping of the allocation. .Valid Usage **** * [[VUID-VkMappedMemoryRange-memory-00684]] pname:memory must: be currently host mapped * [[VUID-VkMappedMemoryRange-size-00685]] If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:offset and pname:size must: specify a range contained within the currently mapped range of pname:memory * [[VUID-VkMappedMemoryRange-size-00686]] If pname:size is equal to ename:VK_WHOLE_SIZE, pname:offset must: be within the currently mapped range of pname:memory * [[VUID-VkMappedMemoryRange-size-01389]] If pname:size is equal to ename:VK_WHOLE_SIZE, the end of the current mapping of pname:memory must: be a multiple of slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize bytes from the beginning of the memory object. * [[VUID-VkMappedMemoryRange-offset-00687]] pname:offset must: be a multiple of slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize * [[VUID-VkMappedMemoryRange-size-01390]] If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: either be a multiple of slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, or pname:offset plus pname:size must: equal the size of pname:memory. **** include::{generated}/validity/structs/VkMappedMemoryRange.txt[] -- [open,refpage='vkUnmapMemory',desc='Unmap a previously mapped memory object',type='protos'] -- To unmap a memory object once host access to it is no longer needed by the application, call: include::{generated}/api/protos/vkUnmapMemory.txt[] * pname:device is the logical device that owns the memory. * pname:memory is the memory object to be unmapped. .Valid Usage **** * [[VUID-vkUnmapMemory-memory-00689]] pname:memory must: be currently host mapped **** include::{generated}/validity/protos/vkUnmapMemory.txt[] -- [[memory-device-lazy_allocation]] === Lazily Allocated Memory If the memory object is allocated from a heap with the ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, that object's backing memory may: be provided by the implementation lazily. The actual committed size of the memory may: initially be as small as zero (or as large as the requested size), and monotonically increases as additional memory is needed. A memory type with this flag set is only allowed to be bound to a sname:VkImage whose usage flags include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT. [NOTE] .Note ==== Using lazily allocated memory objects for framebuffer attachments that are not needed once a render pass instance has completed may: allow some implementations to never allocate memory for such attachments. ==== [open,refpage='vkGetDeviceMemoryCommitment',desc='Query the current commitment for a VkDeviceMemory',type='protos'] -- To determine the amount of lazily-allocated memory that is currently committed for a memory object, call: include::{generated}/api/protos/vkGetDeviceMemoryCommitment.txt[] * pname:device is the logical device that owns the memory. * pname:memory is the memory object being queried. * pname:pCommittedMemoryInBytes is a pointer to a basetype:VkDeviceSize value in which the number of bytes currently committed is returned, on success. The implementation may: update the commitment at any time, and the value returned by this query may: be out of date. The implementation guarantees to allocate any committed memory from the heapIndex indicated by the memory type that the memory object was created with. .Valid Usage **** * [[VUID-vkGetDeviceMemoryCommitment-memory-00690]] pname:memory must: have been created with a memory type that reports ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT **** include::{generated}/validity/protos/vkGetDeviceMemoryCommitment.txt[] -- ifdef::VK_VERSION_1_1[] [[memory-protected-memory]] === Protected Memory _Protected memory_ divides device memory into protected device memory and unprotected device memory. Protected memory adds the following concepts: * Memory: ** Unprotected device memory, which can: be visible to the device and can: be visible to the host ** Protected device memory, which can: be visible to the device but must: not be visible to the host * Resources: ** Unprotected images and unprotected buffers, to which unprotected memory can: be bound ** Protected images and protected buffers, to which protected memory can: be bound * Command buffers: ** Unprotected command buffers, which can: be submitted to a device queue to execute unprotected queue operations ** Protected command buffers, which can: be submitted to a protected-capable device queue to execute protected queue operations * Device queues: ** Unprotected device queues, to which unprotected command buffers can: be submitted ** Protected-capable device queues, to which unprotected command buffers or protected command buffers can: be submitted * Queue submissions ** Unprotected queue submissions, through which unprotected command buffers can: be submitted ** Protected queue submissions, through which protected command buffers can: be submitted * Queue operations ** Unprotected queue operations ** Protected queue operations [[memory-protected-access-rules]] ==== Protected Memory Access Rules If slink:VkPhysicalDeviceProtectedMemoryProperties::pname:protectedNoFault is ename:VK_FALSE, applications must: not perform any of the following operations: * Write to unprotected memory within protected queue operations. * Access protected memory within protected queue operations other than in framebuffer-space pipeline stages, the compute shader stage, or the transfer stage. * Perform a query within protected queue operations. * Execute an indirect command within protected queue operations. If slink:VkPhysicalDeviceProtectedMemoryProperties::pname:protectedNoFault is ename:VK_TRUE, these operations are valid, but reads will return undefined: values, and writes will either be dropped or store undefined: values. Whether these operations are valid or not, or if any other invalid usage is performed, the implementation must: guarantee that: * Protected device memory must: never be visible to the host. * Values written to unprotected device memory must: not be a function of values from protected memory. endif::VK_VERSION_1_1[] ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] [[memory-external-handle-types]] === External Memory Handle Types [[memory-external-android-hardware-buffer]] ==== Android Hardware Buffer Android's NDK defines dlink:AHardwareBuffer objects, which represent device memory that is shareable across processes and that can: be accessed by a variety of media APIs and the hardware used to implement them. These Android hardware buffer objects may: be imported into slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. [open,refpage='AHardwareBuffer',desc='Android hardware buffer type',type='defines'] -- To remove an unnecessary compile-time dependency, an incomplete type definition of dlink:AHardwareBuffer is provided in the Vulkan headers: include::{generated}/api/defines/AHardwareBuffer.txt[] The actual dlink:AHardwareBuffer type is defined in Android NDK headers. -- [NOTE] .Note ==== The NDK format, usage, and size/dimensions of an dlink:AHardwareBuffer object can be obtained with the code:AHardwareBuffer_describe function. While Android hardware buffers can be imported to or exported from Vulkan without using that function, valid usage and implementation behavior is defined in terms of the code:AHardwareBuffer_Desc properties it returns. ==== Android hardware buffer objects are reference-counted using Android NDK functions outside of the scope of this specification. A slink:VkDeviceMemory imported from an Android hardware buffer or that can: be exported to an Android hardware buffer must: acquire a reference to its dlink:AHardwareBuffer object, and must: release this reference when the device memory is freed. During the host execution of a Vulkan command that has an Android hardware buffer as a parameter (including indirect parameters via pname:pNext chains), the application must: not decrement the Android hardware buffer's reference count to zero. Android hardware buffers can: be mapped and unmapped for CPU access using the NDK functions. These lock and unlock APIs are considered to acquire and release ownership of the Android hardware buffer, and applications must: follow the rules described in <> to transfer ownership between the Vulkan instance and these native APIs. Android hardware buffers can: be shared with external APIs and Vulkan instances on the same device, and also with foreign devices. When transferring ownership of the Android hardware buffer, the external and foreign special queue families described in <> are not identical. All APIs which produce or consume Android hardware buffers are considered to use foreign devices, except OpenGL ES contexts and Vulkan logical devices that have matching device and driver UUIDs. Implementations may: treat a transfer to or from the foreign queue family as if it were a transfer to or from the external queue family when the Android hardware buffer's usage only permits it to be used on the same physical device. [[memory-external-android-hardware-buffer-optimal-usages]] ===== Android Hardware Buffer Optimal Usages ===== Vulkan buffer and image usage flags do not correspond exactly to Android hardware buffer usage flags. When allocating Android hardware buffers with non-Vulkan APIs, if any code:AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the allocator must: allocate the memory in such a way that it supports Vulkan usages and creation flags in the <> which do not have Android hardware buffer equivalents. The slink:VkAndroidHardwareBufferUsageANDROID structure can: be attached to the pname:pNext chain of a slink:VkImageFormatProperties2 instance passed to flink:vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android hardware buffer usage flags for specific Vulkan resource creation parameters. Some usage flags returned by these commands are required: based on the input parameters, but additional vendor-specific usage flags (code:AHARDWAREBUFFER_USAGE_VENDOR_*) may: also be returned. Any Android hardware buffer allocated with these vendor-specific usage flags and imported to Vulkan must: only be bound to resources created with parameters that are a subset of the parameters used to obtain the Android hardware buffer usage, since the memory may: have been allocated in a way incompatible with other parameters. If an Android hardware buffer is successfully allocated with additional non-vendor-specific usage flags in addition to the recommended usage, it must: support being used in the same ways as an Android hardware buffer allocated with only the recommended usage, and also in ways indicated by the additional usage. [[memory-external-android-hardware-buffer-external-formats]] ===== Android Hardware Buffer External Formats ===== Android hardware buffers may: represent images using implementation-specific formats, layouts, color models, etc., which do not have Vulkan equivalents. Such _external formats_ are commonly used by external image sources such as video decoders or cameras. Vulkan can: import Android hardware buffers that have external formats, but since the image contents are in an undiscoverable and possibly proprietary representation, images with external formats must: only be used as sampled images, must: only be sampled with a sampler that has Y'C~B~C~R~ conversion enabled, and must: have optimal tiling. Images that will be backed by an Android hardware buffer can: use an external format by setting slink:VkImageCreateInfo::pname:format to ename:VK_FORMAT_UNDEFINED and including an instance of slink:VkExternalFormatANDROID in the pname:pNext chain. Images can: be created with an external format even if the Android hardware buffer has a format which has an <> to enable consistent handling of images from sources that might use either category of format. However, all images created with an external format are subject to the valid usage requirements associated with external formats, even if the Android hardware buffer's format has a Vulkan equivalent. The external format of an Android hardware buffer can: be obtained by passing an instance of slink:VkAndroidHardwareBufferFormatPropertiesANDROID to flink:vkGetAndroidHardwareBufferPropertiesANDROID. [[memory-external-android-hardware-buffer-image-resources]] ===== Android Hardware Buffer Image Resources Android hardware buffers have intrinsic width, height, format, and usage properties, so Vulkan images bound to memory imported from an Android hardware buffer must: use dedicated allocations: sname:VkMemoryDedicatedRequirements::pname:requiresDedicatedAllocation must: be ename:VK_TRUE for images created with sname:VkExternalMemoryImageCreateInfo::pname:handleTypes that includes ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. When creating an image that will be bound to an imported Android hardware buffer, the image creation parameters must: be equivalent to the dlink:AHardwareBuffer properties as described by the valid usage of slink:VkMemoryAllocateInfo. Similarly, device memory allocated for a dedicated image must: not be exported to an Android hardware buffer until it has been bound to that image, and the implementation must: return an Android hardware buffer with properties derived from the image: * The code:width and code:height members of code:AHardwareBuffer_Desc must: be the same as the pname:width and pname:height members of slink:VkImageCreateInfo::pname:extent, respectively. * The code:layers member of code:AHardwareBuffer_Desc must: be the same as the pname:arrayLayers member of slink:VkImageCreateInfo. * The code:format member of code:AHardwareBuffer_Desc must: be equivalent to slink:VkImageCreateInfo::pname:format as defined by <>. * The code:usage member of code:AHardwareBuffer_Desc must: include bits corresponding to bits included in slink:VkImageCreateInfo::pname:usage and slink:VkImageCreateInfo::pname:flags where such a correspondence exists according to <>. It may: also include additional usage bits, including vendor-specific usages. Presence of vendor usage bits may: make the Android hardware buffer only usable in ways indicated by the image creation parameters, even when used outside Vulkan, in a similar way that allocating the Android hardware buffer with usage returned in slink:VkAndroidHardwareBufferUsageANDROID does. Implementations may: support fewer combinations of image creation parameters for images with Android hardware buffer external handle type than for non-external images. Support for a given set of parameters can: be determined by passing slink:VkExternalImageFormatProperties to flink:vkGetPhysicalDeviceImageFormatProperties2 with pname:handleType set to ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. Any Android hardware buffer successfully allocated outside Vulkan with usage that includes code:AHARDWAREBUFFER_USAGE_GPU_* must: be supported when using equivalent Vulkan image parameters. If a given choice of image parameters are supported for import, they can: also be used to create an image and memory that will be exported to an Android hardware buffer. [[memory-external-android-hardware-buffer-formats]] .AHardwareBuffer Format Equivalence [width="100%",options="header"] |==== | AHardwareBuffer Format | Vulkan Format | code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM | ename:VK_FORMAT_R8G8B8A8_UNORM | code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM ^1^ | ename:VK_FORMAT_R8G8B8A8_UNORM | code:AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM | ename:VK_FORMAT_R8G8B8_UNORM | code:AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM | ename:VK_FORMAT_R5G6B5_UNORM_PACK16 | code:AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT | ename:VK_FORMAT_R16G16B16A16_SFLOAT | code:AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM | ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32 | code:AHARDWAREBUFFER_FORMAT_D16_UNORM | ename:VK_FORMAT_D16_UNORM | code:AHARDWAREBUFFER_FORMAT_D24_UNORM | ename:VK_FORMAT_X8_D24_UNORM_PACK32 | code:AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT | ename:VK_FORMAT_D24_UNORM_S8_UINT | code:AHARDWAREBUFFER_FORMAT_D32_FLOAT | ename:VK_FORMAT_D32_SFLOAT | code:AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT | ename:VK_FORMAT_D32_SFLOAT_S8_UINT | code:AHARDWAREBUFFER_FORMAT_S8_UINT | ename:VK_FORMAT_S8_UINT |==== [[memory-external-android-hardware-buffer-usage]] .AHardwareBuffer Usage Equivalence [width="100%",options="header"] |==== | AHardwareBuffer Usage | Vulkan Usage or Creation Flag | None | ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT | None | ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT | code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | ename:VK_IMAGE_USAGE_SAMPLED_BIT | code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT | code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT | ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | code:AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP | ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT | code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE | None ^2^ ifdef::VK_VERSION_1_1[] | code:AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT | ename:VK_IMAGE_CREATE_PROTECTED_BIT endif::VK_VERSION_1_1[] | None | ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT | None | ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT |==== 1:: Vulkan does not differentiate between code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM and code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM: they both behave as ename:VK_FORMAT_R8G8B8A8_UNORM. After an external entity writes to a code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM Android hardware buffer, the values read by Vulkan from the X/A channel are undefined. To emulate the traditional behavior of the X channel during sampling or blending, applications should: use ename:VK_COMPONENT_SWIZZLE_ONE in image view component mappings and ename:VK_BLEND_FACTOR_ONE in color blend factors. There is no way to avoid copying these undefined values when copying from such an image to another image or buffer. 2:: The code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE flag does not correspond to a Vulkan image usage or creation flag. Instead, its presence indicates that the Android hardware buffer contains a complete mipmap chain, and its absence indicates that the Android hardware buffer contains only a single mip level. ifdef::VK_KHR_image_format_list[] [NOTE] .Note ==== When using ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT with Android hardware buffer images, applications should: use slink:VkImageFormatListCreateInfoKHR to inform the implementation which view formats will be used with the image. For some common sets of format, this allows some implementations to provide significantly better performance when accessing the image via Vulkan. ==== endif::VK_KHR_image_format_list[] [[memory-external-android-hardware-buffer-buffer-resources]] ===== Android Hardware Buffer Buffer Resources Android hardware buffers with a format of code:AHARDWAREBUFFER_FORMAT_BLOB and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can: be used as the backing store for slink:VkBuffer objects. Such Android hardware buffers have a size in bytes specified by their code:width; code:height and code:layers are both `1`. Unlike images, buffer resources backed by Android hardware buffers do not require dedicated allocations. Exported dlink:AHardwareBuffer objects that do not have dedicated images must: have a format of code:AHARDWAREBUFFER_FORMAT_BLOB, usage must: include code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, code:width must: equal the device memory allocation size, and code:height and code:layers must: be `1`. endif::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_VERSION_1_1,VK_KHR_device_group[] [[memory-peer-memory-features]] === Peer Memory Features [open,refpage='vkGetDeviceGroupPeerMemoryFeatures',desc='Query supported peer memory features of a device',type='protos'] -- _Peer memory_ is memory that is allocated for a given physical device and then bound to a resource and accessed by a different physical device, in a logical device that represents multiple physical devices. Some ways of reading and writing peer memory may: not be supported by a device. To determine how peer memory can: be accessed, call: ifdef::VK_VERSION_1_1[] include::{generated}/api/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[] endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] ifdef::VK_KHR_device_group[] include::{generated}/api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHR.txt[] endif::VK_KHR_device_group[] * pname:device is the logical device that owns the memory. * pname:heapIndex is the index of the memory heap from which the memory is allocated. * pname:localDeviceIndex is the device index of the physical device that performs the memory access. * pname:remoteDeviceIndex is the device index of the physical device that the memory is allocated for. * pname:pPeerMemoryFeatures is a pointer to a bitmask of elink:VkPeerMemoryFeatureFlagBits indicating which types of memory accesses are supported for the combination of heap, local, and remote devices. .Valid Usage **** * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-heapIndex-00691]] pname:heapIndex must: be less than pname:memoryHeapCount * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00692]] pname:localDeviceIndex must: be a valid device index * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-remoteDeviceIndex-00693]] pname:remoteDeviceIndex must: be a valid device index * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00694]] pname:localDeviceIndex must: not equal pname:remoteDeviceIndex **** include::{generated}/validity/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[] -- [open,refpage='VkPeerMemoryFeatureFlagBits',desc='Bitmask specifying supported peer memory features',type='enums'] -- Bits which may: be set in the value returned for flink:vkGetDeviceGroupPeerMemoryFeatures::pname:pPeerMemoryFeatures, indicating the supported peer memory features, are: include::{generated}/api/enums/VkPeerMemoryFeatureFlagBits.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/enums/VkPeerMemoryFeatureFlagBitsKHR.txt[] endif::VK_KHR_device_group[] * ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT specifies that the memory can: be accessed as the source of a flink:vkCmdCopyBuffer, flink:vkCmdCopyImage, flink:vkCmdCopyBufferToImage, or flink:vkCmdCopyImageToBuffer command. * ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT specifies that the memory can: be accessed as the destination of a flink:vkCmdCopyBuffer, flink:vkCmdCopyImage, flink:vkCmdCopyBufferToImage, or flink:vkCmdCopyImageToBuffer command. * ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT specifies that the memory can: be read as any memory access type. * ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT specifies that the memory can: be written as any memory access type. Shader atomics are considered to be writes. [NOTE] .Note ==== The peer memory features of a memory heap also apply to any accesses that may: be performed during <>. ==== ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must: be supported for all host local heaps and for at least one device local heap. If a device does not support a peer memory feature, it is still valid to use a resource that includes both local and peer memory bindings with the corresponding access type as long as only the local bindings are actually accessed. For example, an application doing split-frame rendering would use framebuffer attachments that include both local and peer memory bindings, but would scissor the rendering to only update local memory. -- [open,refpage='VkPeerMemoryFeatureFlags',desc='Bitmask of VkPeerMemoryFeatureFlagBits',type='flags'] -- include::{generated}/api/flags/VkPeerMemoryFeatureFlags.txt[] ifdef::VK_KHR_device_group[] or the equivalent include::{generated}/api/flags/VkPeerMemoryFeatureFlagsKHR.txt[] endif::VK_KHR_device_group[] tname:VkPeerMemoryFeatureFlags is a bitmask type for setting a mask of zero or more elink:VkPeerMemoryFeatureFlagBits. -- endif::VK_VERSION_1_1,VK_KHR_device_group[]