| // Copyright 2015-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-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]] |
| |
| ifdef::VKSC_VERSION_1_0[] |
| The Vulkan SC implementation will perform its own host memory allocations. |
| Support for application-provided memory allocation, as supported in Base |
| Vulkan, has been removed in Vulkan SC. |
| endif::VKSC_VERSION_1_0[] |
| ifndef::VKSC_VERSION_1_0[] |
| 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. |
| endif::VKSC_VERSION_1_0[] |
| |
| [open,refpage='VkAllocationCallbacks',desc='Structure containing callback function pointers for memory allocation',type='structs'] |
| -- |
| ifdef::VKSC_VERSION_1_0[] |
| ifdef::hidden[] |
| // tag::scdeviation[] |
| * <<memory-vkallocationcallbacks-null, vkCreate*>>::pname:pAllocator must: |
| be `NULL` <<SCID-2>>, <<SCID-8>>. |
| * <<memory-vkallocationcallbacks-null, vkDestroy*>>::pname:pAllocator |
| must: be `NULL` <<SCID-2>>, <<SCID-8>>. |
| * <<memory-vkallocationcallbacks-null, vk*Memory>>::pname:pAllocator must: |
| be `NULL` <<SCID-2>>, <<SCID-8>>. |
| * <<memory-vkallocationcallbacks-null, |
| vkRegisterDeviceEventEXT>>::pname:pAllocator must: be `NULL` <<SCID-8>>. |
| // end::scdeviation[] |
| endif::hidden[] |
| |
| [[memory-vkallocationcallbacks-null]] |
| sname:VkAllocationCallbacks is not supported and pointers to this type must: |
| be `NULL` <<SCID-2>>, <<SCID-8>>. |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| ifndef::VKSC_VERSION_1_0[] |
| Allocators are provided by the application as a pointer to a |
| sname:VkAllocationCallbacks structure: |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| include::{generated}/api/structs/VkAllocationCallbacks.adoc[] |
| |
| ifndef::VKSC_VERSION_1_0[] |
| |
| * 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 tlink:PFN_vkAllocationFunction pointer to an |
| application-defined memory allocation function. |
| * pname:pfnReallocation is a tlink:PFN_vkReallocationFunction pointer to |
| an application-defined memory reallocation function. |
| * pname:pfnFree is a tlink:PFN_vkFreeFunction pointer to an |
| application-defined memory free function. |
| * pname:pfnInternalAllocation is a |
| tlink:PFN_vkInternalAllocationNotification pointer to an |
| application-defined function that is called by the implementation when |
| the implementation makes internal allocations. |
| * pname:pfnInternalFree is a tlink:PFN_vkInternalFreeNotification pointer |
| to an application-defined function that is called by the implementation |
| when the implementation frees internal allocations. |
| |
| .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 |
| **** |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| include::{generated}/validity/structs/VkAllocationCallbacks.adoc[] |
| -- |
| |
| ifdef::VKSC_VERSION_1_0[] |
| ifdef::hidden[] |
| // tag::scremoved[] |
| * ename:VkSystemAllocationScope, ename:VkInternalAllocationType <<SCID-8>> |
| // end::scremoved[] |
| endif::hidden[] |
| endif::VKSC_VERSION_1_0[] |
| |
| ifndef::VKSC_VERSION_1_0[] |
| |
| [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.adoc[] |
| |
| * 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 <<memory-host-allocation-scope,here>>. |
| |
| [[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 runtime 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 <<fundamentals-errorcodes, |
| Return Codes>>. |
| |
| 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.adoc[] |
| |
| * 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 a compatible |
| 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 <<memory-host-allocation-scope,here>>. |
| |
| If the reallocation was successful, 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 |
| <<vkAllocationFunction_return_rules, rules for return values as |
| tname:PFN_vkAllocationFunction>>. |
| -- |
| |
| [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.adoc[] |
| |
| * 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.adoc[] |
| |
| * 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 <<memory-host-allocation-scope,here>>. |
| |
| 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.adoc[] |
| |
| * 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 <<memory-host-allocation-scope,here>>. |
| -- |
| |
| [open,refpage='VkSystemAllocationScope',desc='Allocation scope',type='enums',xrefs='VkAllocationCallbacks'] |
| -- |
| [[memory-host-allocation-scope]] |
| Each allocation has an _allocation scope_ defining 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.adoc[] |
| |
| * 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 a |
| ifdef::VK_EXT_validation_cache[] |
| sname:VkValidationCacheEXT or |
| endif::VK_EXT_validation_cache[] |
| sname:VkPipelineCache object, 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.adoc[] |
| |
| * 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 a |
| 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 |
| slink: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, or pname:pfnReallocation with zero pname:size, 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. |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| [[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-device-properties]] |
| === Device Memory Properties |
| |
| 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.adoc[] |
| |
| * pname:physicalDevice is the handle to the device to query. |
| * pname:pMemoryProperties is a pointer to a |
| slink:VkPhysicalDeviceMemoryProperties structure in which the properties |
| are returned. |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceMemoryProperties',desc='Structure specifying physical device memory properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceMemoryProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties.adoc[] |
| |
| * pname:memoryTypeCount is the number of valid elements in the |
| pname:memoryTypes array. |
| * pname:memoryTypes is an array of ename:VK_MAX_MEMORY_TYPES |
| 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 ename:VK_MAX_MEMORY_HEAPS |
| 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[] |
| ifdef::VK_AMD_device_coherent_memory[] |
| * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + |
| ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
| * 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_COHERENT_BIT_AMD |
| * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
| * 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_COHERENT_BIT_AMD |
| * 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_COHERENT_BIT_AMD |
| * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + |
| ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD |
| * 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_COHERENT_BIT_AMD | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD |
| * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD |
| * 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_COHERENT_BIT_AMD | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD |
| * 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_COHERENT_BIT_AMD | + |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD |
| endif::VK_AMD_device_coherent_memory[] |
| ifdef::VK_NV_external_memory_rdma[] |
| * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + |
| ename:VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV |
| endif::VK_NV_external_memory_rdma[] |
| |
| 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. |
| ifdef::VK_AMD_device_coherent_memory[] |
| If the <<features-deviceCoherentMemory, pname:deviceCoherentMemory>> feature |
| is enabled, there must: be at least one memory type with the |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit set in its |
| pname:propertyFlags. |
| endif::VK_AMD_device_coherent_memory[] |
| |
| For each pair of elements *X* and *Y* returned in pname:memoryTypes, *X* |
| must: be placed at a lower index position than *Y* if: |
| |
| * 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) |
| ifdef::VK_AMD_device_coherent_memory[] |
| ; or |
| * the pname:propertyFlags members of *Y* includes |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD or |
| ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD and *X* does not |
| endif::VK_AMD_device_coherent_memory[] |
| |
| [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 <<memory-device-bitmask-list,list of all allowed memory |
| property flag combinations>> 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. |
| ifdef::VK_AMD_device_coherent_memory[] |
| |
| There may be a performance penalty for using device coherent or uncached |
| device memory types, and using these accidentally is undesirable. |
| In order to avoid this, memory types with these properties always appear at |
| the end of the list; but are subject to the same rules otherwise. |
| endif::VK_AMD_device_coherent_memory[] |
| ==== |
| |
| 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<int32_t>(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.adoc[] |
| -- |
| |
| [open,refpage='VK_MAX_MEMORY_TYPES',desc='Length of an array of memory types',type='consts'] |
| -- |
| ename:VK_MAX_MEMORY_TYPES is the length of an array of slink:VkMemoryType |
| structures describing memory types, as returned in |
| slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypes. |
| |
| include::{generated}/api/enums/VK_MAX_MEMORY_TYPES.adoc[] |
| -- |
| |
| [open,refpage='VK_MAX_MEMORY_HEAPS',desc='Length of an array of memory heaps',type='consts'] |
| -- |
| ename:VK_MAX_MEMORY_HEAPS is the length of an array of slink:VkMemoryHeap |
| structures describing memory heaps, as returned in |
| slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps. |
| |
| include::{generated}/api/enums/VK_MAX_MEMORY_HEAPS.adoc[] |
| -- |
| |
| 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.adoc[] |
| 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.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:physicalDevice is the handle to the device to query. |
| * pname:pMemoryProperties is a pointer to a |
| slink: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.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceMemoryProperties2',desc='Structure specifying physical device memory properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceMemoryProperties2 structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2.adoc[] |
| |
| ifdef::VK_KHR_get_physical_device_properties2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2KHR.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memoryProperties is a slink:VkPhysicalDeviceMemoryProperties |
| structure which is populated with the same values as in |
| flink:vkGetPhysicalDeviceMemoryProperties. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceMemoryProperties2.adoc[] |
| -- |
| 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.adoc[] |
| |
| * 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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * 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_VERSION_1_1,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_VERSION_1_1,VK_KHR_device_group_creation[] |
| ifdef::VKSC_VERSION_1_0[] |
| * ename:VK_MEMORY_HEAP_SEU_SAFE_BIT specifies that the heap is protected |
| against single event upsets. |
| ifdef::hidden[] |
| // tag::scaddition[] |
| * extending elink:VkMemoryHeapFlagBits |
| ** ename:VK_MEMORY_HEAP_SEU_SAFE_BIT <<SCID-1>> |
| // end::scaddition[] |
| endif::hidden[] |
| endif::VKSC_VERSION_1_0[] |
| -- |
| |
| ifdef::VKSC_VERSION_1_0[] |
| [NOTE] |
| .Note |
| ==== |
| Many safety critical environments are required to contend with single event |
| upsets (SEUs). |
| It is typical for host memory to include automatic error detection (EDC) or |
| correction (ECC) on platforms where this a concern. |
| ename:VK_MEMORY_HEAP_SEU_SAFE_BIT is used to denote device memory heaps that |
| have this protection. |
| |
| SEU-safe memory may: have different performance characteristics than |
| SEU-unsafe memory. |
| ==== |
| endif::VKSC_VERSION_1_0[] |
| |
| [open,refpage='VkMemoryHeapFlags',desc='Bitmask of VkMemoryHeapFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkMemoryHeapFlags.adoc[] |
| |
| 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.adoc[] |
| |
| * 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.adoc[] |
| -- |
| |
| [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 type, are: |
| |
| include::{generated}/api/enums/VkMemoryPropertyFlagBits.adoc[] |
| |
| * 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 <<memory-device-lazy_allocation, |
| Lazily Allocated Memory>>. |
| 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[] |
| ifdef::VK_AMD_device_coherent_memory[] |
| * ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit specifies that |
| device accesses to allocations of this memory type are automatically |
| made available and visible. |
| * ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD bit specifies that |
| memory allocated with this type is not cached on the device. |
| Uncached device memory is always device coherent. |
| endif::VK_AMD_device_coherent_memory[] |
| ifdef::VK_NV_external_memory_rdma[] |
| * ename:VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV bit specifies that external |
| devices can access this memory directly. |
| endif::VK_NV_external_memory_rdma[] |
| |
| ifdef::VK_AMD_device_coherent_memory[] |
| For any memory allocated with both the |
| ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT and the |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD, host or device accesses |
| also perform automatic memory domain transfer operations, such that writes |
| are always automatically available and visible to both host and device |
| memory domains. |
| |
| [NOTE] |
| .Note |
| ==== |
| Device coherence is a useful property for certain debugging use cases (e.g. |
| crash analysis, where performing separate coherence actions could mean |
| values are not reported correctly). |
| However, device coherent accesses may be slower than equivalent accesses |
| without device coherence, particularly if they are also device uncached. |
| For device uncached memory in particular, repeated accesses to the same or |
| neighbouring memory locations over a short time period (e.g. within a frame) |
| may be slower than it would be for the equivalent cached memory type. |
| As such, it is generally inadvisable to use device coherent or device |
| uncached memory except when really needed. |
| ==== |
| endif::VK_AMD_device_coherent_memory[] |
| -- |
| |
| [open,refpage='VkMemoryPropertyFlags',desc='Bitmask of VkMemoryPropertyFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkMemoryPropertyFlags.adoc[] |
| |
| 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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:heapBudget is an array of ename:VK_MAX_MEMORY_HEAPS |
| basetype:VkDeviceSize values in which memory budgets are returned, 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 ename:VK_MAX_MEMORY_HEAPS |
| basetype:VkDeviceSize values in which memory usages are returned, 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.adoc[] |
| -- |
| endif::VK_EXT_memory_budget[] |
| |
| |
| [[memory-device-objects]] |
| === Device Memory Objects |
| |
| [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.adoc[] |
| -- |
| |
| |
| === Device Memory Allocation |
| |
| [open,refpage='vkAllocateMemory',desc='Allocate device memory',type='protos'] |
| -- |
| :refpage: vkAllocateMemory |
| :objectnameplural: device memory objects |
| :objectnamecamelcase: deviceMemory |
| :objectcount: 1 |
| |
| To allocate memory objects, call: |
| |
| include::{generated}/api/protos/vkAllocateMemory.adoc[] |
| |
| * pname:device is the logical device that owns the memory. |
| * pname:pAllocateInfo is a pointer to a slink:VkMemoryAllocateInfo |
| structure describing parameters of the allocation. |
| A successfully returned allocation must: use the requested parameters -- |
| no substitution is permitted by the implementation. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> 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 the |
| contents 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. |
| The <<limits-maxMemoryAllocationCount, pname:maxMemoryAllocationCount>> |
| feature describes the number of allocations that can: exist simultaneously |
| before encountering these internal limits. |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [NOTE] |
| .Note |
| ==== |
| For historical reasons, if pname:maxMemoryAllocationCount is exceeded, some |
| implementations may return ename:VK_ERROR_TOO_MANY_OBJECTS. |
| Exceeding this limit will result in undefined: behavior, and an application |
| should not rely on the use of the returned error code in order to identify |
| when the limit is reached. |
| ==== |
| endif::VKSC_VERSION_1_0[] |
| |
| [NOTE] |
| .Note |
| ==== |
| Many protected memory implementations involve complex hardware and system |
| software support, and often have additional and much lower limits on the |
| number of simultaneous protected memory allocations (from memory types with |
| the ename:VK_MEMORY_PROPERTY_PROTECTED_BIT property) than for non-protected |
| memory allocations. |
| These limits can be system-wide, and depend on a variety of factors outside |
| of the Vulkan implementation, so they cannot be queried in Vulkan. |
| Applications should: use as few allocations as possible from such memory |
| types by suballocating aggressively, and be prepared for allocation failure |
| even when there is apparently plenty of capacity remaining in the memory |
| heap. |
| As a guideline, the Vulkan conformance test suite requires that at least 80 |
| minimum-size allocations can exist concurrently when no other uses of |
| protected memory are active in the system. |
| ==== |
| |
| Some platforms may: have a limit on the maximum size of a single allocation. |
| For example, certain systems may: fail to create allocations with a size |
| greater than or equal to 4GB. |
| Such a limit is implementation-dependent, and if such a failure occurs then |
| the error 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 |
| `apiext:VK_AMD_memory_overallocation_behavior` extension. |
| |
| endif::VK_AMD_memory_overallocation_behavior[] |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| ifdef::VK_EXT_pageable_device_local_memory[] |
| |
| If the |
| slink:VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pname:pageableDeviceLocalMemory |
| feature is enabled, memory allocations made from a heap that includes |
| ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in slink:VkMemoryHeap::pname:flags |
| may: be transparently moved to host-local memory allowing multiple |
| applications to share device-local memory. |
| If there is no space left in device-local memory when this new allocation is |
| made, other allocations may: be moved out transparently to make room. |
| The operating system will determine which allocations to move to |
| device-local memory or host-local memory based on platform-specific |
| criteria. |
| To help the operating system make good choices, the application should: set |
| the appropriate memory priority with slink:VkMemoryPriorityAllocateInfoEXT |
| and adjust it as necessary with flink:vkSetDeviceMemoryPriorityEXT. |
| Higher priority allocations will moved to device-local memory first. |
| |
| Memory allocations made on heaps without the |
| ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT property will not be transparently |
| promoted to device-local memory by the operating system. |
| |
| endif::VK_EXT_pageable_device_local_memory[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkAllocateMemory-pAllocateInfo-01713]] |
| pname:pAllocateInfo->allocationSize must: be less than or equal to |
| slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps[`memindex`].pname:size |
| where `memindex` = |
| slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypes[pname:pAllocateInfo->memoryTypeIndex].pname:heapIndex |
| as returned by flink:vkGetPhysicalDeviceMemoryProperties for the |
| slink:VkPhysicalDevice that pname:device was created from |
| * [[VUID-vkAllocateMemory-pAllocateInfo-01714]] |
| pname:pAllocateInfo->memoryTypeIndex must: be less than |
| slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypeCount as |
| returned by flink:vkGetPhysicalDeviceMemoryProperties for the |
| slink:VkPhysicalDevice that pname:device was created from |
| ifdef::VK_AMD_device_coherent_memory[] |
| * [[VUID-vkAllocateMemory-deviceCoherentMemory-02790]] |
| If the <<features-deviceCoherentMemory, pname:deviceCoherentMemory>> |
| feature is not enabled, pname:pAllocateInfo->memoryTypeIndex must: not |
| identify a memory type supporting |
| ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD |
| endif::VK_AMD_device_coherent_memory[] |
| * [[VUID-vkAllocateMemory-maxMemoryAllocationCount-04101]] |
| There must: be less than |
| sname:VkPhysicalDeviceLimits::pname:maxMemoryAllocationCount device |
| memory allocations currently allocated on the device |
| include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] |
| **** |
| |
| include::{generated}/validity/protos/vkAllocateMemory.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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. |
| |
| The internal data of an allocated device memory object must: include a |
| reference to implementation-specific resources, referred to as the memory |
| object's _payload_. |
| ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| Applications can: also import and export that internal data to and from |
| device memory objects to share data between Vulkan instances and other |
| compatible APIs. |
| A sname:VkMemoryAllocateInfo structure defines a memory import operation if |
| its pname:pNext chain includes one of the following structures: |
| |
| [[memory-import-operation]] |
| ifdef::VK_KHR_external_memory_win32[] |
| * slink:VkImportMemoryWin32HandleInfoKHR with a 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[] |
| ifdef::VK_FUCHSIA_external_memory[] |
| * slink:VkImportMemoryZirconHandleInfoFUCHSIA with a non-zero |
| pname:handleType value |
| endif::VK_FUCHSIA_external_memory[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * slink:VkImportMemoryBufferCollectionFUCHSIA |
| endif::VK_FUCHSIA_buffer_collection[] |
| ifdef::VK_NV_external_memory_sci_buf[] |
| * slink:VkImportMemorySciBufInfoNV with a non-zero pname:handleType value |
| endif::VK_NV_external_memory_sci_buf[] |
| ifdef::VK_QNX_external_memory_screen_buffer[] |
| * slink:VkImportScreenBufferInfoQNX with a non-`NULL` pname:buffer value |
| endif::VK_QNX_external_memory_screen_buffer[] |
| |
| ifdef::VK_KHR_external_memory_win32[] |
| 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 is ignored. |
| The implementation must: query the size of these allocations from the OS. |
| endif::VK_KHR_external_memory_win32[] |
| |
| ifdef::VK_NV_external_memory_sci_buf[] |
| If the parameters define an import operation and the external handle type is |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV, pname:allocationSize is |
| ignored. |
| The implementation must: query the size of this allocation from the |
| stext:NvSciBufAttrList associated with the external stext:NvSciBufObj. |
| endif::VK_NV_external_memory_sci_buf[] |
| |
| Whether device memory objects constructed via a memory import operation hold |
| a reference to their payload depends on the properties of the handle type |
| used to perform the import, as defined below for each valid handle type. |
| Importing memory must: not modify the content of the memory. |
| Implementations must: ensure that importing memory does not enable the |
| importing Vulkan instance to access any memory or resources in other Vulkan |
| instances other than that corresponding to the memory object imported. |
| Implementations must: also ensure accessing imported memory which has not |
| been initialized does not allow the importing Vulkan instance to obtain data |
| from the exporting Vulkan instance or vice-versa. |
| |
| [NOTE] |
| .Note |
| ==== |
| How exported and imported memory is isolated is left to the implementation, |
| but applications should be aware that such isolation may: prevent |
| implementations from placing multiple exportable memory objects in the same |
| physical or virtual page. |
| Hence, applications should: avoid creating many small external memory |
| objects whenever possible. |
| ==== |
| |
| Importing memory must: not increase overall heap usage within a system. |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance3,VK_EXT_memory_budget[] |
| However, it must: affect the following per-process values: |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance3[] |
| * slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationCount |
| endif::VK_VERSION_1_1,VK_KHR_maintenance3[] |
| ifdef::VK_EXT_memory_budget[] |
| * slink:VkPhysicalDeviceMemoryBudgetPropertiesEXT::pname:heapUsage |
| endif::VK_EXT_memory_budget[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance3,VK_EXT_memory_budget[] |
| |
| When performing a memory import operation, it is the responsibility of the |
| application to ensure the external handles and their associated payloads |
| meet all valid usage requirements. |
| However, implementations must: perform sufficient validation of external |
| handles and payloads to ensure that the operation results in a valid memory |
| object which will not cause program termination, device loss, queue stalls, |
| or corruption of other resources when used as allowed according to its |
| allocation parameters. |
| If the external handle provided does not meet these requirements, the |
| implementation must: fail the memory import operation with the error code |
| ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| If the parameters define an export operation and the external handle type is |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, |
| implementations should: not strictly follow pname:memoryTypeIndex. |
| Instead, they should: modify the allocation internally to use the required |
| memory type for the application's given usage. |
| This is because for an export operation, there is currently no way for the |
| client to know the memory type index before allocating. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-07897]] |
| ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| If the parameters do not define an <<memory-import-operation,import or |
| export operation>>, |
| endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| pname:allocationSize must: be greater than `0` |
| ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| * [[VUID-VkMemoryAllocateInfo-None-06657]] |
| The parameters must: not define more than one |
| <<memory-import-operation,import operation>> |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-07899]] |
| If the parameters define an export operation |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| and the handle type is not |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| , pname:allocationSize must: be greater than `0` |
| endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer,VK_FUCHSIA_external_memory,VK_NV_external_memory_sci_buf,VK_QNX_external_memory_screen_buffer[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * [[VUID-VkMemoryAllocateInfo-buffer-06380]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA, and |
| slink:VkMemoryDedicatedAllocateInfo::pname:buffer is present and |
| non-NULL, slink:VkImportMemoryBufferCollectionFUCHSIA::pname:collection |
| and slink:VkImportMemoryBufferCollectionFUCHSIA::pname:index must match |
| slink:VkBufferCollectionBufferCreateInfoFUCHSIA::pname:collection and |
| slink:VkBufferCollectionBufferCreateInfoFUCHSIA::pname:index, |
| respectively, of the slink:VkBufferCollectionBufferCreateInfoFUCHSIA |
| structure used to create the |
| slink:VkMemoryDedicatedAllocateInfo::pname:buffer |
| * [[VUID-VkMemoryAllocateInfo-image-06381]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA, and |
| slink:VkMemoryDedicatedAllocateInfo::pname:image is present and |
| non-NULL, slink:VkImportMemoryBufferCollectionFUCHSIA::pname:collection |
| and slink:VkImportMemoryBufferCollectionFUCHSIA::pname:index must match |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection and |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:index, |
| respectively, of the slink:VkBufferCollectionImageCreateInfoFUCHSIA |
| structure used to create the |
| slink:VkMemoryDedicatedAllocateInfo::pname:image |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-06382]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA, pname:allocationSize must: match |
| slink:VkMemoryRequirements::pname:size value retrieved by |
| flink:vkGetImageMemoryRequirements or |
| flink:vkGetBufferMemoryRequirements for image-based or buffer-based |
| collections respectively |
| * [[VUID-VkMemoryAllocateInfo-pNext-06383]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA, the pname:pNext chain must: include a |
| slink:VkMemoryDedicatedAllocateInfo structure with either its |
| pname:image or pname:buffer field set to a value other than |
| dlink:VK_NULL_HANDLE |
| * [[VUID-VkMemoryAllocateInfo-image-06384]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA and |
| slink:VkMemoryDedicatedAllocateInfo::pname:image is not |
| dlink:VK_NULL_HANDLE, the pname:image must: be created with a |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA structure chained to its |
| slink:VkImageCreateInfo::pname:pNext pointer |
| * [[VUID-VkMemoryAllocateInfo-buffer-06385]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA and |
| slink:VkMemoryDedicatedAllocateInfo::pname:buffer is not |
| dlink:VK_NULL_HANDLE, the pname:buffer must: be created with a |
| slink:VkBufferCollectionBufferCreateInfoFUCHSIA structure chained to its |
| slink:VkBufferCreateInfo::pname:pNext pointer |
| * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-06386]] |
| If the parameters define an import operation from an |
| slink:VkBufferCollectionFUCHSIA, pname:memoryTypeIndex must: be from |
| slink:VkBufferCollectionPropertiesFUCHSIA as retrieved by |
| flink:vkGetBufferCollectionPropertiesFUCHSIA |
| endif::VK_FUCHSIA_buffer_collection[] |
| ifdef::VK_KHR_external_memory[] |
| ifdef::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-00639]] |
| If the pname:pNext chain includes a sname:VkExportMemoryAllocateInfo |
| structure, 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.externalMemoryFeatures, |
| or by flink:vkGetPhysicalDeviceExternalBufferProperties in |
| sname:VkExternalBufferProperties::pname:externalMemoryProperties.externalMemoryFeatures, |
| the pname:pNext chain must: include a |
| sname:VkMemoryDedicatedAllocateInfo or |
| sname:VkDedicatedAllocationMemoryAllocateInfoNV structure with either |
| its pname:image or pname:buffer member 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 includes a slink:VkExportMemoryAllocateInfo |
| structure, it must: not include a slink:VkExportMemoryAllocateInfoNV or |
| slink:VkExportMemoryWin32HandleInfoNV structure |
| 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 includes a |
| slink:VkImportMemoryWin32HandleInfoKHR structure, it must: not include a |
| slink:VkImportMemoryWin32HandleInfoNV structure |
| 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, then the values of |
| pname:allocationSize and pname:memoryTypeIndex must: match those |
| specified when the payload 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 the mask specified when the |
| payload being imported was allocated |
| * [[VUID-VkMemoryAllocateInfo-None-00644]] |
| If the parameters define an import operation and the external handle |
| specified was created by the Vulkan API, the list of physical devices |
| that comprise the logical device passed to flink:vkAllocateMemory must: |
| match the list of physical devices that comprise the logical device on |
| which the payload 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 or |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, then the |
| values of pname:allocationSize and pname:memoryTypeIndex must: match |
| those specified when the payload being imported was created |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-00647]] |
| If the parameters define an import operation and the external handle |
| type is 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 payload 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 <<features-protectedMemory, pname:protectedMemory>> 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 |
| ifdef::VK_NV_dedicated_allocation[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-02805]] |
| If the parameters define an import operation and the external handle is |
| a host pointer, the pname:pNext chain must: not include a |
| slink:VkDedicatedAllocationMemoryAllocateInfoNV structure with either |
| its pname:image or pname:buffer field set to a value other than |
| dlink:VK_NULL_HANDLE |
| endif::VK_NV_dedicated_allocation[] |
| ifdef::VK_KHR_dedicated_allocation[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-02806]] |
| If the parameters define an import operation and the external handle is |
| a host pointer, the pname:pNext chain must: not include a |
| slink:VkMemoryDedicatedAllocateInfo structure with either its |
| pname:image or pname:buffer field set to a value other than |
| dlink:VK_NULL_HANDLE |
| endif::VK_KHR_dedicated_allocation[] |
| 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 include a |
| slink:VkMemoryDedicatedAllocateInfo structure 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 includes a sname:VkExportMemoryAllocateInfo structure with |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| included in its pname:handleTypes member, and the pname:pNext chain |
| includes a slink:VkMemoryDedicatedAllocateInfo structure with |
| pname:image not equal to dlink:VK_NULL_HANDLE, then pname:allocationSize |
| must: be `0` |
| * [[VUID-VkMemoryAllocateInfo-pNext-07900]] |
| If the parameters define an export operation, the handle type is |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, |
| and the pname:pNext does not include a |
| slink:VkMemoryDedicatedAllocateInfo structure, pname:allocationSize |
| must: be greater than `0` |
| * [[VUID-VkMemoryAllocateInfo-pNext-07901]] |
| If the parameters define an export operation, the handle type is |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, |
| and the pname:pNext chain includes a slink:VkMemoryDedicatedAllocateInfo |
| structure with pname:buffer set to a valid slink:VkBuffer object, |
| 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 a |
| slink:VkMemoryDedicatedAllocateInfo with pname:image that is not |
| dlink:VK_NULL_HANDLE, the Android hardware buffer's |
| basetype:AHardwareBuffer::code:usage must: include at least one of |
| code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER, |
| code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE or |
| code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER |
| * [[VUID-VkMemoryAllocateInfo-pNext-02387]] |
| If the parameters define an import operation, the external handle is an |
| Android hardware buffer, and the pname:pNext chain includes a |
| 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 a |
| slink:VkMemoryDedicatedAllocateInfo structure 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 a |
| slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is |
| not dlink:VK_NULL_HANDLE, and the Android hardware buffer's |
| basetype: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 a |
| slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is |
| not dlink:VK_NULL_HANDLE, and the Android hardware buffer's |
| basetype: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 a |
| slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is |
| not dlink:VK_NULL_HANDLE, each bit set in the usage of pname:image must: |
| be listed in |
| <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage |
| Equivalence>>, 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[] |
| ifdef::VK_QNX_external_memory_screen_buffer[] |
| * [[VUID-VkMemoryAllocateInfo-screenBufferImport-08941]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, |
| slink:VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX::pname:screenBufferImport |
| must: be enabled |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-08942]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, |
| pname:allocationSize must: be the size returned by |
| flink:vkGetScreenBufferPropertiesQNX for the QNX Screen buffer |
| * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-08943]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, |
| pname:memoryTypeIndex must: be one of those returned by |
| flink:vkGetScreenBufferPropertiesQNX for the QNX Screen buffer |
| * [[VUID-VkMemoryAllocateInfo-pNext-08944]] |
| If the parameters define an import operation, the external handle is a |
| QNX Screen buffer, and the pname:pNext chain includes a |
| slink:VkMemoryDedicatedAllocateInfo with pname:image that is not |
| dlink:VK_NULL_HANDLE, the QNX Screen's buffer must be a |
| <<memory-external-screen-buffer-validity,valid QNX Screen buffer>> |
| * [[VUID-VkMemoryAllocateInfo-pNext-08945]] |
| If the parameters define an import operation, the external handle is an |
| QNX Screen buffer, and the pname:pNext chain includes a |
| 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:vkGetScreenBufferPropertiesQNX in |
| slink:VkScreenBufferFormatPropertiesQNX::pname:format for the QNX Screen |
| buffer |
| * [[VUID-VkMemoryAllocateInfo-pNext-08946]] |
| If the parameters define an import operation, the external handle is a |
| QNX Screen buffer, and the pname:pNext chain includes a |
| slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is |
| not dlink:VK_NULL_HANDLE, the width, height, and array layer dimensions |
| of pname:image and the QNX Screen buffer's code:_screen_buffer must be |
| identical |
| endif::VK_QNX_external_memory_screen_buffer[] |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| * [[VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03329]] |
| If |
| slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress |
| is not zero, sname:VkMemoryAllocateFlagsInfo::pname:flags must: include |
| ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT |
| * [[VUID-VkMemoryAllocateInfo-flags-03330]] |
| If sname:VkMemoryAllocateFlagsInfo::pname:flags includes |
| ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the |
| <<features-bufferDeviceAddressCaptureReplay, |
| pname:bufferDeviceAddressCaptureReplay>> feature must: be enabled |
| * [[VUID-VkMemoryAllocateInfo-flags-03331]] |
| If sname:VkMemoryAllocateFlagsInfo::pname:flags includes |
| ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT, the |
| <<features-bufferDeviceAddress, pname:bufferDeviceAddress>> feature |
| must: be enabled |
| ifdef::VK_EXT_external_memory_host[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-03332]] |
| If the pname:pNext chain includes a |
| sname:VkImportMemoryHostPointerInfoEXT structure, |
| slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress |
| must: be zero |
| endif::VK_EXT_external_memory_host[] |
| * [[VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03333]] |
| If the parameters define an import operation, |
| slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress |
| must: be zero |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| ifdef::VK_FUCHSIA_external_memory[] |
| * [[VUID-VkMemoryAllocateInfo-None-04749]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the |
| value of sname:memoryTypeIndex must: be an index identifying a memory |
| type from the sname:memoryTypeBits field of the |
| slink:VkMemoryZirconHandlePropertiesFUCHSIA structure populated by a |
| call to flink:vkGetMemoryZirconHandlePropertiesFUCHSIA |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-07902]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the |
| value of pname:allocationSize must: be greater than `0` |
| * [[VUID-VkMemoryAllocateInfo-allocationSize-07903]] |
| If the parameters define an import operation and the external handle |
| type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the |
| value of pname:allocationSize must: be less than or equal to the size of |
| the VMO as determined by code:zx_vmo_get_size(pname:handle) where |
| pname:handle is the VMO handle to the imported external memory |
| endif::VK_FUCHSIA_external_memory[] |
| ifdef::VK_NV_external_memory_sci_buf[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-05097]] |
| If the pname:pNext chain includes a slink:VkExportMemorySciBufInfoNV |
| structure, |
| slink:VkPhysicalDeviceExternalMemorySciBufFeaturesNV::pname:sciBufExport |
| must: be enabled |
| * [[VUID-VkMemoryAllocateInfo-pNext-05098]] |
| If the pname:pNext chain includes a slink:VkImportMemorySciBufInfoNV |
| structure, |
| slink:VkPhysicalDeviceExternalMemorySciBufFeaturesNV::pname:sciBufImport |
| must: be enabled |
| * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-05099]] |
| If the parameters define an import operation and the external handle is |
| a stext:NvSciBufObj, the value of pname:memoryTypeIndex must: be one of |
| those returned by |
| flink:vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV |
| endif::VK_NV_external_memory_sci_buf[] |
| ifdef::VK_EXT_metal_objects[] |
| * [[VUID-VkMemoryAllocateInfo-pNext-06780]] |
| If the pname:pNext chain includes a |
| slink:VkExportMetalObjectCreateInfoEXT structure, its |
| pname:exportObjectType member must: be |
| ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_BUFFER_BIT_EXT |
| endif::VK_EXT_metal_objects[] |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryAllocateInfo.adoc[] |
| -- |
| |
| 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.adoc[] |
| |
| ifdef::VK_KHR_dedicated_allocation[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkMemoryDedicatedAllocateInfoKHR.adoc[] |
| endif::VK_KHR_dedicated_allocation[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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-02964]] |
| If pname:image is not dlink:VK_NULL_HANDLE |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] |
| and the memory is not an imported |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[Android Hardware Buffer] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer+VK_QNX_external_memory_screen_buffer[or an imported] |
| ifdef::VK_QNX_external_memory_screen_buffer[QNX Screen buffer] |
| endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] |
| , 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 |
| slink:VkImageCreateInfo::pname:flags |
| * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-02965]] |
| If pname:buffer is not dlink:VK_NULL_HANDLE |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] |
| and the memory is not an imported |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[Android Hardware Buffer] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer+VK_QNX_external_memory_screen_buffer[or an imported] |
| ifdef::VK_QNX_external_memory_screen_buffer[QNX Screen buffer] |
| endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] |
| , 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[] |
| ifdef::VK_FUCHSIA_external_memory[] |
| * [[VUID-VkMemoryDedicatedAllocateInfo-image-04751]] |
| 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_ZIRCON_VMO_BIT_FUCHSIA, 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-04752]] |
| 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_ZIRCON_VMO_BIT_FUCHSIA, 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_FUCHSIA_external_memory[] |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryDedicatedAllocateInfo.adoc[] |
| -- |
| 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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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 |
| slink: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 |
| slink: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.adoc[] |
| -- |
| 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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| endif::VK_EXT_memory_priority[] |
| |
| ifdef::VK_EXT_pageable_device_local_memory[] |
| [open,refpage='vkSetDeviceMemoryPriorityEXT',desc='Change a memory allocation priority',type='protos'] |
| -- |
| To modify the priority of an existing memory allocation, call: |
| |
| include::{generated}/api/protos/vkSetDeviceMemoryPriorityEXT.adoc[] |
| |
| * pname:device is the logical device that owns the memory. |
| * pname:memory is the slink:VkDeviceMemory object to which the new |
| priority will be applied. |
| * 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkSetDeviceMemoryPriorityEXT-priority-06258]] |
| pname:priority must: be between `0` and `1`, inclusive |
| **** |
| |
| include::{generated}/validity/protos/vkSetDeviceMemoryPriorityEXT.adoc[] |
| -- |
| endif::VK_EXT_pageable_device_local_memory[] |
| |
| 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 whose payload 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.adoc[] |
| |
| ifdef::VK_KHR_external_memory[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkExportMemoryAllocateInfoKHR.adoc[] |
| endif::VK_KHR_external_memory[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleTypes is zero or 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.adoc[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| ifdef::VK_NV_external_memory[] |
| include::{chapters}/VK_NV_external_memory/allocate_memory.adoc[] |
| endif::VK_NV_external_memory[] |
| |
| ifdef::VK_KHR_external_memory_win32,VK_NV_external_memory_win32[] |
| === Win32 External Memory |
| endif::VK_KHR_external_memory_win32,VK_NV_external_memory_win32[] |
| |
| 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 a 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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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 |
| payload referenced by NT handles exported from the created memory. |
| |
| If slink:VkExportMemoryAllocateInfo is not included in the same pname:pNext |
| chain, this structure is ignored. |
| |
| If slink:VkExportMemoryAllocateInfo is included in the pname:pNext chain of |
| slink:VkMemoryAllocateInfo with a Windows pname:handleType, but either |
| sname:VkExportMemoryWin32HandleInfoKHR is not included in the pname:pNext |
| chain, or it is included but 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 used depend on |
| the handle type. |
| |
| For handles of the following types: |
| |
| * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT |
| |
| The implementation must: ensure the access rights allow read and write |
| access to the memory. |
| |
| 1:: |
| https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657]] |
| If slink:VkExportMemoryAllocateInfo::pname:handleTypes does not include |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, a |
| sname:VkExportMemoryWin32HandleInfoKHR structure must: not be included |
| in the pname:pNext chain of slink:VkMemoryAllocateInfo |
| **** |
| |
| include::{generated}/validity/structs/VkExportMemoryWin32HandleInfoKHR.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying the type of pname:handle or pname:name. |
| * pname:handle is `NULL` or the external handle to import. |
| * pname:name is `NULL` or a null-terminated UTF-16 string naming the |
| payload to import. |
| |
| Importing memory object payloads 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 handle |
| ownership using the code:CloseHandle system call when the handle is no |
| longer needed. |
| For handle types defined as NT handles, the imported memory object holds a |
| reference to its payload. |
| |
| [NOTE] |
| .Note |
| ==== |
| Non-NT handle import operations do not add a reference to their associated |
| payload. |
| If the original object owning the payload is destroyed, all resources and |
| handles sharing that payload will become invalid. |
| ==== |
| |
| Applications can: import the same payload 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 |
| <<external-memory-handle-types-compatibility,external memory handle |
| types compatibility>> |
| * [[VUID-VkImportMemoryWin32HandleInfoKHR-name-01519]] |
| If pname:name is not `NULL`, it must: obey any requirements listed for |
| pname:handleType in |
| <<external-memory-handle-types-compatibility,external memory handle |
| types compatibility>> |
| **** |
| |
| include::{generated}/validity/structs/VkImportMemoryWin32HandleInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemoryWin32HandleKHR',desc='Get a Windows HANDLE for a memory object',type='protos'] |
| -- |
| To export a Windows handle representing the payload of a Vulkan device |
| memory object, call: |
| |
| include::{generated}/api/protos/vkGetMemoryWin32HandleKHR.adoc[] |
| |
| * pname:device is the logical device that created the device memory being |
| exported. |
| * pname:pGetWin32HandleInfo is a pointer to a |
| slink:VkMemoryGetWin32HandleInfoKHR structure containing parameters of |
| the export operation. |
| * pname:pHandle will return the Windows handle representing the payload of |
| the device memory object. |
| |
| For handle types defined as NT handles, the handles returned by |
| fname:vkGetMemoryWin32HandleKHR are owned by the application and hold a |
| reference to their payload. |
| To avoid leaking resources, the application must: release ownership of them |
| using the code:CloseHandle system call when they are no longer needed. |
| |
| [NOTE] |
| .Note |
| ==== |
| Non-NT handle types do not add a reference to their associated payload. |
| If the original object owning the payload is destroyed, all resources and |
| handles sharing that payload will become invalid. |
| ==== |
| |
| include::{generated}/validity/protos/vkGetMemoryWin32HandleKHR.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle memory export operation',type='structs'] |
| -- |
| The sname:VkMemoryGetWin32HandleInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryGetWin32HandleInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memory is the memory object from which the handle will be |
| exported. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:device is the logical device that will be importing pname:handle. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying the type of the handle pname:handle. |
| * pname:handle is the handle which will be imported. |
| * pname:pMemoryWin32HandleProperties is a pointer to a |
| slink:VkMemoryWin32HandlePropertiesKHR structure in which properties of |
| pname:handle are returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handle-00665]] |
| pname:handle must: point to a valid Windows memory handle |
| * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-00666]] |
| pname:handleType must: not be one of the handle types defined as opaque |
| **** |
| |
| include::{generated}/validity/protos/vkGetMemoryWin32HandlePropertiesKHR.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| endif::VK_KHR_external_memory_win32[] |
| |
| ifdef::VK_NV_external_memory_win32[] |
| include::{chapters}/VK_NV_external_memory_win32/handle_permissions.adoc[] |
| |
| include::{chapters}/VK_NV_external_memory_win32/import_memory_win32.adoc[] |
| |
| include::{chapters}/VK_NV_external_memory_win32/get_handle_win32.adoc[] |
| endif::VK_NV_external_memory_win32[] |
| |
| ifdef::VK_KHR_external_memory_fd[] |
| === File Descriptor External Memory |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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. |
| The imported memory object holds a reference to its payload. |
| |
| Applications can: import the same payload 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 |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT |
| * [[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 |
| <<external-memory-handle-types-compatibility>> |
| * [[VUID-VkImportMemoryFdInfoKHR-fd-01520]] |
| pname:fd must: obey any requirements listed for pname:handleType in |
| <<external-memory-handle-types-compatibility,external memory handle |
| types compatibility>> |
| **** |
| |
| include::{generated}/validity/structs/VkImportMemoryFdInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemoryFdKHR',desc='Get a POSIX file descriptor for a memory object',type='protos'] |
| -- |
| |
| :refpage: vkGetMemoryFdKHR |
| |
| To export a POSIX file descriptor referencing the payload of a Vulkan device |
| memory object, call: |
| |
| include::{generated}/api/protos/vkGetMemoryFdKHR.adoc[] |
| |
| * pname:device is the logical device that created the device memory being |
| exported. |
| * pname:pGetFdInfo is a pointer to a slink:VkMemoryGetFdInfoKHR structure |
| containing parameters of the export operation. |
| * pname:pFd will return a file descriptor referencing the payload of the |
| device memory object. |
| |
| Each call to fname:vkGetMemoryFdKHR must: create a new file descriptor |
| holding a reference to the memory object's payload and transfer ownership of |
| the file descriptor 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::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| include::{generated}/validity/protos/vkGetMemoryFdKHR.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryGetFdInfoKHR',desc='Structure describing a POSIX FD memory export operation',type='structs'] |
| -- |
| The sname:VkMemoryGetFdInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryGetFdInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memory is the memory object from which the handle will be |
| exported. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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::pname: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:https://man7.org/linux/man-pages/man2/lseek.2.html[`lseek`]. |
| ==== |
| 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 |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryGetFdInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemoryFdPropertiesKHR',desc='Get Properties of External Memory File Descriptors',type='protos'] |
| -- |
| |
| :refpage: vkGetMemoryFdPropertiesKHR |
| |
| 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.adoc[] |
| |
| * pname:device is the logical device that will be importing pname:fd. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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. |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetMemoryFdPropertiesKHR-fd-00673]] |
| pname:fd must: point to a valid POSIX file descriptor memory handle |
| * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]] |
| pname:handleType must: not be |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT |
| **** |
| |
| include::{generated}/validity/protos/vkGetMemoryFdPropertiesKHR.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| endif::VK_KHR_external_memory_fd[] |
| |
| ifdef::VK_EXT_external_memory_host[] |
| === Host External Memory |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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 payload as defined in |
| <<memory-device-hostaccess,Host Access to Device Memory Objects>>. |
| |
| Applications can: import the same payload into multiple instances of Vulkan |
| and multiple times into a given Vulkan instance. |
| However, implementations may: fail to import the same payload 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. |
| |
| Whether device memory objects imported from a host pointer hold a reference |
| to their payload is undefined:. |
| As such, 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:VkExternalMemoryProperties |
| * [[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.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemoryHostPointerPropertiesEXT',desc='Get properties of external memory host pointer',type='protos'] |
| -- |
| |
| :refpage: vkGetMemoryHostPointerPropertiesEXT |
| |
| To determine the correct parameters to use when importing host pointers, |
| call: |
| |
| include::{generated}/api/protos/vkGetMemoryHostPointerPropertiesEXT.adoc[] |
| |
| * pname:device is the logical device that will be importing |
| pname:pHostPointer. |
| * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value |
| specifying 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. |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| .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.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryHostPointerPropertiesEXT',desc='Properties of external memory host pointer',type='structs'] |
| -- |
| The sname:VkMemoryHostPointerPropertiesEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryHostPointerPropertiesEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| |
| endif::VK_EXT_external_memory_host[] |
| |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| === Android Hardware Buffer External Memory |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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:usage compatible with |
| Vulkan as described in <<memory-external-android-hardware-buffer,Android |
| Hardware Buffers>> |
| **** |
| |
| include::{generated}/validity/structs/VkImportAndroidHardwareBufferInfoANDROID.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemoryAndroidHardwareBufferANDROID',desc='Get an Android hardware buffer for a memory object',type='protos'] |
| -- |
| To export an Android hardware buffer referencing the payload of a Vulkan |
| device memory object, call: |
| |
| include::{generated}/api/protos/vkGetMemoryAndroidHardwareBufferANDROID.adoc[] |
| |
| * pname:device is the logical device that created the device memory being |
| exported. |
| * pname:pInfo is a pointer to a |
| slink:VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing |
| parameters of the export operation. |
| * pname:pBuffer will return an Android hardware buffer referencing the |
| payload 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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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:VkExportMemoryAllocateInfo::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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * 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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| |
| [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 a |
| sname:VkAndroidHardwareBufferFormatPropertiesANDROID structure in the |
| pname:pNext chain of the slink:VkAndroidHardwareBufferPropertiesANDROID |
| structure passed to flink:vkGetAndroidHardwareBufferPropertiesANDROID. |
| This structure is defined as: |
| |
| include::{generated}/api/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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 |
| <<memory-external-android-hardware-buffer-formats,Format Equivalence |
| table>>, 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 |
| <<memory-external-android-hardware-buffer-external-formats,external-format |
| image>> 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 {YCbCr} conversion even if the non-external |
| format does not, and rendering directly to the external format will not be |
| supported even if the non-external format does support this. |
| ==== |
| |
| 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 the |
| <<resources-image-views-identity-mappings,identity swizzle>>. |
| |
| 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 |
| {GLregistry}/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 |
| {GLregistry}/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.adoc[] |
| -- |
| |
| ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] |
| [open,refpage='VkAndroidHardwareBufferFormatProperties2ANDROID',desc='Structure describing the image format properties of an Android hardware buffer',type='structs'] |
| -- |
| The format properties of an Android hardware buffer can: be obtained by |
| including a sname:VkAndroidHardwareBufferFormatProperties2ANDROID structure |
| in the pname:pNext chain of the |
| slink:VkAndroidHardwareBufferPropertiesANDROID structure passed to |
| flink:vkGetAndroidHardwareBufferPropertiesANDROID. |
| This structure is defined as: |
| |
| include::{generated}/api/structs/VkAndroidHardwareBufferFormatProperties2ANDROID.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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. |
| |
| The bits reported in pname:formatFeatures must: include the bits reported in |
| the corresponding fields of |
| sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures. |
| |
| include::{generated}/validity/structs/VkAndroidHardwareBufferFormatProperties2ANDROID.adoc[] |
| -- |
| endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] |
| |
| ifdef::VK_ANDROID_external_format_resolve[] |
| [open,refpage='VkAndroidHardwareBufferFormatResolvePropertiesANDROID',desc='Structure defining properties of resolves using an external format',type='structs'] |
| -- |
| The slink:VkAndroidHardwareBufferFormatResolvePropertiesANDROID structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkAndroidHardwareBufferFormatResolvePropertiesANDROID.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:colorAttachmentFormat is a elink:VkFormat specifying the format of |
| color attachment images that must: be used for color attachments when |
| resolving to the specified external format. |
| If the implementation supports external format resolves for the |
| specified external format, this value will be set to a color format |
| supporting the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT in |
| slink:VkFormatProperties::pname:optimalTilingFeatures as returned by |
| flink:vkGetPhysicalDeviceFormatProperties with pname:format equal to |
| pname:colorAttachmentFormat If external format resolves are not |
| supported, this value will be set to `VK_FORMAT_UNDEFINED`. |
| |
| Any Android hardware buffer created with the code:GRALLOC_USAGE_HW_RENDER |
| flag must: be renderable in some way in Vulkan, either: |
| |
| * slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format must: |
| be a format that supports ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT |
| or ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT in |
| slink:VkFormatProperties::pname:optimalTilingFeatures; or |
| * pname:colorAttachmentFormat must: be a format that supports |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT in |
| slink:VkFormatProperties::pname:optimalTilingFeatures. |
| |
| include::{generated}/validity/structs/VkAndroidHardwareBufferFormatResolvePropertiesANDROID.adoc[] |
| -- |
| endif::VK_ANDROID_external_format_resolve[] |
| |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| |
| ifdef::VK_NV_external_memory_rdma[] |
| === Remote Device External Memory |
| |
| [open,refpage='vkGetMemoryRemoteAddressNV',desc='Get an address for a memory object accessible by remote devices',type='protos'] |
| -- |
| To export an address representing the payload of a Vulkan device memory |
| object accessible by remote devices, call: |
| |
| include::{generated}/api/protos/vkGetMemoryRemoteAddressNV.adoc[] |
| |
| * pname:device is the logical device that created the device memory being |
| exported. |
| * pname:pMemoryGetRemoteAddressInfo is a pointer to a |
| slink:VkMemoryGetRemoteAddressInfoNV structure containing parameters of |
| the export operation. |
| * pname:pAddress is a pointer to a basetype:VkRemoteAddressNV value in |
| which an address representing the payload of the device memory object is |
| returned. |
| |
| More communication may be required between the kernel-mode drivers of the |
| devices involved. |
| This information is out of scope of this documentation and should be |
| requested from the vendors of the devices. |
| |
| include::{generated}/validity/protos/vkGetMemoryRemoteAddressNV.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryGetRemoteAddressInfoNV',desc='Structure describing a remote accessible address export operation',type='structs'] |
| -- |
| The sname:VkMemoryGetRemoteAddressInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryGetRemoteAddressInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memory is the memory object from which the remote accessible |
| address will be exported. |
| * pname:handleType is the type of handle requested. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkMemoryGetRemoteAddressInfoNV-handleType-04966]] |
| pname:handleType must: have been included in |
| slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory |
| was created |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryGetRemoteAddressInfoNV.adoc[] |
| -- |
| |
| [open,refpage='VkRemoteAddressNV',desc='Remote device address type',type='basetypes'] |
| -- |
| basetype:VkRemoteAddressNV represents an address of a memory object |
| accessible by remote devices, as returned in |
| flink:vkGetMemoryRemoteAddressNV::pname:pAddress. |
| |
| include::{generated}/api/basetypes/VkRemoteAddressNV.adoc[] |
| -- |
| endif::VK_NV_external_memory_rdma[] |
| |
| ifdef::VK_FUCHSIA_external_memory[] |
| include::{chapters}/VK_FUCHSIA_external_memory/device_memory.adoc[] |
| endif::VK_FUCHSIA_external_memory[] |
| |
| ifdef::VK_EXT_metal_objects[] |
| include::{chapters}/VK_EXT_metal_objects/device_memory.adoc[] |
| endif::VK_EXT_metal_objects[] |
| |
| ifdef::VK_NV_external_memory_sci_buf[] |
| === NvSciBuf External Memory |
| |
| [open,refpage='VkExportMemorySciBufInfoNV',desc='Structure specifying attributes of stext:NvSciBufObj exported from memory',type='structs'] |
| -- |
| To export a stext:NvSciBufObj from memory, add a |
| slink:VkExportMemorySciBufInfoNV structure to the pname:pNext chain of the |
| slink:VkMemoryAllocateInfo structure. |
| The sname:VkExportMemorySciBufInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkExportMemorySciBufInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pAttributes is an opaque sname:NvSciBufAttrList describing the |
| attributes of the NvSciBuf object that will be exported. |
| |
| If slink:VkExportMemoryAllocateInfo is not present in the same pname:pNext |
| chain, this structure is ignored. |
| |
| If the pname:pNext chain of slink:VkMemoryAllocateInfo includes a |
| slink:VkExportMemoryAllocateInfo structure with a pname:handleType mask |
| containing the ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV bit, but |
| either sname:VkExportMemorySciBufInfoNV is not included in the pname:pNext |
| chain, or it is included but pname:pAttributes is set to `NULL`, |
| flink:vkAllocateMemory will return ename:VK_ERROR_INITIALIZATION_FAILED. |
| |
| The pname:pAttributes parameter must: be a reconciled |
| stext:NvSciBufAttrList. |
| stext:NvSciBufAttrList consists of both public and private attributes. |
| It is the application's responsibility to set the public attributes. |
| To set the private attributes, the application must: use the |
| flink:vkGetPhysicalDeviceSciBufAttributesNV command. |
| The stext:NvSciBufAttrList is then reconciled using the |
| <<NvSciBuf-extension-page, NvSciBuf APIs>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkExportMemorySciBufInfoNV-pAttributes-05100]] |
| pname:pAttributes must: be a reconciled stext:NvSciBufAttrList |
| **** |
| |
| include::{generated}/validity/structs/VkExportMemorySciBufInfoNV.adoc[] |
| -- |
| |
| [open,refpage='vkGetPhysicalDeviceSciBufAttributesNV',desc='Fill the private attributes of the stext:NvSciBufAttrList struct',type='protos'] |
| -- |
| To fill the private attributes of an unreconciled stext:NvSciBufAttrList, |
| call: |
| |
| include::{generated}/api/protos/vkGetPhysicalDeviceSciBufAttributesNV.adoc[] |
| |
| * pname:physicalDevice is the handle to the physical device that will be |
| used to determine the attributes. |
| * pname:pAttributes is an opaque stext:NvSciBufAttrList in which the |
| implementation will set the requested attributes. |
| |
| On success, pname:pAttributes will contain an unreconciled |
| stext:NvSciBufAttrList whose private attributes are filled in by the |
| implementation. |
| If the private attributes of pname:physicalDevice could not be obtained, |
| ename:VK_ERROR_INITIALIZATION_FAILED is returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetPhysicalDeviceSciBufAttributesNV-pAttributes-05101]] |
| pname:pAttributes must: be a valid stext:NvSciBufAttrList and must: not |
| be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceSciBufAttributesNV.adoc[] |
| -- |
| |
| [open,refpage='VkImportMemorySciBufInfoNV',desc='import NvSciBuf memory created on the same physical device',type='structs'] |
| -- |
| To import memory from a stext:NvSciBufObj, add a |
| slink:VkImportMemorySciBufInfoNV structure to the pname:pNext chain of the |
| slink:VkMemoryAllocateInfo structure. |
| |
| The sname:VkImportMemorySciBufInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkImportMemorySciBufInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleType specifies the type of handle or name. |
| * pname:handle is the external handle to import. |
| |
| Importing memory from a stext:NvSciBufObj does not transfer ownership of the |
| stext:NvSciBufObj from the application to the Vulkan implementation. |
| Vulkan will increment the reference count of the underlying memory of the |
| imported stext:NvSciBufObj. |
| The application must: release its ownership using <<NvSciBuf-extension-page, |
| NvSciBuf APIs>> when that ownership is no longer needed. |
| |
| Applications can: import the same payload 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. |
| |
| After successfully importing the stext:NvSciBufObj to sname:VkDeviceMemory, |
| the application can: use it as a normal sname:VkDeviceMemory object. |
| It is the application's responsibility to synchronize the different |
| stext:NvSciBufObj accesses. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImportMemorySciBufInfoNV-handleType-05102]] |
| pname:handleType must: be |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV |
| **** |
| |
| include::{generated}/validity/structs/VkImportMemorySciBufInfoNV.adoc[] |
| -- |
| |
| [open,refpage='vkGetMemorySciBufNV',desc='Get a stext:NvSciBufObj handle for a memory object',type='protos'] |
| -- |
| To export a stext:NvSciBufObj representing the payload of a Vulkan device |
| memory object, call: |
| |
| include::{generated}/api/protos/vkGetMemorySciBufNV.adoc[] |
| |
| * pname:device is the logical device that created the device memory being |
| exported. |
| * pname:pGetSciBufInfo is a pointer to a slink:VkMemoryGetSciBufInfoNV |
| structure containing parameters of the export operation. |
| * pname:pHandle will return the stext:NvSciBufObj representing the payload |
| of the device memory object. |
| |
| A call to fname:vkGetMemorySciBufNV will not transfer the ownership of the |
| stext:NvSciBufObj handle to the application. |
| The application will hold a reference to the stext:NvSciBufObj, but it does |
| not add a reference count to the stext:NvSciBufObj, so the application must: |
| not release it. |
| |
| include::{generated}/validity/protos/vkGetMemorySciBufNV.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryGetSciBufInfoNV',desc='Structure describing a stext:NvSciBufObj handle memory export operation',type='structs'] |
| -- |
| The sname:VkMemoryGetSciBufInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryGetSciBufInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memory is the memory object from which the handle will be |
| exported. |
| * pname:handleType is the type of handle requested. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkMemoryGetSciBufInfoNV-handleType-05103]] |
| pname:handleType must: be |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryGetSciBufInfoNV.adoc[] |
| -- |
| |
| [open,refpage='vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV',desc='Get physical device properties of External Memory stext:NvSciBufObj Handles',type='protos'] |
| -- |
| A stext:NvSciBufObj handle compatible with Vulkan can: 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/vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV.adoc[] |
| |
| * pname:physicalDevice is the handle to the physical device whose |
| properties will be queried. |
| * pname:handleType is the type of the handle pname:handle. |
| * pname:handle is the stext:NvSciBuffObj handle which will be imported. |
| * pname:pMemorySciBufProperties is a pointer to a |
| slink:VkMemorySciBufPropertiesNV structure. |
| |
| This command will return properties of pname:handle, it contains the memory |
| type bitmask that can: be used to determine the |
| slink:VkMemoryAllocateInfo::pname:memoryTypeIndex when calling |
| flink:vkAllocateMemory. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV-handleType-05104]] |
| pname:handleType must: be |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV |
| * [[VUID-vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV-sciBufImport-05105]] |
| slink:VkPhysicalDeviceExternalMemorySciBufFeaturesNV::pname:sciBufImport |
| must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceExternalMemorySciBufPropertiesNV.adoc[] |
| -- |
| |
| [open,refpage='VkMemorySciBufPropertiesNV',desc='Structure describing properties of External Memory stext:NvSciBufObj Handles',type='structs'] |
| -- |
| The sname:VkMemorySciBufPropertiesNV structure is defined as: |
| |
| include::{generated}/api/structs/VkMemorySciBufPropertiesNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memoryTypeBits is a bitmask containing one bit set for every |
| memory type for which the specified stext:NvSciBufObj handle can: be |
| imported. |
| |
| include::{generated}/validity/structs/VkMemorySciBufPropertiesNV.adoc[] |
| -- |
| endif::VK_NV_external_memory_sci_buf[] |
| |
| ifdef::VK_QNX_external_memory_screen_buffer[] |
| include::{chapters}/VK_QNX_external_memory_screen_buffer/device_memory.adoc[] |
| endif::VK_QNX_external_memory_screen_buffer[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| === Device Group Memory Allocations |
| |
| [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.adoc[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkMemoryAllocateFlagsInfoKHR.adoc[] |
| endif::VK_KHR_device_group[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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.adoc[] |
| -- |
| |
| [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.adoc[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkMemoryAllocateFlagBitsKHR.adoc[] |
| 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. |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| * ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT specifies that the memory |
| can: be attached to a buffer object created with the |
| ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT bit set in pname:usage, |
| and that the memory handle can: be used to retrieve an opaque address |
| via flink:vkGetDeviceMemoryOpaqueCaptureAddress. |
| * ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies |
| that the memory's address can: be saved and reused on a subsequent run |
| (e.g. for trace capture and replay), see |
| slink:VkBufferOpaqueCaptureAddressCreateInfo for more detail. |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| -- |
| |
| [open,refpage='VkMemoryAllocateFlags',desc='Bitmask of VkMemoryAllocateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkMemoryAllocateFlags.adoc[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/flags/VkMemoryAllocateFlagsKHR.adoc[] |
| 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[] |
| |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| === Opaque Capture Address Allocation |
| |
| [open,refpage='VkMemoryOpaqueCaptureAddressAllocateInfo',desc='Request a specific address for a memory allocation',type='structs',alias='VkMemoryOpaqueCaptureAddressAllocateInfoKHR'] |
| -- |
| To request a specific device address for a memory allocation, add a |
| slink:VkMemoryOpaqueCaptureAddressAllocateInfo structure to the pname:pNext |
| chain of the slink:VkMemoryAllocateInfo structure. |
| The sname:VkMemoryOpaqueCaptureAddressAllocateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryOpaqueCaptureAddressAllocateInfo.adoc[] |
| |
| ifdef::VK_KHR_buffer_device_address[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkMemoryOpaqueCaptureAddressAllocateInfoKHR.adoc[] |
| endif::VK_KHR_buffer_device_address[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:opaqueCaptureAddress is the opaque capture address requested for |
| the memory allocation. |
| |
| If pname:opaqueCaptureAddress is zero, no specific address is requested. |
| |
| If pname:opaqueCaptureAddress is not zero, it should: be an address |
| retrieved from flink:vkGetDeviceMemoryOpaqueCaptureAddress on an identically |
| created memory allocation on the same implementation. |
| |
| [NOTE] |
| .Note |
| ==== |
| In most cases, it is expected that a non-zero pname:opaqueAddress is an |
| address retrieved from flink:vkGetDeviceMemoryOpaqueCaptureAddress on an |
| identically created memory allocation. |
| If this is not the case, it is likely that |
| ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors will occur. |
| |
| This is, however, not a strict requirement because trace capture/replay |
| tools may need to adjust memory allocation parameters for imported memory. |
| ==== |
| |
| If this structure is not present, it is as if pname:opaqueCaptureAddress is |
| zero. |
| |
| include::{generated}/validity/structs/VkMemoryOpaqueCaptureAddressAllocateInfo.adoc[] |
| -- |
| |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| |
| |
| === Freeing Device Memory |
| |
| ifdef::VKSC_VERSION_1_0[] |
| ifdef::hidden[] |
| // tag::scremoved[] |
| * fname:vkFreeMemory <<SCID-4>> |
| // end::scremoved[] |
| endif::hidden[] |
| |
| Device memory cannot: be freed <<SCID-4>>. |
| If |
| slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> |
| is ename:VK_TRUE, the memory is returned to the system when the device is |
| destroyed. |
| |
| endif::VKSC_VERSION_1_0[] |
| ifndef::VKSC_VERSION_1_0[] |
| [open,refpage='vkFreeMemory',desc='Free device memory',type='protos'] |
| -- |
| To free a memory object, call: |
| |
| include::{generated}/api/protos/vkFreeMemory.adoc[] |
| |
| * 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 |
| <<memory-allocation, Memory Allocation>> 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. |
| Freeing a memory object releases the reference it held, if any, to its |
| payload. |
| If there are still any bound images or buffers, the memory object's payload |
| may: not be immediately released by the implementation, but must: be |
| released by the time all bound images and buffers have been destroyed. |
| Once all references to a payload are released, it is returned to the heap |
| from which it was allocated. |
| |
| How memory objects are bound to Images and Buffers is described in detail in |
| the <<resources-association, Resource Memory Association>> section. |
| |
| If a memory object is mapped at the time it is freed, it is implicitly |
| unmapped. |
| |
| [NOTE] |
| .Note |
| ==== |
| As described <<memory-device-unmap-does-not-flush, below>>, host writes are |
| not implicitly flushed when the memory object is unmapped, but the |
| implementation must: guarantee that writes that have not been flushed do not |
| affect any other memory. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[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.adoc[] |
| -- |
| endif::VKSC_VERSION_1_0[] |
| |
| [[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'] |
| -- |
| |
| :refpage: vkMapMemory |
| |
| To retrieve a host virtual address pointer to a region of a mappable memory |
| object, call: |
| |
| include::{generated}/api/protos/vkMapMemory.adoc[] |
| |
| * 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 is a pointer to a code:void* variable in which a |
| host-accessible pointer to the beginning of the mapped range is |
| returned. |
| 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_. |
| |
| [NOTE] |
| .Note |
| ==== |
| 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 |
| <<synchronization-submission-host-writes, here>> 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 |
| <<synchronization, Synchronization and Cache Control>> as they are crucial |
| to maintaining memory access ordering. |
| ==== |
| |
| ifdef::VK_KHR_map_memory2[] |
| Calling fname:vkMapMemory is equivalent to calling flink:vkMapMemory2KHR |
| with an empty pname:pNext chain. |
| endif::VK_KHR_map_memory2[] |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| .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.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryMapFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkMemoryMapFlags.adoc[] |
| |
| tname:VkMemoryMapFlags is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| -- |
| |
| ifdef::VK_KHR_map_memory2[] |
| [open,refpage='vkMapMemory2KHR',desc='Map a memory object into application address space',type='protos'] |
| -- |
| Alternatively, to retrieve a host virtual address pointer to a region of a |
| mappable memory object, call: |
| |
| include::{generated}/api/protos/vkMapMemory2KHR.adoc[] |
| |
| * pname:device is the logical device that owns the memory. |
| * pname:pMemoryMapInfo is a pointer to a slink:VkMemoryMapInfoKHR |
| structure describing parameters of the map. |
| * pname:ppData is a pointer to a `void *` variable in which is returned a |
| host-accessible pointer to the beginning of the mapped range. |
| This pointer minus slink:VkMemoryMapInfoKHR::pname:offset must: be |
| aligned to at least |
| slink:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment. |
| |
| This function behaves identically to flink:vkMapMemory except that it gets |
| its parameters via an extensible structure pointer rather than directly as |
| function arguments. |
| |
| include::{generated}/validity/protos/vkMapMemory2KHR.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryMapInfoKHR',desc='Structure containing parameters of a memory map operation',type='structs'] |
| -- |
| The sname:VkMemoryMapInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryMapInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkMemoryMapInfoKHR-memory-07958]] |
| pname:memory must: not be currently host mapped |
| * [[VUID-VkMemoryMapInfoKHR-offset-07959]] |
| pname:offset must: be less than the size of pname:memory |
| * [[VUID-VkMemoryMapInfoKHR-size-07960]] |
| If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be |
| greater than `0` |
| * [[VUID-VkMemoryMapInfoKHR-size-07961]] |
| 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-VkMemoryMapInfoKHR-memory-07962]] |
| 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-VkMemoryMapInfoKHR-memory-07963]] |
| pname:memory must: not have been allocated with multiple instances |
| endif::VK_KHR_device_group[] |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryMapInfoKHR.adoc[] |
| -- |
| endif::VK_KHR_map_memory2[] |
| |
| 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, <<synchronization-dependencies-available-and-visible, availability |
| and visibility operations>> still need to be managed on the device. |
| See the description of <<synchronization-host-access-types, host access |
| types>> 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[] |
| |
| After a successful call to fname:vkMapMemory |
| ifdef::VK_KHR_map_memory2[] |
| or fname:vkMapMemory2KHR |
| endif::VK_KHR_map_memory2[] |
| the memory object pname:memory is considered to be currently _host mapped_. |
| |
| [open,refpage='vkFlushMappedMemoryRanges',desc='Flush mapped memory ranges',type='protos'] |
| -- |
| |
| :refpage: vkFlushMappedMemoryRanges |
| |
| To flush ranges of non-coherent memory from the host caches, call: |
| |
| include::{generated}/api/protos/vkFlushMappedMemoryRanges.adoc[] |
| |
| * 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 <<synchronization-dependencies-available-and-visible, memory |
| domain operations>> using the ename:VK_ACCESS_HOST_WRITE_BIT |
| <<synchronization-access-types,access type>>. |
| |
| 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::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| include::{generated}/validity/protos/vkFlushMappedMemoryRanges.adoc[] |
| -- |
| |
| [open,refpage='vkInvalidateMappedMemoryRanges',desc='Invalidate ranges of mapped memory objects',type='protos'] |
| -- |
| |
| :refpage: vkInvalidateMappedMemoryRanges |
| |
| To invalidate ranges of non-coherent memory from the host caches, call: |
| |
| include::{generated}/api/protos/vkInvalidateMappedMemoryRanges.adoc[] |
| |
| * 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 <<synchronization-access-types, access |
| types>>, are made visible to the host. |
| If a range of non-coherent memory is written by the host and then |
| invalidated without first being flushed, its contents are undefined:. |
| |
| Within each range described by 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 that memory. |
| ==== |
| |
| include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] |
| |
| include::{generated}/validity/protos/vkInvalidateMappedMemoryRanges.adoc[] |
| -- |
| |
| [open,refpage='VkMappedMemoryRange',desc='Structure specifying a mapped memory range',type='structs'] |
| -- |
| The sname:VkMappedMemoryRange structure is defined as: |
| |
| include::{generated}/api/structs/VkMappedMemoryRange.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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-offset-00687]] |
| pname:offset must: be a multiple of |
| slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize |
| * [[VUID-VkMappedMemoryRange-size-01389]] |
| If pname:size is equal to ename:VK_WHOLE_SIZE, the end of the current |
| mapping of pname:memory must: either be a multiple of |
| slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize bytes from the |
| beginning of the memory object, or be equal to the end of the memory |
| object |
| * [[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.adoc[] |
| -- |
| |
| |
| [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.adoc[] |
| |
| * pname:device is the logical device that owns the memory. |
| * pname:memory is the memory object to be unmapped. |
| |
| ifdef::VK_KHR_map_memory2[] |
| Calling fname:vkUnmapMemory is equivalent to calling flink:vkUnmapMemory2KHR |
| with an empty pname:pNext chain and the flags parameter set to zero. |
| endif::VK_KHR_map_memory2[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkUnmapMemory-memory-00689]] |
| pname:memory must: be currently host mapped |
| **** |
| |
| include::{generated}/validity/protos/vkUnmapMemory.adoc[] |
| -- |
| |
| ifdef::VK_KHR_map_memory2[] |
| [open,refpage='vkUnmapMemory2KHR',desc='Unmap a previously mapped memory object',type='protos'] |
| -- |
| Alternatively, to unmap a memory object once host access to it is no longer |
| needed by the application, call: |
| |
| include::{generated}/api/protos/vkUnmapMemory2KHR.adoc[] |
| |
| * pname:device is the logical device that owns the memory. |
| * pname:pMemoryUnmapInfo is a pointer to a slink:VkMemoryUnmapInfoKHR |
| structure describing parameters of the unmap. |
| |
| This function behaves identically to flink:vkUnmapMemory except that it gets |
| its parameters via an extensible structure pointer rather than directly as |
| function arguments. |
| |
| include::{generated}/validity/protos/vkUnmapMemory2KHR.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryUnmapInfoKHR',desc='Structure containing parameters of a memory unmap operation',type='structs'] |
| -- |
| The sname:VkMemoryUnmapInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryUnmapInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * pname:memory is the slink:VkDeviceMemory object to be unmapped. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkMemoryUnmapInfoKHR-memory-07964]] |
| pname:memory must: be currently host mapped |
| **** |
| |
| include::{generated}/validity/structs/VkMemoryUnmapInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryUnmapFlagsKHR',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkMemoryUnmapFlagsKHR.adoc[] |
| |
| tname:VkMemoryMapFlagsKHR is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| -- |
| endif::VK_KHR_map_memory2[] |
| |
| [[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.adoc[] |
| |
| * 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 |
| pname: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.adoc[] |
| -- |
| |
| |
| 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 |
| |
| ifdef::VK_EXT_pipeline_protected_access[] |
| [NOTE] |
| .Note |
| ==== |
| When the <<features-protectedMemory, pname:protectedMemory>> feature is |
| enabled, all pipelines may: be recorded in either protected or unprotected |
| command buffers (or both), which may incur an extra cost on some |
| implementations. |
| This can: be mitigated by enabling the <<features-pipelineProtectedAccess, |
| pname:pipelineProtectedAccess>> feature, in which case pipelines created |
| with ename:VK_PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT_EXT may only be |
| recorded in protected command buffers, and pipelines created with |
| ename:VK_PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT_EXT may only be recorded in |
| unprotected command buffers. |
| ==== |
| endif::VK_EXT_pipeline_protected_access[] |
| |
| |
| [[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. |
| |
| 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. |
| |
| Additionally, indirect operations must: not be performed within protected |
| queue operations. |
| |
| 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 basetype: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. |
| An slink:VkImage or slink:VkBuffer can: be bound to the imported or exported |
| slink:VkDeviceMemory object if it is created with |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. |
| |
| [open,refpage='AHardwareBuffer',desc='Android hardware buffer type',type='basetypes'] |
| -- |
| To remove an unnecessary compile time dependency, an incomplete type |
| definition of basetype:AHardwareBuffer is provided in the Vulkan headers: |
| |
| include::{generated}/api/basetypes/AHardwareBuffer.adoc[] |
| |
| The actual basetype:AHardwareBuffer type is defined in Android NDK headers. |
| -- |
| |
| [NOTE] |
| .Note |
| ==== |
| The NDK format, usage, and size/dimensions of an basetype: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 |
| basetype: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 <<resources-external-sharing,External Resource Sharing>> 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 |
| <<synchronization-queue-transfers>> 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 |
| <<memory-external-android-hardware-buffer-usage, usage equivalence table>> |
| which do not have Android hardware buffer equivalents. |
| |
| An slink:VkAndroidHardwareBufferUsageANDROID structure can: be included in |
| the pname:pNext chain of a slink:VkImageFormatProperties2 structure 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 |
| ifdef::VK_ANDROID_external_format_resolve[] |
| resolve images or |
| endif::VK_ANDROID_external_format_resolve[] |
| sampled images, and must: have optimal tiling. |
| Images with external formats must: only be sampled with a sampler that has |
| {YCbCr} conversion enabled. |
| |
| 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 a slink:VkExternalFormatANDROID |
| structure 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 |
| <<memory-external-android-hardware-buffer-formats,equivalent Vulkan format>> |
| 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 a slink:VkAndroidHardwareBufferFormatPropertiesANDROID structure 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 |
| slink: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 |
| basetype: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 |
| <<memory-external-android-hardware-buffer-formats,AHardwareBuffer Format |
| Equivalence>>. |
| * 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 |
| <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage |
| Equivalence>>. |
| 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_FRAMEBUFFER ^3^ | ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT |
| | code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER ^3^ | ename:VK_IMAGE_USAGE_DEPTH_STENCIL_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 |
| | code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER ^4^ | ename:VK_IMAGE_USAGE_STORAGE_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 component are undefined:. |
| To emulate the traditional behavior of the X component 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. |
| |
| 3:: |
| Only image usages valid for the format are valid. |
| It would be invalid to take a Android Hardware Buffer with a format of |
| code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM that has a |
| code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER usage and try to create an |
| image with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT. |
| |
| 4:: |
| In combination with a hardware buffer format other than code:BLOB. |
| |
| ifdef::VK_VERSION_1_2,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:VkImageFormatListCreateInfo 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_VERSION_1_2,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 basetype: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_QNX_external_memory_screen_buffer[] |
| ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| [[memory-external-handle-types]] |
| === External Memory Handle Types |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| include::{chapters}/VK_QNX_external_memory_screen_buffer/qnx_screen_buffer.adoc[] |
| endif::VK_QNX_external_memory_screen_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.adoc[] |
| 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.adoc[] |
| 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 |
| tlink:VkPeerMemoryFeatureFlags bitmask 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.adoc[] |
| -- |
| |
| [open,refpage='VkPeerMemoryFeatureFlagBits',desc='Bitmask specifying supported peer memory features',type='enums'] |
| -- |
| Bits which may: be set in |
| flink:vkGetDeviceGroupPeerMemoryFeatures::pname:pPeerMemoryFeatures, |
| indicating supported peer memory features, are: |
| |
| include::{generated}/api/enums/VkPeerMemoryFeatureFlagBits.adoc[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkPeerMemoryFeatureFlagBitsKHR.adoc[] |
| endif::VK_KHR_device_group[] |
| |
| * ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT specifies that the memory can: |
| be accessed as the source of any ftext:vkCmdCopy* command. |
| * ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT specifies that the memory can: |
| be accessed as the destination of any ftext:vkCmdCopy* 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 <<synchronization-image-layout-transitions, image |
| layout transitions>>. |
| ==== |
| |
| ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must: be supported for all host |
| local heaps and for at least one device-local memory 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.adoc[] |
| |
| ifdef::VK_KHR_device_group[] |
| or the equivalent |
| |
| include::{generated}/api/flags/VkPeerMemoryFeatureFlagsKHR.adoc[] |
| 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[] |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| === Opaque Capture Address Query |
| |
| [open,refpage='vkGetDeviceMemoryOpaqueCaptureAddress',desc='Query an opaque capture address of a memory object',type='protos',alias='vkGetDeviceMemoryOpaqueCaptureAddressKHR'] |
| -- |
| To query a 64-bit opaque capture address value from a memory object, call: |
| |
| ifdef::VK_VERSION_1_2[] |
| include::{generated}/api/protos/vkGetDeviceMemoryOpaqueCaptureAddress.adoc[] |
| endif::VK_VERSION_1_2[] |
| |
| ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] |
| |
| ifdef::VK_KHR_buffer_device_address[] |
| include::{generated}/api/protos/vkGetDeviceMemoryOpaqueCaptureAddressKHR.adoc[] |
| endif::VK_KHR_buffer_device_address[] |
| |
| * pname:device is the logical device that the memory object was allocated |
| on. |
| * pname:pInfo is a pointer to a |
| slink:VkDeviceMemoryOpaqueCaptureAddressInfo structure specifying the |
| memory object to retrieve an address for. |
| |
| The 64-bit return value is an opaque address representing the start of |
| pname:pInfo->memory. |
| |
| If the memory object was allocated with a non-zero value of |
| slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress, |
| the return value must: be the same address. |
| |
| [NOTE] |
| .Note |
| ==== |
| The expected usage for these opaque addresses is only for trace |
| capture/replay tools to store these addresses in a trace and subsequently |
| specify them during replay. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetDeviceMemoryOpaqueCaptureAddress-None-03334]] |
| The <<features-bufferDeviceAddress, pname:bufferDeviceAddress>> feature |
| must: be enabled |
| * [[VUID-vkGetDeviceMemoryOpaqueCaptureAddress-device-03335]] |
| If pname:device was created with multiple physical devices, then the |
| <<features-bufferDeviceAddressMultiDevice, |
| pname:bufferDeviceAddressMultiDevice>> feature must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkGetDeviceMemoryOpaqueCaptureAddress.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceMemoryOpaqueCaptureAddressInfo',desc='Structure specifying the memory object to query an address for',type='structs',alias='VkDeviceMemoryOpaqueCaptureAddressInfoKHR'] |
| -- |
| The sname:VkDeviceMemoryOpaqueCaptureAddressInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceMemoryOpaqueCaptureAddressInfo.adoc[] |
| |
| ifdef::VK_KHR_buffer_device_address[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDeviceMemoryOpaqueCaptureAddressInfoKHR.adoc[] |
| endif::VK_KHR_buffer_device_address[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memory specifies the memory whose address is being queried. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-memory-03336]] |
| pname:memory must: have been allocated with |
| ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceMemoryOpaqueCaptureAddressInfo.adoc[] |
| -- |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
