• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2015-2021 The Khronos Group, Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[memory]]
6= Memory Allocation
7
8Vulkan memory is broken up into two categories, _host memory_ and _device
9memory_.
10
11
12[[memory-host]]
13== Host Memory
14
15Host memory is memory needed by the Vulkan implementation for
16non-device-visible storage.
17
18[NOTE]
19.Note
20====
21This memory may: be used to store the implementation's representation and
22state of Vulkan objects.
23====
24
25[[memory-allocation]]
26Vulkan provides applications the opportunity to perform host memory
27allocations on behalf of the Vulkan implementation.
28If this feature is not used, the implementation will perform its own memory
29allocations.
30Since most memory allocations are off the critical path, this is not meant
31as a performance feature.
32Rather, this can: be useful for certain embedded systems, for debugging
33purposes (e.g. putting a guard page after all host allocations), or for
34memory allocation logging.
35
36[open,refpage='VkAllocationCallbacks',desc='Structure containing callback function pointers for memory allocation',type='structs']
37--
38Allocators are provided by the application as a pointer to a
39sname:VkAllocationCallbacks structure:
40
41include::{generated}/api/structs/VkAllocationCallbacks.txt[]
42
43  * pname:pUserData is a value to be interpreted by the implementation of
44    the callbacks.
45    When any of the callbacks in sname:VkAllocationCallbacks are called, the
46    Vulkan implementation will pass this value as the first parameter to the
47    callback.
48    This value can: vary each time an allocator is passed into a command,
49    even when the same object takes an allocator in multiple commands.
50  * pname:pfnAllocation is a tlink:PFN_vkAllocationFunction pointer to an
51    application-defined memory allocation function.
52  * pname:pfnReallocation is a tlink:PFN_vkReallocationFunction pointer to
53    an application-defined memory reallocation function.
54  * pname:pfnFree is a tlink:PFN_vkFreeFunction pointer to an
55    application-defined memory free function.
56  * pname:pfnInternalAllocation is a
57    tlink:PFN_vkInternalAllocationNotification pointer to an
58    application-defined function that is called by the implementation when
59    the implementation makes internal allocations.
60  * pname:pfnInternalFree is a tlink:PFN_vkInternalFreeNotification pointer
61    to an application-defined function that is called by the implementation
62    when the implementation frees internal allocations.
63
64.Valid Usage
65****
66  * [[VUID-VkAllocationCallbacks-pfnAllocation-00632]]
67    pname:pfnAllocation must: be a valid pointer to a valid user-defined
68    tlink:PFN_vkAllocationFunction
69  * [[VUID-VkAllocationCallbacks-pfnReallocation-00633]]
70    pname:pfnReallocation must: be a valid pointer to a valid user-defined
71    tlink:PFN_vkReallocationFunction
72  * [[VUID-VkAllocationCallbacks-pfnFree-00634]]
73    pname:pfnFree must: be a valid pointer to a valid user-defined
74    tlink:PFN_vkFreeFunction
75  * [[VUID-VkAllocationCallbacks-pfnInternalAllocation-00635]]
76    If either of pname:pfnInternalAllocation or pname:pfnInternalFree is not
77    `NULL`, both must: be valid callbacks
78****
79
80include::{generated}/validity/structs/VkAllocationCallbacks.txt[]
81--
82
83[open,refpage='PFN_vkAllocationFunction',desc='Application-defined memory allocation function',type='funcpointers',xrefs='VkAllocationCallbacks']
84--
85The type of pname:pfnAllocation is:
86
87include::{generated}/api/funcpointers/PFN_vkAllocationFunction.txt[]
88
89  * pname:pUserData is the value specified for
90    slink:VkAllocationCallbacks::pname:pUserData in the allocator specified
91    by the application.
92  * pname:size is the size in bytes of the requested allocation.
93  * pname:alignment is the requested alignment of the allocation in bytes
94    and must: be a power of two.
95  * pname:allocationScope is a elink:VkSystemAllocationScope value
96    specifying the allocation scope of the lifetime of the allocation, as
97    described <<memory-host-allocation-scope,here>>.
98
99[[vkAllocationFunction_return_rules]]
100If pname:pfnAllocation is unable to allocate the requested memory, it must:
101return `NULL`.
102If the allocation was successful, it must: return a valid pointer to memory
103allocation containing at least pname:size bytes, and with the pointer value
104being a multiple of pname:alignment.
105
106[NOTE]
107.Note
108====
109Correct Vulkan operation cannot: be assumed if the application does not
110follow these rules.
111
112For example, pname:pfnAllocation (or pname:pfnReallocation) could cause
113termination of running Vulkan instance(s) on a failed allocation for
114debugging purposes, either directly or indirectly.
115In these circumstances, it cannot: be assumed that any part of any affected
116slink:VkInstance objects are going to operate correctly (even
117flink:vkDestroyInstance), and the application must: ensure it cleans up
118properly via other means (e.g. process termination).
119====
120
121If pname:pfnAllocation returns `NULL`, and if the implementation is unable
122to continue correct processing of the current command without the requested
123allocation, it must: treat this as a runtime error, and generate
124ename:VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command in
125which the condition was detected, as described in <<fundamentals-errorcodes,
126Return Codes>>.
127
128If the implementation is able to continue correct processing of the current
129command without the requested allocation, then it may: do so, and must: not
130generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed
131allocation.
132--
133
134[open,refpage='PFN_vkReallocationFunction',desc='Application-defined memory reallocation function',type='funcpointers',xrefs='VkAllocationCallbacks']
135--
136The type of pname:pfnReallocation is:
137
138include::{generated}/api/funcpointers/PFN_vkReallocationFunction.txt[]
139
140  * pname:pUserData is the value specified for
141    slink:VkAllocationCallbacks::pname:pUserData in the allocator specified
142    by the application.
143  * pname:pOriginal must: be either `NULL` or a pointer previously returned
144    by pname:pfnReallocation or pname:pfnAllocation of a compatible
145    allocator.
146  * pname:size is the size in bytes of the requested allocation.
147  * pname:alignment is the requested alignment of the allocation in bytes
148    and must: be a power of two.
149  * pname:allocationScope is a elink:VkSystemAllocationScope value
150    specifying the allocation scope of the lifetime of the allocation, as
151    described <<memory-host-allocation-scope,here>>.
152
153pname:pfnReallocation must: return an allocation with enough space for
154pname:size bytes, and the contents of the original allocation from bytes
155zero to [eq]#min(original size, new size) - 1# must: be preserved in the
156returned allocation.
157If pname:size is larger than the old size, the contents of the additional
158space are undefined:.
159If satisfying these requirements involves creating a new allocation, then
160the old allocation should: be freed.
161
162If pname:pOriginal is `NULL`, then pname:pfnReallocation must: behave
163equivalently to a call to tlink:PFN_vkAllocationFunction with the same
164parameter values (without pname:pOriginal).
165
166If pname:size is zero, then pname:pfnReallocation must: behave equivalently
167to a call to tlink:PFN_vkFreeFunction with the same pname:pUserData
168parameter value, and pname:pMemory equal to pname:pOriginal.
169
170If pname:pOriginal is non-`NULL`, the implementation must: ensure that
171pname:alignment is equal to the pname:alignment used to originally allocate
172pname:pOriginal.
173
174If this function fails and pname:pOriginal is non-`NULL` the application
175must: not free the old allocation.
176
177pname:pfnReallocation must: follow the same
178<<vkAllocationFunction_return_rules, rules for return values as
179tname:PFN_vkAllocationFunction>>.
180--
181
182[open,refpage='PFN_vkFreeFunction',desc='Application-defined memory free function',type='funcpointers',xrefs='VkAllocationCallbacks']
183--
184The type of pname:pfnFree is:
185
186include::{generated}/api/funcpointers/PFN_vkFreeFunction.txt[]
187
188  * pname:pUserData is the value specified for
189    slink:VkAllocationCallbacks::pname:pUserData in the allocator specified
190    by the application.
191  * pname:pMemory is the allocation to be freed.
192
193pname:pMemory may: be `NULL`, which the callback must: handle safely.
194If pname:pMemory is non-`NULL`, it must: be a pointer previously allocated
195by pname:pfnAllocation or pname:pfnReallocation.
196The application should: free this memory.
197--
198
199[open,refpage='PFN_vkInternalAllocationNotification',desc='Application-defined memory allocation notification function',type='funcpointers',xrefs='VkAllocationCallbacks']
200--
201The type of pname:pfnInternalAllocation is:
202
203include::{generated}/api/funcpointers/PFN_vkInternalAllocationNotification.txt[]
204
205  * pname:pUserData is the value specified for
206    slink:VkAllocationCallbacks::pname:pUserData in the allocator specified
207    by the application.
208  * pname:size is the requested size of an allocation.
209  * pname:allocationType is a elink:VkInternalAllocationType value
210    specifying the requested type of an allocation.
211  * pname:allocationScope is a elink:VkSystemAllocationScope value
212    specifying the allocation scope of the lifetime of the allocation, as
213    described <<memory-host-allocation-scope,here>>.
214
215This is a purely informational callback.
216--
217
218[open,refpage='PFN_vkInternalFreeNotification',desc='Application-defined memory free notification function',type='funcpointers',xrefs='VkAllocationCallbacks']
219--
220The type of pname:pfnInternalFree is:
221
222include::{generated}/api/funcpointers/PFN_vkInternalFreeNotification.txt[]
223
224  * pname:pUserData is the value specified for
225    slink:VkAllocationCallbacks::pname:pUserData in the allocator specified
226    by the application.
227  * pname:size is the requested size of an allocation.
228  * pname:allocationType is a elink:VkInternalAllocationType value
229    specifying the requested type of an allocation.
230  * pname:allocationScope is a elink:VkSystemAllocationScope value
231    specifying the allocation scope of the lifetime of the allocation, as
232    described <<memory-host-allocation-scope,here>>.
233--
234
235[open,refpage='VkSystemAllocationScope',desc='Allocation scope',type='enums',xrefs='VkAllocationCallbacks']
236--
237[[memory-host-allocation-scope]]
238Each allocation has an _allocation scope_ defining its lifetime and which
239object it is associated with.
240Possible values passed to the pname:allocationScope parameter of the
241callback functions specified by slink:VkAllocationCallbacks, indicating the
242allocation scope, are:
243
244include::{generated}/api/enums/VkSystemAllocationScope.txt[]
245
246  * ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND specifies that the allocation
247    is scoped to the duration of the Vulkan command.
248  * ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT specifies that the allocation is
249    scoped to the lifetime of the Vulkan object that is being created or
250    used.
251  * ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE specifies that the allocation is
252    scoped to the lifetime of a sname:VkPipelineCache
253ifdef::VK_EXT_validation_cache[]
254    or sname:VkValidationCacheEXT
255endif::VK_EXT_validation_cache[]
256    object.
257  * ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE specifies that the allocation is
258    scoped to the lifetime of the Vulkan device.
259  * ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE specifies that the allocation
260    is scoped to the lifetime of the Vulkan instance.
261
262Most Vulkan commands operate on a single object, or there is a sole object
263that is being created or manipulated.
264When an allocation uses an allocation scope of
265ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or
266ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the
267object being created or manipulated.
268
269When an implementation requires host memory, it will make callbacks to the
270application using the most specific allocator and allocation scope
271available:
272
273  * If an allocation is scoped to the duration of a command, the allocator
274    will use the ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND allocation scope.
275    The most specific allocator available is used: if the object being
276    created or manipulated has an allocator, that object's allocator will be
277    used, else if the parent sname:VkDevice has an allocator it will be
278    used, else if the parent sname:VkInstance has an allocator it will be
279    used.
280    Else,
281  * If an allocation is associated with a
282ifdef::VK_EXT_validation_cache[]
283    sname:VkValidationCacheEXT or
284endif::VK_EXT_validation_cache[]
285    sname:VkPipelineCache object, the allocator will use the
286    ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE allocation scope.
287    The most specific allocator available is used (cache, else device, else
288    instance).
289    Else,
290  * If an allocation is scoped to the lifetime of an object, that object is
291    being created or manipulated by the command, and that object's type is
292    not sname:VkDevice or sname:VkInstance, the allocator will use an
293    allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT.
294    The most specific allocator available is used (object, else device, else
295    instance).
296    Else,
297  * If an allocation is scoped to the lifetime of a device, the allocator
298    will use an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE.
299    The most specific allocator available is used (device, else instance).
300    Else,
301  * If the allocation is scoped to the lifetime of an instance and the
302    instance has an allocator, its allocator will be used with an allocation
303    scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE.
304  * Otherwise an implementation will allocate memory through an alternative
305    mechanism that is unspecified.
306
307--
308
309Objects that are allocated from pools do not specify their own allocator.
310When an implementation requires host memory for such an object, that memory
311is sourced from the object's parent pool's allocator.
312
313The application is not expected to handle allocating memory that is intended
314for execution by the host due to the complexities of differing security
315implementations across multiple platforms.
316The implementation will allocate such memory internally and invoke an
317application provided informational callback when these _internal
318allocations_ are allocated and freed.
319Upon allocation of executable memory, pname:pfnInternalAllocation will be
320called.
321Upon freeing executable memory, pname:pfnInternalFree will be called.
322An implementation will only call an informational callback for executable
323memory allocations and frees.
324
325[open,refpage='VkInternalAllocationType',desc='Allocation type',type='enums',xrefs='PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification']
326--
327The pname:allocationType parameter to the pname:pfnInternalAllocation and
328pname:pfnInternalFree functions may: be one of the following values:
329
330include::{generated}/api/enums/VkInternalAllocationType.txt[]
331
332  * ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the
333    allocation is intended for execution by the host.
334--
335
336An implementation must: only make calls into an application-provided
337allocator during the execution of an API command.
338An implementation must: only make calls into an application-provided
339allocator from the same thread that called the provoking API command.
340The implementation should: not synchronize calls to any of the callbacks.
341If synchronization is needed, the callbacks must: provide it themselves.
342The informational callbacks are subject to the same restrictions as the
343allocation callbacks.
344
345If an implementation intends to make calls through a
346sname:VkAllocationCallbacks structure between the time a ftext:vkCreate*
347command returns and the time a corresponding ftext:vkDestroy* command
348begins, that implementation must: save a copy of the allocator before the
349ftext:vkCreate* command returns.
350The callback functions and any data structures they rely upon must: remain
351valid for the lifetime of the object they are associated with.
352
353If an allocator is provided to a ftext:vkCreate* command, a _compatible_
354allocator must: be provided to the corresponding ftext:vkDestroy* command.
355Two sname:VkAllocationCallbacks structures are compatible if memory
356allocated with pname:pfnAllocation or pname:pfnReallocation in each can: be
357freed with pname:pfnReallocation or pname:pfnFree in the other.
358An allocator must: not be provided to a ftext:vkDestroy* command if an
359allocator was not provided to the corresponding ftext:vkCreate* command.
360
361If a non-`NULL` allocator is used, the pname:pfnAllocation,
362pname:pfnReallocation and pname:pfnFree members must: be non-`NULL` and
363point to valid implementations of the callbacks.
364An application can: choose to not provide informational callbacks by setting
365both pname:pfnInternalAllocation and pname:pfnInternalFree to `NULL`.
366pname:pfnInternalAllocation and pname:pfnInternalFree must: either both be
367`NULL` or both be non-`NULL`.
368
369If pname:pfnAllocation or pname:pfnReallocation fail, the implementation
370may: fail object creation and/or generate a
371ename:VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate.
372
373Allocation callbacks must: not call any Vulkan commands.
374
375The following sets of rules define when an implementation is permitted to
376call the allocator callbacks.
377
378pname:pfnAllocation or pname:pfnReallocation may: be called in the following
379situations:
380
381  * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be
382    allocated from any API command.
383  * Allocations scoped to a command may: be allocated from any API command.
384  * Allocations scoped to a sname:VkPipelineCache may: only be allocated
385    from:
386  ** fname:vkCreatePipelineCache
387  ** fname:vkMergePipelineCaches for pname:dstCache
388  ** fname:vkCreateGraphicsPipelines for pname:pipelineCache
389  ** fname:vkCreateComputePipelines for pname:pipelineCache
390ifdef::VK_EXT_validation_cache[]
391  * Allocations scoped to a sname:VkValidationCacheEXT may: only be
392    allocated from:
393  ** fname:vkCreateValidationCacheEXT
394  ** fname:vkMergeValidationCachesEXT for pname:dstCache
395  ** fname:vkCreateShaderModule for pname:validationCache in
396     slink:VkShaderModuleValidationCacheCreateInfoEXT
397endif::VK_EXT_validation_cache[]
398  * Allocations scoped to a sname:VkDescriptorPool may: only be allocated
399    from:
400  ** any command that takes the pool as a direct argument
401  ** fname:vkAllocateDescriptorSets for the pname:descriptorPool member of
402     its pname:pAllocateInfo parameter
403  ** fname:vkCreateDescriptorPool
404  * Allocations scoped to a sname:VkCommandPool may: only be allocated from:
405  ** any command that takes the pool as a direct argument
406  ** fname:vkCreateCommandPool
407  ** fname:vkAllocateCommandBuffers for the pname:commandPool member of its
408     pname:pAllocateInfo parameter
409  ** any ftext:vkCmd* command whose pname:commandBuffer was allocated from
410     that sname:VkCommandPool
411  * Allocations scoped to any other object may: only be allocated in that
412    object's ftext:vkCreate* command.
413
414pname:pfnFree, or pname:pfnReallocation with zero pname:size, may: be called
415in the following situations:
416
417  * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be freed
418    from any API command.
419  * Allocations scoped to a command must: be freed by any API command which
420    allocates such memory.
421  * Allocations scoped to a sname:VkPipelineCache may: be freed from
422    fname:vkDestroyPipelineCache.
423ifdef::VK_EXT_validation_cache[]
424  * Allocations scoped to a sname:VkValidationCacheEXT may: be freed from
425    fname:vkDestroyValidationCacheEXT.
426endif::VK_EXT_validation_cache[]
427  * Allocations scoped to a sname:VkDescriptorPool may: be freed from
428  ** any command that takes the pool as a direct argument
429  * Allocations scoped to a sname:VkCommandPool may: be freed from:
430  ** any command that takes the pool as a direct argument
431  ** fname:vkResetCommandBuffer whose pname:commandBuffer was allocated from
432     that sname:VkCommandPool
433  * Allocations scoped to any other object may: be freed in that object's
434    ftext:vkDestroy* command.
435  * Any command that allocates host memory may: also free host memory of the
436    same scope.
437
438
439[[memory-device]]
440== Device Memory
441
442_Device memory_ is memory that is visible to the device -- for example the
443contents of the image or buffer objects, which can: be natively used by the
444device.
445
446[[memory-device-properties]]
447=== Device Memory Properties
448
449Memory properties of a physical device describe the memory heaps and memory
450types available.
451
452[open,refpage='vkGetPhysicalDeviceMemoryProperties',desc='Reports memory information for the specified physical device',type='protos']
453--
454To query memory properties, call:
455
456include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties.txt[]
457
458  * pname:physicalDevice is the handle to the device to query.
459  * pname:pMemoryProperties is a pointer to a
460    slink:VkPhysicalDeviceMemoryProperties structure in which the properties
461    are returned.
462
463include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[]
464--
465
466[open,refpage='VkPhysicalDeviceMemoryProperties',desc='Structure specifying physical device memory properties',type='structs']
467--
468The sname:VkPhysicalDeviceMemoryProperties structure is defined as:
469
470include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties.txt[]
471
472  * pname:memoryTypeCount is the number of valid elements in the
473    pname:memoryTypes array.
474  * pname:memoryTypes is an array of ename:VK_MAX_MEMORY_TYPES
475    slink:VkMemoryType structures describing the _memory types_ that can: be
476    used to access memory allocated from the heaps specified by
477    pname:memoryHeaps.
478  * pname:memoryHeapCount is the number of valid elements in the
479    pname:memoryHeaps array.
480  * pname:memoryHeaps is an array of ename:VK_MAX_MEMORY_HEAPS
481    slink:VkMemoryHeap structures describing the _memory heaps_ from which
482    memory can: be allocated.
483
484The sname:VkPhysicalDeviceMemoryProperties structure describes a number of
485_memory heaps_ as well as a number of _memory types_ that can: be used to
486access memory allocated in those heaps.
487Each heap describes a memory resource of a particular size, and each memory
488type describes a set of memory properties (e.g. host cached vs uncached)
489that can: be used with a given memory heap.
490Allocations using a particular memory type will consume resources from the
491heap indicated by that memory type's heap index.
492More than one memory type may: share each heap, and the heaps and memory
493types provide a mechanism to advertise an accurate size of the physical
494memory resources while allowing the memory to be used with a variety of
495different properties.
496
497The number of memory heaps is given by pname:memoryHeapCount and is less
498than or equal to ename:VK_MAX_MEMORY_HEAPS.
499Each heap is described by an element of the pname:memoryHeaps array as a
500slink:VkMemoryHeap structure.
501The number of memory types available across all memory heaps is given by
502pname:memoryTypeCount and is less than or equal to
503ename:VK_MAX_MEMORY_TYPES.
504Each memory type is described by an element of the pname:memoryTypes array
505as a slink:VkMemoryType structure.
506
507At least one heap must: include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in
508slink:VkMemoryHeap::pname:flags.
509If there are multiple heaps that all have similar performance
510characteristics, they may: all include
511ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT.
512In a unified memory architecture (UMA) system there is often only a single
513memory heap which is considered to be equally "`local`" to the host and to
514the device, and such an implementation must: advertise the heap as
515device-local.
516
517[[memory-device-bitmask-list]]
518Each memory type returned by flink:vkGetPhysicalDeviceMemoryProperties must:
519have its pname:propertyFlags set to one of the following values:
520
521  * 0
522  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
523    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
524  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
525    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
526  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
527    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
528    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
529  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
530  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
531    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
532    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
533  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
534    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
535    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT
536  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
537    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
538    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
539    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT
540  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
541    ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
542ifdef::VK_VERSION_1_1[]
543  * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
544  * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT |
545    ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
546endif::VK_VERSION_1_1[]
547ifdef::VK_AMD_device_coherent_memory[]
548  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
549    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
550    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
551  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
552    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
553    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
554    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
555  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
556    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
557  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
558    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
559    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
560    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
561  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
562    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
563    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
564    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
565    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
566  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
567    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
568    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | +
569    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
570  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
571    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
572    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
573    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | +
574    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
575  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
576    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | +
577    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
578  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
579    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
580    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
581    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | +
582    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
583  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
584    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | +
585    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | +
586    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | +
587    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD | +
588    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD
589endif::VK_AMD_device_coherent_memory[]
590ifdef::VK_NV_external_memory_rdma[]
591  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | +
592    ename:VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV
593endif::VK_NV_external_memory_rdma[]
594
595There must: be at least one memory type with both the
596ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and
597ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bits set in its
598pname:propertyFlags.
599There must: be at least one memory type with the
600ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set in its
601pname:propertyFlags.
602ifdef::VK_AMD_device_coherent_memory[]
603If the <<features-deviceCoherentMemory, pname:deviceCoherentMemory>> feature
604is enabled, there must: be at least one memory type with the
605ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit set in its
606pname:propertyFlags.
607endif::VK_AMD_device_coherent_memory[]
608
609For each pair of elements *X* and *Y* returned in pname:memoryTypes, *X*
610must: be placed at a lower index position than *Y* if:
611
612  * the set of bit flags returned in the pname:propertyFlags member of *X*
613    is a strict subset of the set of bit flags returned in the
614    pname:propertyFlags member of *Y*; or
615  * the pname:propertyFlags members of *X* and *Y* are equal, and *X*
616    belongs to a memory heap with greater performance (as determined in an
617    implementation-specific manner)
618ifdef::VK_AMD_device_coherent_memory[]
619    ; or
620  * the pname:propertyFlags members of *Y* includes
621    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD or
622    ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD and *X* does not
623endif::VK_AMD_device_coherent_memory[]
624
625[NOTE]
626.Note
627====
628There is no ordering requirement between *X* and *Y* elements for the case
629their pname:propertyFlags members are not in a subset relation.
630That potentially allows more than one possible way to order the same set of
631memory types.
632Notice that the <<memory-device-bitmask-list,list of all allowed memory
633property flag combinations>> is written in a valid order.
634But if instead ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before
635ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
636ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the list would still be in a
637valid order.
638ifdef::VK_AMD_device_coherent_memory[]
639
640There may be a performance penalty for using device coherent or uncached
641device memory types, and using these accidentally is undesirable.
642In order to avoid this, memory types with these properties always appear at
643the end of the list; but are subject to the same rules otherwise.
644endif::VK_AMD_device_coherent_memory[]
645====
646
647This ordering requirement enables applications to use a simple search loop
648to select the desired memory type along the lines of:
649
650[source,c++]
651~~~~
652// Find a memory in `memoryTypeBitsRequirement` that includes all of `requiredProperties`
653int32_t findProperties(const VkPhysicalDeviceMemoryProperties* pMemoryProperties,
654                       uint32_t memoryTypeBitsRequirement,
655                       VkMemoryPropertyFlags requiredProperties) {
656    const uint32_t memoryCount = pMemoryProperties->memoryTypeCount;
657    for (uint32_t memoryIndex = 0; memoryIndex < memoryCount; ++memoryIndex) {
658        const uint32_t memoryTypeBits = (1 << memoryIndex);
659        const bool isRequiredMemoryType = memoryTypeBitsRequirement & memoryTypeBits;
660
661        const VkMemoryPropertyFlags properties =
662            pMemoryProperties->memoryTypes[memoryIndex].propertyFlags;
663        const bool hasRequiredProperties =
664            (properties & requiredProperties) == requiredProperties;
665
666        if (isRequiredMemoryType && hasRequiredProperties)
667            return static_cast<int32_t>(memoryIndex);
668    }
669
670    // failed to find memory type
671    return -1;
672}
673
674// Try to find an optimal memory type, or if it does not exist try fallback memory type
675// `device` is the VkDevice
676// `image` is the VkImage that requires memory to be bound
677// `memoryProperties` properties as returned by vkGetPhysicalDeviceMemoryProperties
678// `requiredProperties` are the property flags that must be present
679// `optimalProperties` are the property flags that are preferred by the application
680VkMemoryRequirements memoryRequirements;
681vkGetImageMemoryRequirements(device, image, &memoryRequirements);
682int32_t memoryType =
683    findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, optimalProperties);
684if (memoryType == -1) // not found; try fallback properties
685    memoryType =
686        findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, requiredProperties);
687~~~~
688
689include::{generated}/validity/structs/VkPhysicalDeviceMemoryProperties.txt[]
690--
691
692[open,refpage='VK_MAX_MEMORY_TYPES',desc='Length of an array of memory types',type='consts']
693--
694ename:VK_MAX_MEMORY_TYPES is the length of an array of slink:VkMemoryType
695structures describing memory types, as returned in
696slink:VkPhysicalDeviceMemoryProperties::memoryTypes.
697
698include::{generated}/api/enums/VK_MAX_MEMORY_TYPES.txt[]
699--
700
701[open,refpage='VK_MAX_MEMORY_HEAPS',desc='Length of an array of memory heaps',type='consts']
702--
703ename:VK_MAX_MEMORY_HEAPS is the length of an array of slink:VkMemoryHeap
704structures describing memory heaps, as returned in
705slink:VkPhysicalDeviceMemoryProperties::memoryHeaps.
706
707include::{generated}/api/enums/VK_MAX_MEMORY_HEAPS.txt[]
708--
709
710ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
711[open,refpage='vkGetPhysicalDeviceMemoryProperties2',desc='Reports memory information for the specified physical device',type='protos']
712--
713To query memory properties, call:
714
715ifdef::VK_VERSION_1_1[]
716include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties2.txt[]
717endif::VK_VERSION_1_1[]
718
719ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]
720
721ifdef::VK_KHR_get_physical_device_properties2[]
722include::{generated}/api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[]
723endif::VK_KHR_get_physical_device_properties2[]
724
725  * pname:physicalDevice is the handle to the device to query.
726  * pname:pMemoryProperties is a pointer to a
727    slink:VkPhysicalDeviceMemoryProperties2 structure in which the
728    properties are returned.
729
730fname:vkGetPhysicalDeviceMemoryProperties2 behaves similarly to
731flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return
732extended information in a pname:pNext chain of output structures.
733
734include::{generated}/validity/protos/vkGetPhysicalDeviceMemoryProperties2.txt[]
735--
736
737[open,refpage='VkPhysicalDeviceMemoryProperties2',desc='Structure specifying physical device memory properties',type='structs']
738--
739The sname:VkPhysicalDeviceMemoryProperties2 structure is defined as:
740
741include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2.txt[]
742
743ifdef::VK_KHR_get_physical_device_properties2[]
744or the equivalent
745
746include::{generated}/api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[]
747endif::VK_KHR_get_physical_device_properties2[]
748
749  * pname:sType is the type of this structure.
750  * pname:pNext is `NULL` or a pointer to a structure extending this
751    structure.
752  * pname:memoryProperties is a slink:VkPhysicalDeviceMemoryProperties
753    structure which is populated with the same values as in
754    flink:vkGetPhysicalDeviceMemoryProperties.
755
756include::{generated}/validity/structs/VkPhysicalDeviceMemoryProperties2.txt[]
757--
758endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
759
760[open,refpage='VkMemoryHeap',desc='Structure specifying a memory heap',type='structs']
761--
762The sname:VkMemoryHeap structure is defined as:
763
764include::{generated}/api/structs/VkMemoryHeap.txt[]
765
766  * pname:size is the total memory size in bytes in the heap.
767  * pname:flags is a bitmask of elink:VkMemoryHeapFlagBits specifying
768    attribute flags for the heap.
769
770include::{generated}/validity/structs/VkMemoryHeap.txt[]
771--
772
773[open,refpage='VkMemoryHeapFlagBits',desc='Bitmask specifying attribute flags for a heap',type='enums']
774--
775Bits which may: be set in slink:VkMemoryHeap::pname:flags, indicating
776attribute flags for the heap, are:
777
778include::{generated}/api/enums/VkMemoryHeapFlagBits.txt[]
779
780  * ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT specifies that the heap
781    corresponds to device-local memory.
782    Device-local memory may: have different performance characteristics than
783    host-local memory, and may: support different memory property flags.
784ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]
785  * ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT specifies that in a logical
786    device representing more than one physical device, there is a
787    per-physical device instance of the heap memory.
788    By default, an allocation from such a heap will be replicated to each
789    physical device's instance of the heap.
790endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]
791--
792
793[open,refpage='VkMemoryHeapFlags',desc='Bitmask of VkMemoryHeapFlagBits',type='flags']
794--
795include::{generated}/api/flags/VkMemoryHeapFlags.txt[]
796
797tname:VkMemoryHeapFlags is a bitmask type for setting a mask of zero or more
798elink:VkMemoryHeapFlagBits.
799--
800
801[open,refpage='VkMemoryType',desc='Structure specifying memory type',type='structs']
802--
803The sname:VkMemoryType structure is defined as:
804
805include::{generated}/api/structs/VkMemoryType.txt[]
806
807  * pname:heapIndex describes which memory heap this memory type corresponds
808    to, and must: be less than pname:memoryHeapCount from the
809    slink:VkPhysicalDeviceMemoryProperties structure.
810  * pname:propertyFlags is a bitmask of elink:VkMemoryPropertyFlagBits of
811    properties for this memory type.
812
813include::{generated}/validity/structs/VkMemoryType.txt[]
814--
815
816[open,refpage='VkMemoryPropertyFlagBits',desc='Bitmask specifying properties for a memory type',type='enums']
817--
818Bits which may: be set in slink:VkMemoryType::pname:propertyFlags,
819indicating properties of a memory heap, are:
820
821include::{generated}/api/enums/VkMemoryPropertyFlagBits.txt[]
822
823  * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit specifies that memory
824    allocated with this type is the most efficient for device access.
825    This property will be set if and only if the memory type belongs to a
826    heap with the ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set.
827  * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit specifies that memory
828    allocated with this type can: be mapped for host access using
829    flink:vkMapMemory.
830  * ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit specifies that the host
831    cache management commands flink:vkFlushMappedMemoryRanges and
832    flink:vkInvalidateMappedMemoryRanges are not needed to flush host writes
833    to the device or make device writes visible to the host, respectively.
834  * ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit specifies that memory
835    allocated with this type is cached on the host.
836    Host memory accesses to uncached memory are slower than to cached
837    memory, however uncached memory is always host coherent.
838  * ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit specifies that the
839    memory type only allows device access to the memory.
840    Memory types must: not have both
841    ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and
842    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set.
843    Additionally, the object's backing memory may: be provided by the
844    implementation lazily as specified in <<memory-device-lazy_allocation,
845    Lazily Allocated Memory>>.
846ifdef::VK_VERSION_1_1[]
847  * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT bit specifies that the memory
848    type only allows device access to the memory, and allows protected queue
849    operations to access the memory.
850    Memory types must: not have ename:VK_MEMORY_PROPERTY_PROTECTED_BIT set
851    and any of ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set, or
852    ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, or
853    ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT set.
854endif::VK_VERSION_1_1[]
855ifdef::VK_AMD_device_coherent_memory[]
856  * ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD bit specifies that
857    device accesses to allocations of this memory type are automatically
858    made available and visible.
859  * ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD bit specifies that
860    memory allocated with this type is not cached on the device.
861    Uncached device memory is always device coherent.
862endif::VK_AMD_device_coherent_memory[]
863ifdef::VK_NV_external_memory_rdma[]
864  * ename:VK_MEMORY_PROPERTY_RDMA_CAPABLE_BIT_NV bit specifies that external
865    devices can access this memory directly.
866endif::VK_NV_external_memory_rdma[]
867
868ifdef::VK_AMD_device_coherent_memory[]
869For any memory allocated with both the
870ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT and the
871ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD, host or device accesses
872also perform automatic memory domain transfer operations, such that writes
873are always automatically available and visible to both host and device
874memory domains.
875
876[NOTE]
877.Note
878====
879Device coherence is a useful property for certain debugging use cases (e.g.
880crash analysis, where performing separate coherence actions could mean
881values are not reported correctly).
882However, device coherent accesses may be slower than equivalent accesses
883without device coherence, particularly if they are also device uncached.
884For device uncached memory in particular, repeated accesses to the same or
885neighbouring memory locations over a short time period (e.g. within a frame)
886may be slower than it would be for the equivalent cached memory type.
887As such, it is generally inadvisable to use device coherent or device
888uncached memory except when really needed.
889====
890endif::VK_AMD_device_coherent_memory[]
891--
892
893[open,refpage='VkMemoryPropertyFlags',desc='Bitmask of VkMemoryPropertyFlagBits',type='flags']
894--
895include::{generated}/api/flags/VkMemoryPropertyFlags.txt[]
896
897tname:VkMemoryPropertyFlags is a bitmask type for setting a mask of zero or
898more elink:VkMemoryPropertyFlagBits.
899--
900
901ifdef::VK_EXT_memory_budget[]
902[open,refpage='VkPhysicalDeviceMemoryBudgetPropertiesEXT',desc='Structure specifying physical device memory budget and usage',type='structs']
903--
904If the sname:VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is included
905in the pname:pNext chain of slink:VkPhysicalDeviceMemoryProperties2, it is
906filled with the current memory budgets and usages.
907
908The sname:VkPhysicalDeviceMemoryBudgetPropertiesEXT structure is defined as:
909
910include::{generated}/api/structs/VkPhysicalDeviceMemoryBudgetPropertiesEXT.txt[]
911
912  * pname:sType is the type of this structure.
913  * pname:pNext is `NULL` or a pointer to a structure extending this
914    structure.
915  * pname:heapBudget is an array of ename:VK_MAX_MEMORY_HEAPS
916    basetype:VkDeviceSize values in which memory budgets are returned, with
917    one element for each memory heap.
918    A heap's budget is a rough estimate of how much memory the process can:
919    allocate from that heap before allocations may: fail or cause
920    performance degradation.
921    The budget includes any currently allocated device memory.
922  * pname:heapUsage is an array of ename:VK_MAX_MEMORY_HEAPS
923    basetype:VkDeviceSize values in which memory usages are returned, with
924    one element for each memory heap.
925    A heap's usage is an estimate of how much memory the process is
926    currently using in that heap.
927
928The values returned in this structure are not invariant.
929The pname:heapBudget and pname:heapUsage values must: be zero for array
930elements greater than or equal to
931slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeapCount.
932The pname:heapBudget value must: be non-zero for array elements less than
933slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeapCount.
934The pname:heapBudget value must: be less than or equal to
935slink:VkMemoryHeap::pname:size for each heap.
936
937include::{generated}/validity/structs/VkPhysicalDeviceMemoryBudgetPropertiesEXT.txt[]
938--
939endif::VK_EXT_memory_budget[]
940
941[[memory-device-objects]]
942=== Device Memory Objects
943
944[open,refpage='VkDeviceMemory',desc='Opaque handle to a device memory object',type='handles']
945--
946A Vulkan device operates on data in device memory via memory objects that
947are represented in the API by a sname:VkDeviceMemory handle:
948
949include::{generated}/api/handles/VkDeviceMemory.txt[]
950--
951
952=== Device Memory Allocation
953
954[open,refpage='vkAllocateMemory',desc='Allocate device memory',type='protos']
955--
956To allocate memory objects, call:
957
958include::{generated}/api/protos/vkAllocateMemory.txt[]
959
960  * pname:device is the logical device that owns the memory.
961  * pname:pAllocateInfo is a pointer to a slink:VkMemoryAllocateInfo
962    structure describing parameters of the allocation.
963    A successfully returned allocation must: use the requested parameters --
964    no substitution is permitted by the implementation.
965  * pname:pAllocator controls host memory allocation as described in the
966    <<memory-allocation, Memory Allocation>> chapter.
967  * pname:pMemory is a pointer to a slink:VkDeviceMemory handle in which
968    information about the allocated memory is returned.
969
970Allocations returned by fname:vkAllocateMemory are guaranteed to meet any
971alignment requirement of the implementation.
972For example, if an implementation requires 128 byte alignment for images and
97364 byte alignment for buffers, the device memory returned through this
974mechanism would be 128-byte aligned.
975This ensures that applications can: correctly suballocate objects of
976different types (with potentially different alignment requirements) in the
977same memory object.
978
979ifndef::VK_VERSION_1_1[]
980When memory is allocated, its contents are undefined:.
981endif::VK_VERSION_1_1[]
982ifdef::VK_VERSION_1_1[]
983When memory is allocated, its contents are undefined: with the following
984constraint:
985
986  * The contents of unprotected memory must: not be a function of the
987    contents of data protected memory objects, even if those memory objects
988    were previously freed.
989
990[NOTE]
991.Note
992====
993The contents of memory allocated by one application should: not be a
994function of data from protected memory objects of another application, even
995if those memory objects were previously freed.
996====
997endif::VK_VERSION_1_1[]
998
999The maximum number of valid memory allocations that can: exist
1000simultaneously within a slink:VkDevice may: be restricted by implementation-
1001or platform-dependent limits.
1002The <<limits-maxMemoryAllocationCount,pname:maxMemoryAllocationCount>>
1003feature describes the number of allocations that can: exist simultaneously
1004before encountering these internal limits.
1005
1006[NOTE]
1007.Note
1008====
1009For historical reasons, if pname:maxMemoryAllocationCount is exceeded, some
1010implementations may return ename:VK_ERROR_TOO_MANY_OBJECTS.
1011Exceeding this limit will result in undefined: behavior, and an application
1012should not rely on the use of the returned error code in order to identify
1013when the limit is reached.
1014====
1015
1016[NOTE]
1017.Note
1018====
1019Many protected memory implementations involve complex hardware and system
1020software support, and often have additional and much lower limits on the
1021number of simultaneous protected memory allocations (from memory types with
1022the ename:VK_MEMORY_PROPERTY_PROTECTED_BIT property) than for non-protected
1023memory allocations.
1024These limits can be system-wide, and depend on a variety of factors outside
1025of the Vulkan implementation, so they cannot be queried in Vulkan.
1026Applications should: use as few allocations as possible from such memory
1027types by suballocating aggressively, and be prepared for allocation failure
1028even when there is apparently plenty of capacity remaining in the memory
1029heap.
1030As a guideline, the Vulkan conformance test suite requires that at least 80
1031minimum-size allocations can exist concurrently when no other uses of
1032protected memory are active in the system.
1033====
1034
1035Some platforms may: have a limit on the maximum size of a single allocation.
1036For example, certain systems may: fail to create allocations with a size
1037greater than or equal to 4GB.
1038Such a limit is implementation-dependent, and if such a failure occurs then
1039the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY must: be returned.
1040ifdef::VK_KHR_maintenance3[]
1041This limit is advertised in
1042slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationSize.
1043endif::VK_KHR_maintenance3[]
1044
1045ifdef::VK_AMD_memory_overallocation_behavior[]
1046
1047The cumulative memory size allocated to a heap can: be limited by the size
1048of the specified heap.
1049In such cases, allocated memory is tracked on a per-device and per-heap
1050basis.
1051Some platforms allow overallocation into other heaps.
1052The overallocation behavior can: be specified through the
1053`apiext:VK_AMD_memory_overallocation_behavior` extension.
1054
1055endif::VK_AMD_memory_overallocation_behavior[]
1056
1057ifdef::VK_EXT_pageable_device_local_memory[]
1058
1059If the
1060slink:VkPhysicalDevicePageableDeviceLocalMemoryFeaturesEXT::pname:pageableDeviceLocalMemory
1061feature is enabled, memory allocations made from a heap that includes
1062ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in slink:VkMemoryHeap::pname:flags
1063may: be transparently moved to host-local memory allowing multiple
1064applications to share device-local memory.
1065If there is no space left in device-local memory when this new allocation is
1066made, other allocations may: be moved out transparently to make room.
1067The operating system will determine which allocations to move to
1068device-local memory or host-local memory based on platform-specific
1069criteria.
1070To help the operating system make good choices, the application should: set
1071the appropriate memory priority with slink:VkMemoryPriorityAllocateInfoEXT
1072and adjust it as necessary with flink:vkSetDeviceMemoryPriorityEXT.
1073Higher priority allocations will moved to device-local memory first.
1074
1075Memory allocations made on heaps without the
1076ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT property will not be transparently
1077promoted to device-local memory by the operating system.
1078
1079endif::VK_EXT_pageable_device_local_memory[]
1080
1081.Valid Usage
1082****
1083  * [[VUID-vkAllocateMemory-pAllocateInfo-01713]]
1084    pname:pAllocateInfo->allocationSize must: be less than or equal to
1085    slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps[`memindex`].pname:size
1086    where `memindex` =
1087    slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypes[pname:pAllocateInfo->memoryTypeIndex].pname:heapIndex
1088    as returned by flink:vkGetPhysicalDeviceMemoryProperties for the
1089    slink:VkPhysicalDevice that pname:device was created from
1090  * [[VUID-vkAllocateMemory-pAllocateInfo-01714]]
1091    pname:pAllocateInfo->memoryTypeIndex must: be less than
1092    slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypeCount as
1093    returned by flink:vkGetPhysicalDeviceMemoryProperties for the
1094    slink:VkPhysicalDevice that pname:device was created from
1095ifdef::VK_AMD_device_coherent_memory[]
1096  * [[VUID-vkAllocateMemory-deviceCoherentMemory-02790]]
1097    If the <<features-deviceCoherentMemory,pname:deviceCoherentMemory>>
1098    feature is not enabled, pname:pAllocateInfo->memoryTypeIndex must: not
1099    identify a memory type supporting
1100    ename:VK_MEMORY_PROPERTY_DEVICE_COHERENT_BIT_AMD
1101endif::VK_AMD_device_coherent_memory[]
1102  * [[VUID-vkAllocateMemory-maxMemoryAllocationCount-04101]]
1103    There must: be less than
1104    sname:VkPhysicalDeviceLimits::pname:maxMemoryAllocationCount device
1105    memory allocations currently allocated on the device
1106****
1107
1108include::{generated}/validity/protos/vkAllocateMemory.txt[]
1109--
1110
1111[open,refpage='VkMemoryAllocateInfo',desc='Structure containing parameters of a memory allocation',type='structs']
1112--
1113The sname:VkMemoryAllocateInfo structure is defined as:
1114
1115include::{generated}/api/structs/VkMemoryAllocateInfo.txt[]
1116
1117  * pname:sType is the type of this structure.
1118  * pname:pNext is `NULL` or a pointer to a structure extending this
1119    structure.
1120  * pname:allocationSize is the size of the allocation in bytes.
1121  * pname:memoryTypeIndex is an index identifying a memory type from the
1122    pname:memoryTypes array of the slink:VkPhysicalDeviceMemoryProperties
1123    structure.
1124
1125The internal data of an allocated device memory object must: include a
1126reference to implementation-specific resources, referred to as the memory
1127object's _payload_.
1128ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[]
1129Applications can: also import and export that internal data to and from
1130device memory objects to share data between Vulkan instances and other
1131compatible APIs.
1132A sname:VkMemoryAllocateInfo structure defines a memory import operation if
1133its pname:pNext chain includes one of the following structures:
1134
1135ifdef::VK_KHR_external_memory_win32[]
1136  * slink:VkImportMemoryWin32HandleInfoKHR with a non-zero pname:handleType
1137    value
1138endif::VK_KHR_external_memory_win32[]
1139ifdef::VK_KHR_external_memory_fd[]
1140  * slink:VkImportMemoryFdInfoKHR with a non-zero pname:handleType value
1141endif::VK_KHR_external_memory_fd[]
1142ifdef::VK_EXT_external_memory_host[]
1143  * slink:VkImportMemoryHostPointerInfoEXT with a non-zero pname:handleType
1144    value
1145endif::VK_EXT_external_memory_host[]
1146ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
1147  * slink:VkImportAndroidHardwareBufferInfoANDROID with a non-`NULL`
1148    pname:buffer value
1149endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1150ifdef::VK_FUCHSIA_external_memory[]
1151  * slink:VkImportMemoryZirconHandleInfoFUCHSIA with a non-zero
1152    pname:handleType value
1153endif::VK_FUCHSIA_external_memory[]
1154ifdef::VK_FUCHSIA_buffer_collection[]
1155  * slink:VkImportMemoryBufferCollectionFUCHSIA
1156endif::VK_FUCHSIA_buffer_collection[]
1157
1158ifdef::VK_KHR_external_memory_win32[]
1159If the parameters define an import operation and the external handle type is
1160ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
1161ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or
1162ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT,
1163pname:allocationSize is ignored.
1164The implementation must: query the size of these allocations from the OS.
1165endif::VK_KHR_external_memory_win32[]
1166
1167Whether device memory objects constructed via a memory import operation hold
1168a reference to their payload depends on the properties of the handle type
1169used to perform the import, as defined below for each valid handle type.
1170Importing memory must: not modify the content of the memory.
1171Implementations must: ensure that importing memory does not enable the
1172importing Vulkan instance to access any memory or resources in other Vulkan
1173instances other than that corresponding to the memory object imported.
1174Implementations must: also ensure accessing imported memory which has not
1175been initialized does not allow the importing Vulkan instance to obtain data
1176from the exporting Vulkan instance or vice-versa.
1177
1178[NOTE]
1179.Note
1180====
1181How exported and imported memory is isolated is left to the implementation,
1182but applications should be aware that such isolation may: prevent
1183implementations from placing multiple exportable memory objects in the same
1184physical or virtual page.
1185Hence, applications should: avoid creating many small external memory
1186objects whenever possible.
1187====
1188
1189Importing memory must: not increase overall heap usage within a system.
1190ifdef::VK_VERSION_1_1,VK_KHR_maintenance3,VK_EXT_memory_budget[]
1191However, it must: affect the following per-process values:
1192
1193ifdef::VK_VERSION_1_1,VK_KHR_maintenance3[]
1194  * slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationCount
1195endif::VK_VERSION_1_1,VK_KHR_maintenance3[]
1196ifdef::VK_EXT_memory_budget[]
1197  * slink:VkPhysicalDeviceMemoryBudgetPropertiesEXT::pname:heapUsage
1198endif::VK_EXT_memory_budget[]
1199endif::VK_VERSION_1_1,VK_KHR_maintenance3,VK_EXT_memory_budget[]
1200
1201When performing a memory import operation, it is the responsibility of the
1202application to ensure the external handles and their associated payloads
1203meet all valid usage requirements.
1204However, implementations must: perform sufficient validation of external
1205handles and payloads to ensure that the operation results in a valid memory
1206object which will not cause program termination, device loss, queue stalls,
1207or corruption of other resources when used as allowed according to its
1208allocation parameters.
1209If the external handle provided does not meet these requirements, the
1210implementation must: fail the memory import operation with the error code
1211ename:VK_ERROR_INVALID_EXTERNAL_HANDLE.
1212
1213endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[]
1214
1215.Valid Usage
1216****
1217ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
1218  * [[VUID-VkMemoryAllocateInfo-allocationSize-00638]]
1219    pname:allocationSize must: be greater than `0`
1220endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1221ifdef::VK_FUCHSIA_buffer_collection[]
1222  * [[VUID-VkMemoryAllocateInfo-buffer-06380]]
1223    If the parameters define an import operation from an
1224    slink:VkBufferCollectionFUCHSIA, and
1225    slink:VkMemoryDedicatedAllocateInfo::pname:buffer is present and
1226    non-NULL, slink:VkImportMemoryBufferCollectionFUCHSIA::pname:collection
1227    and slink:VkImportMemoryBufferCollectionFUCHSIA::pname:index must match
1228    slink:VkBufferCollectionBufferCreateInfoFUCHSIA::pname:collection and
1229    slink:VkBufferCollectionBufferCreateInfoFUCHSIA::pname:index,
1230    respectively, of the slink:VkBufferCollectionBufferCreateInfoFUCHSIA
1231    structure used to create the
1232    slink:VkMemoryDedicatedAllocateInfo::pname:buffer
1233  * [[VUID-VkMemoryAllocateInfo-image-06381]]
1234    If the parameters define an import operation from an
1235    slink:VkBufferCollectionFUCHSIA, and
1236    slink:VkMemoryDedicatedAllocateInfo::pname:image is present and
1237    non-NULL, slink:VkImportMemoryBufferCollectionFUCHSIA::pname:collection
1238    and slink:VkImportMemoryBufferCollectionFUCHSIA::pname:index must match
1239    slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection and
1240    slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:index,
1241    respectively, of the slink:VkBufferCollectionImageCreateInfoFUCHSIA
1242    structure used to create the
1243    slink:VkMemoryDedicatedAllocateInfo::pname:image
1244  * [[VUID-VkMemoryAllocateInfo-allocationSize-06382]]
1245    If the parameters define an import operation from an
1246    slink:VkBufferCollectionFUCHSIA, pname:allocationSize must: match
1247    slink:VkMemoryRequirements::pname:size value retrieved by
1248    flink:vkGetImageMemoryRequirements or
1249    flink:vkGetBufferMemoryRequirements for image-based or buffer-based
1250    collections respectively
1251  * [[VUID-VkMemoryAllocateInfo-pNext-06383]]
1252    If the parameters define an import operation from an
1253    slink:VkBufferCollectionFUCHSIA, the pname:pNext chain must: include a
1254    slink:VkMemoryDedicatedAllocateInfo structure with either its
1255    pname:image or pname:buffer field set to a value other than
1256    dlink:VK_NULL_HANDLE.
1257  * [[VUID-VkMemoryAllocateInfo-image-06384]]
1258    If the parameters define an import operation from an
1259    slink:VkBufferCollectionFUCHSIA and
1260    slink:VkMemoryDedicatedAllocateInfo::pname:image is not
1261    dlink:VK_NULL_HANDLE, the pname:image must: be created with a
1262    slink:VkBufferCollectionImageCreateInfoFUCHSIA structure chained to its
1263    slink:VkImageCreateInfo::pname:pNext pointer
1264  * [[VUID-VkMemoryAllocateInfo-buffer-06385]]
1265    If the parameters define an import operation from an
1266    slink:VkBufferCollectionFUCHSIA and
1267    slink:VkMemoryDedicatedAllocateInfo::pname:buffer is not
1268    dlink:VK_NULL_HANDLE, the pname:buffer must: be created with a
1269    slink:VkBufferCollectionBufferCreateInfoFUCHSIA structure chained to its
1270    slink:VkBufferCreateInfo::pname:pNext pointer
1271  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-06386]]
1272    If the parameters define an import operation from an
1273    slink:VkBufferCollectionFUCHSIA, pname:memoryTypeIndex must: be from
1274    slink:VkBufferCollectionPropertiesFUCHSIA as retrieved by
1275    flink:vkGetBufferCollectionPropertiesFUCHSIA.
1276endif::VK_FUCHSIA_buffer_collection[]
1277ifdef::VK_KHR_external_memory[]
1278ifdef::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[]
1279  * [[VUID-VkMemoryAllocateInfo-pNext-00639]]
1280    If the pname:pNext chain includes a sname:VkExportMemoryAllocateInfo
1281    structure, and any of the handle types specified in
1282    sname:VkExportMemoryAllocateInfo::pname:handleTypes require a dedicated
1283    allocation, as reported by
1284    flink:vkGetPhysicalDeviceImageFormatProperties2 in
1285    sname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures
1286    or
1287    sname:VkExternalBufferProperties::pname:externalMemoryProperties.externalMemoryFeatures,
1288    the pname:pNext chain must: include a
1289    sname:VkMemoryDedicatedAllocateInfo or
1290    sname:VkDedicatedAllocationMemoryAllocateInfoNV structure with either
1291    its pname:image or pname:buffer member set to a value other than
1292    dlink:VK_NULL_HANDLE
1293endif::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[]
1294endif::VK_KHR_external_memory[]
1295ifdef::VK_KHR_external_memory[]
1296ifdef::VK_NV_external_memory[]
1297  * [[VUID-VkMemoryAllocateInfo-pNext-00640]]
1298    If the pname:pNext chain includes a slink:VkExportMemoryAllocateInfo
1299    structure, it must: not include a slink:VkExportMemoryAllocateInfoNV or
1300    slink:VkExportMemoryWin32HandleInfoNV structure
1301endif::VK_NV_external_memory[]
1302endif::VK_KHR_external_memory[]
1303ifdef::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[]
1304  * [[VUID-VkMemoryAllocateInfo-pNext-00641]]
1305    If the pname:pNext chain includes a
1306    slink:VkImportMemoryWin32HandleInfoKHR structure, it must: not include a
1307    slink:VkImportMemoryWin32HandleInfoNV structure
1308endif::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[]
1309ifdef::VK_KHR_external_memory_fd[]
1310  * [[VUID-VkMemoryAllocateInfo-allocationSize-01742]]
1311    If the parameters define an import operation, the external handle
1312    specified was created by the Vulkan API, and the external handle type is
1313    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, then the values of
1314    pname:allocationSize and pname:memoryTypeIndex must: match those
1315    specified when the payload being imported was created
1316endif::VK_KHR_external_memory_fd[]
1317ifdef::VK_KHR_external_memory+VK_KHR_device_group[]
1318  * [[VUID-VkMemoryAllocateInfo-None-00643]]
1319    If the parameters define an import operation and the external handle
1320    specified was created by the Vulkan API, the device mask specified by
1321    slink:VkMemoryAllocateFlagsInfo must: match the mask specified when the
1322    payload being imported was allocated
1323  * [[VUID-VkMemoryAllocateInfo-None-00644]]
1324    If the parameters define an import operation and the external handle
1325    specified was created by the Vulkan API, the list of physical devices
1326    that comprise the logical device passed to flink:vkAllocateMemory must:
1327    match the list of physical devices that comprise the logical device on
1328    which the payload was originally allocated
1329endif::VK_KHR_external_memory+VK_KHR_device_group[]
1330ifdef::VK_KHR_external_memory_win32[]
1331  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-00645]]
1332    If the parameters define an import operation and the external handle is
1333    an NT handle or a global share handle created outside of the Vulkan API,
1334    the value of pname:memoryTypeIndex must: be one of those returned by
1335    flink:vkGetMemoryWin32HandlePropertiesKHR
1336  * [[VUID-VkMemoryAllocateInfo-allocationSize-01743]]
1337    If the parameters define an import operation, the external handle was
1338    created by the Vulkan API, and the external handle type is
1339    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT or
1340    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, then the
1341    values of pname:allocationSize and pname:memoryTypeIndex must: match
1342    those specified when the payload being imported was created
1343  * [[VUID-VkMemoryAllocateInfo-allocationSize-00647]]
1344    If the parameters define an import operation and the external handle
1345    type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT,
1346    pname:allocationSize must: match the size specified when creating the
1347    Direct3D 12 heap from which the payload was extracted
1348endif::VK_KHR_external_memory_win32[]
1349ifdef::VK_KHR_external_memory_fd[]
1350  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-00648]]
1351    If the parameters define an import operation and the external handle is
1352    a POSIX file descriptor created outside of the Vulkan API, the value of
1353    pname:memoryTypeIndex must: be one of those returned by
1354    flink:vkGetMemoryFdPropertiesKHR
1355endif::VK_KHR_external_memory_fd[]
1356ifdef::VK_VERSION_1_1[]
1357  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01872]]
1358    If the protected memory feature is not enabled, the
1359    sname:VkMemoryAllocateInfo::pname:memoryTypeIndex must: not indicate a
1360    memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
1361endif::VK_VERSION_1_1[]
1362ifdef::VK_EXT_external_memory_host[]
1363  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744]]
1364    If the parameters define an import operation and the external handle is
1365    a host pointer, the value of pname:memoryTypeIndex must: be one of those
1366    returned by flink:vkGetMemoryHostPointerPropertiesEXT
1367  * [[VUID-VkMemoryAllocateInfo-allocationSize-01745]]
1368    If the parameters define an import operation and the external handle is
1369    a host pointer, pname:allocationSize must: be an integer multiple of
1370    sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment
1371ifdef::VK_NV_dedicated_allocation[]
1372  * [[VUID-VkMemoryAllocateInfo-pNext-02805]]
1373    If the parameters define an import operation and the external handle is
1374    a host pointer, the pname:pNext chain must: not include a
1375    slink:VkDedicatedAllocationMemoryAllocateInfoNV structure with either
1376    its pname:image or pname:buffer field set to a value other than
1377    dlink:VK_NULL_HANDLE
1378endif::VK_NV_dedicated_allocation[]
1379ifdef::VK_KHR_dedicated_allocation[]
1380  * [[VUID-VkMemoryAllocateInfo-pNext-02806]]
1381    If the parameters define an import operation and the external handle is
1382    a host pointer, the pname:pNext chain must: not include a
1383    slink:VkMemoryDedicatedAllocateInfo structure with either its
1384    pname:image or pname:buffer field set to a value other than
1385    dlink:VK_NULL_HANDLE
1386endif::VK_KHR_dedicated_allocation[]
1387endif::VK_EXT_external_memory_host[]
1388ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
1389  * [[VUID-VkMemoryAllocateInfo-allocationSize-02383]]
1390    If the parameters define an import operation and the external handle
1391    type is
1392    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID,
1393    pname:allocationSize must: be the size returned by
1394    flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android
1395    hardware buffer
1396  * [[VUID-VkMemoryAllocateInfo-pNext-02384]]
1397    If the parameters define an import operation and the external handle
1398    type is
1399    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID,
1400    and the pname:pNext chain does not include a
1401    slink:VkMemoryDedicatedAllocateInfo structure or
1402    slink:VkMemoryDedicatedAllocateInfo::pname:image is
1403    dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a
1404    code:AHardwareBuffer_Desc::code:format of
1405    code:AHARDWAREBUFFER_FORMAT_BLOB and a
1406    code:AHardwareBuffer_Desc::code:usage that includes
1407    code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER
1408  * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-02385]]
1409    If the parameters define an import operation and the external handle
1410    type is
1411    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID,
1412    pname:memoryTypeIndex must: be one of those returned by
1413    flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android
1414    hardware buffer
1415  * [[VUID-VkMemoryAllocateInfo-pNext-01874]]
1416    If the parameters do not define an import operation, and the pname:pNext
1417    chain includes a sname:VkExportMemoryAllocateInfo structure with
1418    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
1419    included in its pname:handleTypes member, and the pname:pNext chain
1420    includes a slink:VkMemoryDedicatedAllocateInfo structure with
1421    pname:image not equal to dlink:VK_NULL_HANDLE, then pname:allocationSize
1422    must: be `0`, otherwise pname:allocationSize must: be greater than `0`
1423  * [[VUID-VkMemoryAllocateInfo-pNext-02386]]
1424    If the parameters define an import operation, the external handle is an
1425    Android hardware buffer, and the pname:pNext chain includes a
1426    slink:VkMemoryDedicatedAllocateInfo with pname:image that is not
1427    dlink:VK_NULL_HANDLE, the Android hardware buffer's
1428    basetype:AHardwareBuffer::code:usage must: include at least one of
1429    code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER or
1430    code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE
1431  * [[VUID-VkMemoryAllocateInfo-pNext-02387]]
1432    If the parameters define an import operation, the external handle is an
1433    Android hardware buffer, and the pname:pNext chain includes a
1434    slink:VkMemoryDedicatedAllocateInfo with pname:image that is not
1435    dlink:VK_NULL_HANDLE, the format of pname:image must: be
1436    ename:VK_FORMAT_UNDEFINED or the format returned by
1437    flink:vkGetAndroidHardwareBufferPropertiesANDROID in
1438    slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format for
1439    the Android hardware buffer
1440  * [[VUID-VkMemoryAllocateInfo-pNext-02388]]
1441    If the parameters define an import operation, the external handle is an
1442    Android hardware buffer, and the pname:pNext chain includes a
1443    slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is
1444    not dlink:VK_NULL_HANDLE, the width, height, and array layer dimensions
1445    of pname:image and the Android hardware buffer's
1446    code:AHardwareBuffer_Desc must: be identical
1447  * [[VUID-VkMemoryAllocateInfo-pNext-02389]]
1448    If the parameters define an import operation, the external handle is an
1449    Android hardware buffer, and the pname:pNext chain includes a
1450    slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is
1451    not dlink:VK_NULL_HANDLE, and the Android hardware buffer's
1452    basetype:AHardwareBuffer::code:usage includes
1453    code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must:
1454    have a complete mipmap chain
1455  * [[VUID-VkMemoryAllocateInfo-pNext-02586]]
1456    If the parameters define an import operation, the external handle is an
1457    Android hardware buffer, and the pname:pNext chain includes a
1458    slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is
1459    not dlink:VK_NULL_HANDLE, and the Android hardware buffer's
1460    basetype:AHardwareBuffer::code:usage does not include
1461    code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must:
1462    have exactly one mipmap level
1463  * [[VUID-VkMemoryAllocateInfo-pNext-02390]]
1464    If the parameters define an import operation, the external handle is an
1465    Android hardware buffer, and the pname:pNext chain includes a
1466    slink:VkMemoryDedicatedAllocateInfo structure with pname:image that is
1467    not dlink:VK_NULL_HANDLE, each bit set in the usage of pname:image must:
1468    be listed in
1469    <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage
1470    Equivalence>>, and if there is a corresponding
1471    code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in the
1472    Android hardware buffer's code:AHardwareBuffer_Desc::code:usage
1473endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1474ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
1475  * [[VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03329]]
1476    If
1477    slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress
1478    is not zero, sname:VkMemoryAllocateFlagsInfo::pname:flags must: include
1479    ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
1480  * [[VUID-VkMemoryAllocateInfo-flags-03330]]
1481    If sname:VkMemoryAllocateFlagsInfo::pname:flags includes
1482    ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the
1483    <<features-bufferDeviceAddressCaptureReplay,bufferDeviceAddressCaptureReplay>>
1484    feature must: be enabled
1485  * [[VUID-VkMemoryAllocateInfo-flags-03331]]
1486    If sname:VkMemoryAllocateFlagsInfo::pname:flags includes
1487    ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT, the
1488    <<features-bufferDeviceAddress,bufferDeviceAddress>> feature must: be
1489    enabled
1490ifdef::VK_EXT_external_memory_host[]
1491  * [[VUID-VkMemoryAllocateInfo-pNext-03332]]
1492    If the pname:pNext chain includes a
1493    sname:VkImportMemoryHostPointerInfoEXT structure,
1494    slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress
1495    must: be zero
1496endif::VK_EXT_external_memory_host[]
1497  * [[VUID-VkMemoryAllocateInfo-opaqueCaptureAddress-03333]]
1498    If the parameters define an import operation,
1499    slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress
1500    must: be zero
1501endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
1502ifdef::VK_FUCHSIA_external_memory[]
1503  * [[VUID-VkMemoryAllocateInfo-None-04749]]
1504    If the parameters define an import operation and the external handle
1505    type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the
1506    value of sname:memoryTypeIndex must: be an index identifying a memory
1507    type from the sname:memoryTypeBits field of the
1508    slink:VkMemoryZirconHandlePropertiesFUCHSIA structure populated by a
1509    call to flink:vkGetMemoryZirconHandlePropertiesFUCHSIA
1510  * [[VUID-VkMemoryAllocateInfo-allocationSize-04750]]
1511    If the parameters define an import operation and the external handle
1512    type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the
1513    value of pname:allocationSize must: be greater than `0` and must: be
1514    less than or equal to the size of the VMO as determined by
1515    code:zx_vmo_get_size(pname:handle) where pname:handle is the VMO handle
1516    to the imported external memory
1517endif::VK_FUCHSIA_external_memory[]
1518****
1519
1520include::{generated}/validity/structs/VkMemoryAllocateInfo.txt[]
1521--
1522
1523ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
1524[open,refpage='VkMemoryDedicatedAllocateInfo',desc='Specify a dedicated memory allocation resource',type='structs']
1525--
1526If the pname:pNext chain includes a sname:VkMemoryDedicatedAllocateInfo
1527structure, then that structure includes a handle of the sole buffer or image
1528resource that the memory can: be bound to.
1529
1530The sname:VkMemoryDedicatedAllocateInfo structure is defined as:
1531
1532include::{generated}/api/structs/VkMemoryDedicatedAllocateInfo.txt[]
1533
1534ifdef::VK_KHR_dedicated_allocation[]
1535or the equivalent
1536
1537include::{generated}/api/structs/VkMemoryDedicatedAllocateInfoKHR.txt[]
1538endif::VK_KHR_dedicated_allocation[]
1539
1540  * pname:sType is the type of this structure.
1541  * pname:pNext is `NULL` or a pointer to a structure extending this
1542    structure.
1543  * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this
1544    memory will be bound to.
1545  * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this
1546    memory will be bound to.
1547
1548.Valid Usage
1549****
1550  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01432]]
1551    At least one of pname:image and pname:buffer must: be
1552    dlink:VK_NULL_HANDLE
1553ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
1554  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01433]]
1555    If pname:image is not dlink:VK_NULL_HANDLE,
1556    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1557    sname:VkMemoryRequirements::pname:size of the image
1558endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1559ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
1560  * [[VUID-VkMemoryDedicatedAllocateInfo-image-02964]]
1561    If pname:image is not dlink:VK_NULL_HANDLE and the memory is not an
1562    imported Android Hardware Buffer,
1563    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1564    sname:VkMemoryRequirements::pname:size of the image
1565endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1566  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01434]]
1567    If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: have been
1568    created without ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT set in
1569    slink:VkImageCreateInfo::pname:flags
1570ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
1571  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01435]]
1572    If pname:buffer is not dlink:VK_NULL_HANDLE,
1573    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1574    sname:VkMemoryRequirements::pname:size of the buffer
1575endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1576ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
1577  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-02965]]
1578    If pname:buffer is not dlink:VK_NULL_HANDLE and the memory is not an
1579    imported Android Hardware Buffer,
1580    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1581    sname:VkMemoryRequirements::pname:size of the buffer
1582endif::VK_ANDROID_external_memory_android_hardware_buffer[]
1583  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01436]]
1584    If pname:buffer is not dlink:VK_NULL_HANDLE, pname:buffer must: have
1585    been created without ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT set in
1586    slink:VkBufferCreateInfo::pname:flags
1587ifdef::VK_KHR_external_memory_win32[]
1588  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01876]]
1589    If pname:image is not dlink:VK_NULL_HANDLE and
1590    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1591    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
1592    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
1593    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
1594    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT,
1595    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or
1596    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the
1597    external handle was created by the Vulkan API, then the memory being
1598    imported must: also be a dedicated image allocation and pname:image must
1599    be identical to the image associated with the imported memory
1600  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01877]]
1601    If pname:buffer is not dlink:VK_NULL_HANDLE and
1602    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1603    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
1604    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT,
1605    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
1606    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT,
1607    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or
1608    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the
1609    external handle was created by the Vulkan API, then the memory being
1610    imported must: also be a dedicated buffer allocation and pname:buffer
1611    must: be identical to the buffer associated with the imported memory
1612endif::VK_KHR_external_memory_win32[]
1613ifdef::VK_KHR_external_memory_fd[]
1614  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01878]]
1615    If pname:image is not dlink:VK_NULL_HANDLE and
1616    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1617    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory
1618    being imported must: also be a dedicated image allocation and
1619    pname:image must: be identical to the image associated with the imported
1620    memory
1621  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01879]]
1622    If pname:buffer is not dlink:VK_NULL_HANDLE and
1623    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1624    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory
1625    being imported must: also be a dedicated buffer allocation and
1626    pname:buffer must: be identical to the buffer associated with the
1627    imported memory
1628endif::VK_KHR_external_memory_fd[]
1629ifdef::VK_KHR_sampler_ycbcr_conversion[]
1630  * [[VUID-VkMemoryDedicatedAllocateInfo-image-01797]]
1631    If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: not have
1632    been created with ename:VK_IMAGE_CREATE_DISJOINT_BIT set in
1633    slink:VkImageCreateInfo::pname:flags
1634endif::VK_KHR_sampler_ycbcr_conversion[]
1635ifdef::VK_FUCHSIA_external_memory[]
1636  * [[VUID-VkMemoryDedicatedAllocateInfo-image-04751]]
1637    If pname:image is not dlink:VK_NULL_HANDLE and
1638    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1639    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the
1640    memory being imported must: also be a dedicated image allocation and
1641    pname:image must: be identical to the image associated with the imported
1642    memory
1643  * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-04752]]
1644    If pname:buffer is not dlink:VK_NULL_HANDLE and
1645    slink:VkMemoryAllocateInfo defines a memory import operation with handle
1646    type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ZIRCON_VMO_BIT_FUCHSIA, the
1647    memory being imported must: also be a dedicated buffer allocation and
1648    pname:buffer must: be identical to the buffer associated with the
1649    imported memory
1650endif::VK_FUCHSIA_external_memory[]
1651****
1652
1653include::{generated}/validity/structs/VkMemoryDedicatedAllocateInfo.txt[]
1654--
1655endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
1656
1657ifdef::VK_NV_dedicated_allocation[]
1658[open,refpage='VkDedicatedAllocationMemoryAllocateInfoNV',desc='Specify a dedicated memory allocation resource',type='structs']
1659--
1660If the pname:pNext chain includes a
1661sname:VkDedicatedAllocationMemoryAllocateInfoNV structure, then that
1662structure includes a handle of the sole buffer or image resource that the
1663memory can: be bound to.
1664
1665The sname:VkDedicatedAllocationMemoryAllocateInfoNV structure is defined as:
1666
1667include::{generated}/api/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[]
1668
1669  * pname:sType is the type of this structure.
1670  * pname:pNext is `NULL` or a pointer to a structure extending this
1671    structure.
1672  * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this
1673    memory will be bound to.
1674  * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this
1675    memory will be bound to.
1676
1677.Valid Usage
1678****
1679  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00649]]
1680    At least one of pname:image and pname:buffer must: be
1681    dlink:VK_NULL_HANDLE
1682  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00650]]
1683    If pname:image is not dlink:VK_NULL_HANDLE, the image must: have been
1684    created with
1685    slink:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation
1686    equal to ename:VK_TRUE
1687  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00651]]
1688    If pname:buffer is not dlink:VK_NULL_HANDLE, the buffer must: have been
1689    created with
1690    slink:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation
1691    equal to ename:VK_TRUE
1692  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00652]]
1693    If pname:image is not dlink:VK_NULL_HANDLE,
1694    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1695    sname:VkMemoryRequirements::pname:size of the image
1696  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00653]]
1697    If pname:buffer is not dlink:VK_NULL_HANDLE,
1698    sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the
1699    sname:VkMemoryRequirements::pname:size of the buffer
1700ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[]
1701  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00654]]
1702    If pname:image is not dlink:VK_NULL_HANDLE and
1703    slink:VkMemoryAllocateInfo defines a memory import operation, the memory
1704    being imported must: also be a dedicated image allocation and
1705    pname:image must: be identical to the image associated with the imported
1706    memory
1707  * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00655]]
1708    If pname:buffer is not dlink:VK_NULL_HANDLE and
1709    slink:VkMemoryAllocateInfo defines a memory import operation, the memory
1710    being imported must: also be a dedicated buffer allocation and
1711    pname:buffer must: be identical to the buffer associated with the
1712    imported memory
1713endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[]
1714****
1715
1716include::{generated}/validity/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[]
1717--
1718endif::VK_NV_dedicated_allocation[]
1719
1720ifdef::VK_EXT_memory_priority[]
1721[open,refpage='VkMemoryPriorityAllocateInfoEXT',desc='Specify a memory allocation priority',type='structs']
1722--
1723If the pname:pNext chain includes a sname:VkMemoryPriorityAllocateInfoEXT
1724structure, then that structure includes a priority for the memory.
1725
1726The sname:VkMemoryPriorityAllocateInfoEXT structure is defined as:
1727
1728include::{generated}/api/structs/VkMemoryPriorityAllocateInfoEXT.txt[]
1729
1730  * pname:sType is the type of this structure.
1731  * pname:pNext is `NULL` or a pointer to a structure extending this
1732    structure.
1733  * pname:priority is a floating-point value between `0` and `1`, indicating
1734    the priority of the allocation relative to other memory allocations.
1735    Larger values are higher priority.
1736    The granularity of the priorities is implementation-dependent.
1737
1738Memory allocations with higher priority may: be more likely to stay in
1739device-local memory when the system is under memory pressure.
1740
1741If this structure is not included, it is as if the pname:priority value were
1742`0.5`.
1743
1744.Valid Usage
1745****
1746  * [[VUID-VkMemoryPriorityAllocateInfoEXT-priority-02602]]
1747    pname:priority must: be between `0` and `1`, inclusive
1748****
1749
1750include::{generated}/validity/structs/VkMemoryPriorityAllocateInfoEXT.txt[]
1751--
1752endif::VK_EXT_memory_priority[]
1753
1754ifdef::VK_EXT_pageable_device_local_memory[]
1755[open,refpage='vkSetDeviceMemoryPriorityEXT',desc='Change a memory allocation priority',type='protos']
1756--
1757
1758To modify the priority of an existing memory allocation, call:
1759
1760include::{generated}/api/protos/vkSetDeviceMemoryPriorityEXT.txt[]
1761
1762  * pname:device is the logical device that owns the memory.
1763  * pname:memory is the slink:VkDeviceMemory object to which the new
1764    priority will be applied.
1765  * pname:priority is a floating-point value between `0` and `1`, indicating
1766    the priority of the allocation relative to other memory allocations.
1767    Larger values are higher priority.
1768    The granularity of the priorities is implementation-dependent.
1769
1770Memory allocations with higher priority may: be more likely to stay in
1771device-local memory when the system is under memory pressure.
1772
1773.Valid Usage
1774****
1775  * [[VUID-vkSetDeviceMemoryPriorityEXT-priority-06258]]
1776    pname:priority must: be between `0` and `1`, inclusive
1777****
1778
1779include::{generated}/validity/protos/vkSetDeviceMemoryPriorityEXT.txt[]
1780--
1781endif::VK_EXT_pageable_device_local_memory[]
1782
1783ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
1784[open,refpage='VkExportMemoryAllocateInfo',desc='Specify exportable handle types for a device memory object',type='structs']
1785--
1786When allocating memory whose payload may: be exported to another process or
1787Vulkan instance, add a slink:VkExportMemoryAllocateInfo structure to the
1788pname:pNext chain of the slink:VkMemoryAllocateInfo structure, specifying
1789the handle types that may: be exported.
1790
1791The slink:VkExportMemoryAllocateInfo structure is defined as:
1792
1793include::{generated}/api/structs/VkExportMemoryAllocateInfo.txt[]
1794
1795ifdef::VK_KHR_external_memory[]
1796or the equivalent
1797
1798include::{generated}/api/structs/VkExportMemoryAllocateInfoKHR.txt[]
1799endif::VK_KHR_external_memory[]
1800
1801  * pname:sType is the type of this structure.
1802  * pname:pNext is `NULL` or a pointer to a structure extending this
1803    structure.
1804  * pname:handleTypes is a bitmask of
1805    elink:VkExternalMemoryHandleTypeFlagBits specifying one or more memory
1806    handle types the application can: export from the resulting allocation.
1807    The application can: request multiple handle types for the same
1808    allocation.
1809
1810.Valid Usage
1811****
1812  * [[VUID-VkExportMemoryAllocateInfo-handleTypes-00656]]
1813    The bits in pname:handleTypes must: be supported and compatible, as
1814    reported by slink:VkExternalImageFormatProperties or
1815    slink:VkExternalBufferProperties
1816****
1817
1818include::{generated}/validity/structs/VkExportMemoryAllocateInfo.txt[]
1819--
1820endif::VK_VERSION_1_1,VK_KHR_external_memory[]
1821
1822ifdef::VK_NV_external_memory[]
1823include::{chapters}/VK_NV_external_memory/allocate_memory.txt[]
1824endif::VK_NV_external_memory[]
1825
1826ifdef::VK_KHR_external_memory_win32,VK_NV_external_memory_win32[]
1827=== Win32 External Memory
1828endif::VK_KHR_external_memory_win32,VK_NV_external_memory_win32[]
1829
1830ifdef::VK_KHR_external_memory_win32[]
1831[open,refpage='VkExportMemoryWin32HandleInfoKHR',desc='Structure specifying additional attributes of Windows handles exported from a memory',type='structs']
1832--
1833To specify additional attributes of NT handles exported from a memory
1834object, add a slink:VkExportMemoryWin32HandleInfoKHR structure to the
1835pname:pNext chain of the slink:VkMemoryAllocateInfo structure.
1836The sname:VkExportMemoryWin32HandleInfoKHR structure is defined as:
1837
1838include::{generated}/api/structs/VkExportMemoryWin32HandleInfoKHR.txt[]
1839
1840  * pname:sType is the type of this structure.
1841  * pname:pNext is `NULL` or a pointer to a structure extending this
1842    structure.
1843  * pname:pAttributes is a pointer to a Windows code:SECURITY_ATTRIBUTES
1844    structure specifying security attributes of the handle.
1845  * pname:dwAccess is a code:DWORD specifying access rights of the handle.
1846  * pname:name is a null-terminated UTF-16 string to associate with the
1847    payload referenced by NT handles exported from the created memory.
1848
1849If slink:VkExportMemoryAllocateInfo is not included in the same pname:pNext
1850chain, this structure is ignored.
1851
1852If slink:VkExportMemoryAllocateInfo is included in the pname:pNext chain of
1853slink:VkMemoryAllocateInfo with a Windows pname:handleType, but either
1854sname:VkExportMemoryWin32HandleInfoKHR is not included in the pname:pNext
1855chain, or if it is but pname:pAttributes is set to `NULL`, default security
1856descriptor values will be used, and child processes created by the
1857application will not inherit the handle, as described in the MSDN
1858documentation for "`Synchronization Object Security and Access Rights`"^1^.
1859Further, if the structure is not present, the access rights used depend on
1860the handle type.
1861
1862For handles of the following types:
1863
1864  * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT
1865
1866The implementation must: ensure the access rights allow read and write
1867access to the memory.
1868
18691::
1870    https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights
1871
1872.Valid Usage
1873****
1874  * [[VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657]]
1875    If slink:VkExportMemoryAllocateInfo::pname:handleTypes does not include
1876    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, a
1877    sname:VkExportMemoryWin32HandleInfoKHR structure must: not be included
1878    in the pname:pNext chain of slink:VkMemoryAllocateInfo
1879****
1880
1881include::{generated}/validity/structs/VkExportMemoryWin32HandleInfoKHR.txt[]
1882--
1883
1884[open,refpage='VkImportMemoryWin32HandleInfoKHR',desc='Import Win32 memory created on the same physical device',type='structs']
1885--
1886To import memory from a Windows handle, add a
1887slink:VkImportMemoryWin32HandleInfoKHR structure to the pname:pNext chain of
1888the slink:VkMemoryAllocateInfo structure.
1889
1890The sname:VkImportMemoryWin32HandleInfoKHR structure is defined as:
1891
1892include::{generated}/api/structs/VkImportMemoryWin32HandleInfoKHR.txt[]
1893
1894  * pname:sType is the type of this structure.
1895  * pname:pNext is `NULL` or a pointer to a structure extending this
1896    structure.
1897  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
1898    specifying the type of pname:handle or pname:name.
1899  * pname:handle is `NULL` or the external handle to import.
1900  * pname:name is `NULL` or a null-terminated UTF-16 string naming the
1901    payload to import.
1902
1903Importing memory object payloads from Windows handles does not transfer
1904ownership of the handle to the Vulkan implementation.
1905For handle types defined as NT handles, the application must: release handle
1906ownership using the code:CloseHandle system call when the handle is no
1907longer needed.
1908For handle types defined as NT handles, the imported memory object holds a
1909reference to its payload.
1910
1911[NOTE]
1912.Note
1913====
1914Non-NT handle import operations do not add a reference to their associated
1915payload.
1916If the original object owning the payload is destroyed, all resources and
1917handles sharing that payload will become invalid.
1918====
1919
1920Applications can: import the same payload into multiple instances of Vulkan,
1921into the same instance from which it was exported, and multiple times into a
1922given Vulkan instance.
1923In all cases, each import operation must: create a distinct
1924sname:VkDeviceMemory object.
1925
1926.Valid Usage
1927****
1928  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00658]]
1929    If pname:handleType is not `0`, it must: be supported for import, as
1930    reported by slink:VkExternalImageFormatProperties or
1931    slink:VkExternalBufferProperties
1932  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-00659]]
1933    The memory from which pname:handle was exported, or the memory named by
1934    pname:name must: have been created on the same underlying physical
1935    device as pname:device
1936  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00660]]
1937    If pname:handleType is not `0`, it must: be defined as an NT handle or a
1938    global share handle
1939  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01439]]
1940    If pname:handleType is not
1941    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT,
1942    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT,
1943    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or
1944    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, pname:name
1945    must: be `NULL`
1946  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01440]]
1947    If pname:handleType is not `0` and pname:handle is `NULL`, pname:name
1948    must: name a valid memory resource of the type specified by
1949    pname:handleType
1950  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00661]]
1951    If pname:handleType is not `0` and pname:name is `NULL`, pname:handle
1952    must: be a valid handle of the type specified by pname:handleType
1953  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01441]]
1954    if pname:handle is not `NULL`, pname:name must: be `NULL`
1955  * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01518]]
1956    If pname:handle is not `NULL`, it must: obey any requirements listed for
1957    pname:handleType in
1958    <<external-memory-handle-types-compatibility,external memory handle
1959    types compatibility>>
1960  * [[VUID-VkImportMemoryWin32HandleInfoKHR-name-01519]]
1961    If pname:name is not `NULL`, it must: obey any requirements listed for
1962    pname:handleType in
1963    <<external-memory-handle-types-compatibility,external memory handle
1964    types compatibility>>
1965****
1966
1967include::{generated}/validity/structs/VkImportMemoryWin32HandleInfoKHR.txt[]
1968--
1969
1970[open,refpage='vkGetMemoryWin32HandleKHR',desc='Get a Windows HANDLE for a memory object',type='protos']
1971--
1972To export a Windows handle representing the payload of a Vulkan device
1973memory object, call:
1974
1975include::{generated}/api/protos/vkGetMemoryWin32HandleKHR.txt[]
1976
1977  * pname:device is the logical device that created the device memory being
1978    exported.
1979  * pname:pGetWin32HandleInfo is a pointer to a
1980    slink:VkMemoryGetWin32HandleInfoKHR structure containing parameters of
1981    the export operation.
1982  * pname:pHandle will return the Windows handle representing the payload of
1983    the device memory object.
1984
1985For handle types defined as NT handles, the handles returned by
1986fname:vkGetMemoryWin32HandleKHR are owned by the application and hold a
1987reference to their payload.
1988To avoid leaking resources, the application must: release ownership of them
1989using the code:CloseHandle system call when they are no longer needed.
1990
1991[NOTE]
1992.Note
1993====
1994Non-NT handle types do not add a reference to their associated payload.
1995If the original object owning the payload is destroyed, all resources and
1996handles sharing that payload will become invalid.
1997====
1998
1999include::{generated}/validity/protos/vkGetMemoryWin32HandleKHR.txt[]
2000--
2001
2002[open,refpage='VkMemoryGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle semaphore export operation',type='structs']
2003--
2004The sname:VkMemoryGetWin32HandleInfoKHR structure is defined as:
2005
2006include::{generated}/api/structs/VkMemoryGetWin32HandleInfoKHR.txt[]
2007
2008  * pname:sType is the type of this structure.
2009  * pname:pNext is `NULL` or a pointer to a structure extending this
2010    structure.
2011  * pname:memory is the memory object from which the handle will be
2012    exported.
2013  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2014    specifying the type of handle requested.
2015
2016The properties of the handle returned depend on the value of
2017pname:handleType.
2018See elink:VkExternalMemoryHandleTypeFlagBits for a description of the
2019properties of the defined external memory handle types.
2020
2021.Valid Usage
2022****
2023  * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00662]]
2024    pname:handleType must: have been included in
2025    slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
2026    was created
2027  * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00663]]
2028    If pname:handleType is defined as an NT handle,
2029    flink:vkGetMemoryWin32HandleKHR must: be called no more than once for
2030    each valid unique combination of pname:memory and pname:handleType
2031  * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00664]]
2032    pname:handleType must: be defined as an NT handle or a global share
2033    handle
2034****
2035
2036include::{generated}/validity/structs/VkMemoryGetWin32HandleInfoKHR.txt[]
2037--
2038
2039[open,refpage='vkGetMemoryWin32HandlePropertiesKHR',desc='Get Properties of External Memory Win32 Handles',type='protos']
2040--
2041Windows memory handles compatible with Vulkan may: also be created by
2042non-Vulkan APIs using methods beyond the scope of this specification.
2043To determine the correct parameters to use when importing such handles,
2044call:
2045
2046include::{generated}/api/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[]
2047
2048  * pname:device is the logical device that will be importing pname:handle.
2049  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2050    specifying the type of the handle pname:handle.
2051  * pname:handle is the handle which will be imported.
2052  * pname:pMemoryWin32HandleProperties is a pointer to a
2053    slink:VkMemoryWin32HandlePropertiesKHR structure in which properties of
2054    pname:handle are returned.
2055
2056.Valid Usage
2057****
2058  * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handle-00665]]
2059    pname:handle must: be an external memory handle created outside of the
2060    Vulkan API
2061  * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-00666]]
2062    pname:handleType must: not be one of the handle types defined as opaque
2063****
2064
2065include::{generated}/validity/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[]
2066--
2067
2068[open,refpage='VkMemoryWin32HandlePropertiesKHR',desc='Properties of External Memory Windows Handles',type='structs']
2069--
2070The sname:VkMemoryWin32HandlePropertiesKHR structure returned is defined as:
2071
2072include::{generated}/api/structs/VkMemoryWin32HandlePropertiesKHR.txt[]
2073
2074  * pname:sType is the type of this structure.
2075  * pname:pNext is `NULL` or a pointer to a structure extending this
2076    structure.
2077  * pname:memoryTypeBits is a bitmask containing one bit set for every
2078    memory type which the specified windows handle can: be imported as.
2079
2080include::{generated}/validity/structs/VkMemoryWin32HandlePropertiesKHR.txt[]
2081--
2082endif::VK_KHR_external_memory_win32[]
2083
2084ifdef::VK_NV_external_memory_win32[]
2085include::{chapters}/VK_NV_external_memory_win32/handle_permissions.txt[]
2086
2087include::{chapters}/VK_NV_external_memory_win32/import_memory_win32.txt[]
2088
2089include::{chapters}/VK_NV_external_memory_win32/get_handle_win32.txt[]
2090endif::VK_NV_external_memory_win32[]
2091
2092ifdef::VK_KHR_external_memory_fd[]
2093=== File Descriptor External Memory
2094
2095[open,refpage='VkImportMemoryFdInfoKHR',desc='Import memory created on the same physical device from a file descriptor',type='structs']
2096--
2097To import memory from a POSIX file descriptor handle, add a
2098slink:VkImportMemoryFdInfoKHR structure to the pname:pNext chain of the
2099slink:VkMemoryAllocateInfo structure.
2100The sname:VkImportMemoryFdInfoKHR structure is defined as:
2101
2102include::{generated}/api/structs/VkImportMemoryFdInfoKHR.txt[]
2103
2104  * pname:sType is the type of this structure.
2105  * pname:pNext is `NULL` or a pointer to a structure extending this
2106    structure.
2107  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2108    specifying the handle type of pname:fd.
2109  * pname:fd is the external handle to import.
2110
2111Importing memory from a file descriptor transfers ownership of the file
2112descriptor from the application to the Vulkan implementation.
2113The application must: not perform any operations on the file descriptor
2114after a successful import.
2115The imported memory object holds a reference to its payload.
2116
2117Applications can: import the same payload into multiple instances of Vulkan,
2118into the same instance from which it was exported, and multiple times into a
2119given Vulkan instance.
2120In all cases, each import operation must: create a distinct
2121sname:VkDeviceMemory object.
2122
2123.Valid Usage
2124****
2125  * [[VUID-VkImportMemoryFdInfoKHR-handleType-00667]]
2126    If pname:handleType is not `0`, it must: be supported for import, as
2127    reported by slink:VkExternalImageFormatProperties or
2128    slink:VkExternalBufferProperties
2129  * [[VUID-VkImportMemoryFdInfoKHR-fd-00668]]
2130    The memory from which pname:fd was exported must: have been created on
2131    the same underlying physical device as pname:device
2132  * [[VUID-VkImportMemoryFdInfoKHR-handleType-00669]]
2133    If pname:handleType is not `0`, it must: be
2134    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or
2135    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
2136  * [[VUID-VkImportMemoryFdInfoKHR-handleType-00670]]
2137    If pname:handleType is not `0`, pname:fd must: be a valid handle of the
2138    type specified by pname:handleType
2139  * [[VUID-VkImportMemoryFdInfoKHR-fd-01746]]
2140    The memory represented by pname:fd must: have been created from a
2141    physical device and driver that is compatible with pname:device and
2142    pname:handleType, as described in
2143    <<external-memory-handle-types-compatibility>>
2144  * [[VUID-VkImportMemoryFdInfoKHR-fd-01520]]
2145    pname:fd must: obey any requirements listed for pname:handleType in
2146    <<external-memory-handle-types-compatibility,external memory handle
2147    types compatibility>>
2148****
2149
2150include::{generated}/validity/structs/VkImportMemoryFdInfoKHR.txt[]
2151--
2152
2153[open,refpage='vkGetMemoryFdKHR',desc='Get a POSIX file descriptor for a memory object',type='protos']
2154--
2155To export a POSIX file descriptor referencing the payload of a Vulkan device
2156memory object, call:
2157
2158include::{generated}/api/protos/vkGetMemoryFdKHR.txt[]
2159
2160  * pname:device is the logical device that created the device memory being
2161    exported.
2162  * pname:pGetFdInfo is a pointer to a slink:VkMemoryGetFdInfoKHR structure
2163    containing parameters of the export operation.
2164  * pname:pFd will return a file descriptor referencing the payload of the
2165    device memory object.
2166
2167Each call to fname:vkGetMemoryFdKHR must: create a new file descriptor
2168holding a reference to the memory object's payload and transfer ownership of
2169the file descriptor to the application.
2170To avoid leaking resources, the application must: release ownership of the
2171file descriptor using the code:close system call when it is no longer
2172needed, or by importing a Vulkan memory object from it.
2173Where supported by the operating system, the implementation must: set the
2174file descriptor to be closed automatically when an code:execve system call
2175is made.
2176
2177include::{generated}/validity/protos/vkGetMemoryFdKHR.txt[]
2178--
2179
2180[open,refpage='VkMemoryGetFdInfoKHR',desc='Structure describing a POSIX FD semaphore export operation',type='structs']
2181--
2182The sname:VkMemoryGetFdInfoKHR structure is defined as:
2183
2184include::{generated}/api/structs/VkMemoryGetFdInfoKHR.txt[]
2185
2186  * pname:sType is the type of this structure.
2187  * pname:pNext is `NULL` or a pointer to a structure extending this
2188    structure.
2189  * pname:memory is the memory object from which the handle will be
2190    exported.
2191  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2192    specifying the type of handle requested.
2193
2194The properties of the file descriptor exported depend on the value of
2195pname:handleType.
2196See elink:VkExternalMemoryHandleTypeFlagBits for a description of the
2197properties of the defined external memory handle types.
2198
2199ifdef::VK_EXT_external_memory_dma_buf[]
2200[NOTE]
2201.Note
2202====
2203The size of the exported file may: be larger than the size requested by
2204slink:VkMemoryAllocateInfo::pname:allocationSize.
2205If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT,
2206then the application can: query the file's actual size with
2207link:https://man7.org/linux/man-pages/man2/lseek.2.html[`lseek`].
2208====
2209endif::VK_EXT_external_memory_dma_buf[]
2210
2211.Valid Usage
2212****
2213  * [[VUID-VkMemoryGetFdInfoKHR-handleType-00671]]
2214    pname:handleType must: have been included in
2215    slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
2216    was created
2217  * [[VUID-VkMemoryGetFdInfoKHR-handleType-00672]]
2218    pname:handleType must: be
2219    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT or
2220    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
2221****
2222
2223include::{generated}/validity/structs/VkMemoryGetFdInfoKHR.txt[]
2224--
2225
2226[open,refpage='vkGetMemoryFdPropertiesKHR',desc='Get Properties of External Memory File Descriptors',type='protos']
2227--
2228POSIX file descriptor memory handles compatible with Vulkan may: also be
2229created by non-Vulkan APIs using methods beyond the scope of this
2230specification.
2231To determine the correct parameters to use when importing such handles,
2232call:
2233
2234include::{generated}/api/protos/vkGetMemoryFdPropertiesKHR.txt[]
2235
2236  * pname:device is the logical device that will be importing pname:fd.
2237  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2238    specifying the type of the handle pname:fd.
2239  * pname:fd is the handle which will be imported.
2240  * pname:pMemoryFdProperties is a pointer to a
2241    slink:VkMemoryFdPropertiesKHR structure in which the properties of the
2242    handle pname:fd are returned.
2243
2244.Valid Usage
2245****
2246  * [[VUID-vkGetMemoryFdPropertiesKHR-fd-00673]]
2247    pname:fd must: be an external memory handle created outside of the
2248    Vulkan API
2249  * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]]
2250    pname:handleType must: not be
2251    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT
2252****
2253
2254include::{generated}/validity/protos/vkGetMemoryFdPropertiesKHR.txt[]
2255--
2256
2257[open,refpage='VkMemoryFdPropertiesKHR',desc='Properties of External Memory File Descriptors',type='structs']
2258--
2259The sname:VkMemoryFdPropertiesKHR structure returned is defined as:
2260
2261include::{generated}/api/structs/VkMemoryFdPropertiesKHR.txt[]
2262
2263  * pname:sType is the type of this structure.
2264  * pname:pNext is `NULL` or a pointer to a structure extending this
2265    structure.
2266  * pname:memoryTypeBits is a bitmask containing one bit set for every
2267    memory type which the specified file descriptor can: be imported as.
2268
2269include::{generated}/validity/structs/VkMemoryFdPropertiesKHR.txt[]
2270--
2271endif::VK_KHR_external_memory_fd[]
2272
2273ifdef::VK_EXT_external_memory_host[]
2274=== Host External Memory
2275
2276[open,refpage='VkImportMemoryHostPointerInfoEXT',desc='Import memory from a host pointer',type='structs']
2277--
2278To import memory from a host pointer, add a
2279slink:VkImportMemoryHostPointerInfoEXT structure to the pname:pNext chain of
2280the slink:VkMemoryAllocateInfo structure.
2281The sname:VkImportMemoryHostPointerInfoEXT structure is defined as:
2282
2283include::{generated}/api/structs/VkImportMemoryHostPointerInfoEXT.txt[]
2284
2285  * pname:sType is the type of this structure.
2286  * pname:pNext is `NULL` or a pointer to a structure extending this
2287    structure.
2288  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2289    specifying the handle type.
2290  * pname:pHostPointer is the host pointer to import from.
2291
2292Importing memory from a host pointer shares ownership of the memory between
2293the host and the Vulkan implementation.
2294The application can: continue to access the memory through the host pointer
2295but it is the application's responsibility to synchronize device and
2296non-device access to the payload as defined in
2297<<memory-device-hostaccess,Host Access to Device Memory Objects>>.
2298
2299Applications can: import the same payload into multiple instances of Vulkan
2300and multiple times into a given Vulkan instance.
2301However, implementations may: fail to import the same payload multiple times
2302into a given physical device due to platform constraints.
2303
2304Importing memory from a particular host pointer may: not be possible due to
2305additional platform-specific restrictions beyond the scope of this
2306specification in which case the implementation must: fail the memory import
2307operation with the error code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR.
2308
2309Whether device memory objects imported from a host pointer hold a reference
2310to their payload is undefined:.
2311As such, the application must: ensure that the imported memory range remains
2312valid and accessible for the lifetime of the imported memory object.
2313
2314.Valid Usage
2315****
2316  * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01747]]
2317    If pname:handleType is not `0`, it must: be supported for import, as
2318    reported in slink:VkExternalMemoryProperties
2319  * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01748]]
2320    If pname:handleType is not `0`, it must: be
2321    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or
2322    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
2323  * [[VUID-VkImportMemoryHostPointerInfoEXT-pHostPointer-01749]]
2324    pname:pHostPointer must: be a pointer aligned to an integer multiple of
2325    sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment
2326  * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01750]]
2327    If pname:handleType is
2328    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT,
2329    pname:pHostPointer must: be a pointer to pname:allocationSize number of
2330    bytes of host memory, where pname:allocationSize is the member of the
2331    sname:VkMemoryAllocateInfo structure this structure is chained to
2332  * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01751]]
2333    If pname:handleType is
2334    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT,
2335    pname:pHostPointer must: be a pointer to pname:allocationSize number of
2336    bytes of host mapped foreign memory, where pname:allocationSize is the
2337    member of the sname:VkMemoryAllocateInfo structure this structure is
2338    chained to
2339****
2340
2341include::{generated}/validity/structs/VkImportMemoryHostPointerInfoEXT.txt[]
2342--
2343
2344[open,refpage='vkGetMemoryHostPointerPropertiesEXT',desc='Get properties of external memory host pointer',type='protos']
2345--
2346To determine the correct parameters to use when importing host pointers,
2347call:
2348
2349include::{generated}/api/protos/vkGetMemoryHostPointerPropertiesEXT.txt[]
2350
2351  * pname:device is the logical device that will be importing
2352    pname:pHostPointer.
2353  * pname:handleType is a elink:VkExternalMemoryHandleTypeFlagBits value
2354    specifying the type of the handle pname:pHostPointer.
2355  * pname:pHostPointer is the host pointer to import from.
2356  * pname:pMemoryHostPointerProperties is a pointer to a
2357    slink:VkMemoryHostPointerPropertiesEXT structure in which the host
2358    pointer properties are returned.
2359
2360.Valid Usage
2361****
2362  * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01752]]
2363    pname:handleType must: be
2364    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or
2365    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
2366  * [[VUID-vkGetMemoryHostPointerPropertiesEXT-pHostPointer-01753]]
2367    pname:pHostPointer must: be a pointer aligned to an integer multiple of
2368    sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment
2369  * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01754]]
2370    If pname:handleType is
2371    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT,
2372    pname:pHostPointer must: be a pointer to host memory
2373  * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01755]]
2374    If pname:handleType is
2375    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT,
2376    pname:pHostPointer must: be a pointer to host mapped foreign memory
2377****
2378
2379include::{generated}/validity/protos/vkGetMemoryHostPointerPropertiesEXT.txt[]
2380--
2381
2382[open,refpage='VkMemoryHostPointerPropertiesEXT',desc='Properties of external memory host pointer',type='structs']
2383--
2384The sname:VkMemoryHostPointerPropertiesEXT structure is defined as:
2385
2386include::{generated}/api/structs/VkMemoryHostPointerPropertiesEXT.txt[]
2387
2388  * pname:sType is the type of this structure.
2389  * pname:pNext is `NULL` or a pointer to a structure extending this
2390    structure.
2391  * pname:memoryTypeBits is a bitmask containing one bit set for every
2392    memory type which the specified host pointer can: be imported as.
2393
2394The value returned by pname:memoryTypeBits must: only include bits that
2395identify memory types which are host visible.
2396
2397include::{generated}/validity/structs/VkMemoryHostPointerPropertiesEXT.txt[]
2398--
2399
2400endif::VK_EXT_external_memory_host[]
2401
2402ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
2403=== Android Hardware Buffer External Memory
2404
2405[open,refpage='VkImportAndroidHardwareBufferInfoANDROID',desc='Import memory from an Android hardware buffer',type='structs']
2406--
2407To import memory created outside of the current Vulkan instance from an
2408Android hardware buffer, add a
2409sname:VkImportAndroidHardwareBufferInfoANDROID structure to the pname:pNext
2410chain of the slink:VkMemoryAllocateInfo structure.
2411The sname:VkImportAndroidHardwareBufferInfoANDROID structure is defined as:
2412
2413include::{generated}/api/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[]
2414
2415  * pname:sType is the type of this structure.
2416  * pname:pNext is `NULL` or a pointer to a structure extending this
2417    structure.
2418  * pname:buffer is the Android hardware buffer to import.
2419
2420If the flink:vkAllocateMemory command succeeds, the implementation must:
2421acquire a reference to the imported hardware buffer, which it must: release
2422when the device memory object is freed.
2423If the command fails, the implementation must: not retain a reference.
2424
2425.Valid Usage
2426****
2427  * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01880]]
2428    If pname:buffer is not `NULL`, Android hardware buffers must: be
2429    supported for import, as reported by
2430    slink:VkExternalImageFormatProperties or
2431    slink:VkExternalBufferProperties
2432  * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01881]]
2433    If pname:buffer is not `NULL`, it must: be a valid Android hardware
2434    buffer object with code:AHardwareBuffer_Desc::code:usage compatible with
2435    Vulkan as described in <<memory-external-android-hardware-buffer,Android
2436    Hardware Buffers>>
2437****
2438
2439include::{generated}/validity/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[]
2440--
2441
2442[open,refpage='vkGetMemoryAndroidHardwareBufferANDROID',desc='Get an Android hardware buffer for a memory object',type='protos']
2443--
2444To export an Android hardware buffer referencing the payload of a Vulkan
2445device memory object, call:
2446
2447include::{generated}/api/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[]
2448
2449  * pname:device is the logical device that created the device memory being
2450    exported.
2451  * pname:pInfo is a pointer to a
2452    slink:VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing
2453    parameters of the export operation.
2454  * pname:pBuffer will return an Android hardware buffer referencing the
2455    payload of the device memory object.
2456
2457Each call to fname:vkGetMemoryAndroidHardwareBufferANDROID must: return an
2458Android hardware buffer with a new reference acquired in addition to the
2459reference held by the slink:VkDeviceMemory.
2460To avoid leaking resources, the application must: release the reference by
2461calling code:AHardwareBuffer_release when it is no longer needed.
2462When called with the same handle in
2463slink:VkMemoryGetAndroidHardwareBufferInfoANDROID::pname:memory,
2464fname:vkGetMemoryAndroidHardwareBufferANDROID must: return the same Android
2465hardware buffer object.
2466If the device memory was created by importing an Android hardware buffer,
2467fname:vkGetMemoryAndroidHardwareBufferANDROID must: return that same Android
2468hardware buffer object.
2469
2470include::{generated}/validity/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[]
2471--
2472
2473[open,refpage='VkMemoryGetAndroidHardwareBufferInfoANDROID',desc='Structure describing an Android hardware buffer memory export operation',type='structs']
2474--
2475The sname:VkMemoryGetAndroidHardwareBufferInfoANDROID structure is defined
2476as:
2477
2478include::{generated}/api/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[]
2479
2480  * pname:sType is the type of this structure.
2481  * pname:pNext is `NULL` or a pointer to a structure extending this
2482    structure.
2483  * pname:memory is the memory object from which the Android hardware buffer
2484    will be exported.
2485
2486.Valid Usage
2487****
2488  * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-handleTypes-01882]]
2489    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
2490    must: have been included in
2491    slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
2492    was created
2493  * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-01883]]
2494    If the pname:pNext chain of the slink:VkMemoryAllocateInfo used to
2495    allocate pname:memory included a slink:VkMemoryDedicatedAllocateInfo
2496    with non-`NULL` pname:image member, then that pname:image must: already
2497    be bound to pname:memory
2498****
2499
2500include::{generated}/validity/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[]
2501--
2502
2503[open,refpage='vkGetAndroidHardwareBufferPropertiesANDROID',desc='Get Properties of External Memory Android Hardware Buffers',type='protos']
2504--
2505To determine the memory parameters to use when importing an Android hardware
2506buffer, call:
2507
2508include::{generated}/api/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[]
2509
2510  * pname:device is the logical device that will be importing pname:buffer.
2511  * pname:buffer is the Android hardware buffer which will be imported.
2512  * pname:pProperties is a pointer to a
2513    slink:VkAndroidHardwareBufferPropertiesANDROID structure in which the
2514    properties of pname:buffer are returned.
2515
2516.Valid Usage
2517****
2518  * [[VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-01884]]
2519    pname:buffer must: be a valid Android hardware buffer object with at
2520    least one of the code:AHARDWAREBUFFER_USAGE_GPU_* flags in its
2521    code:AHardwareBuffer_Desc::code:usage
2522****
2523
2524include::{generated}/validity/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[]
2525--
2526
2527[open,refpage='VkAndroidHardwareBufferPropertiesANDROID',desc='Properties of External Memory Android Hardware Buffers',type='structs']
2528--
2529The sname:VkAndroidHardwareBufferPropertiesANDROID structure returned is
2530defined as:
2531
2532include::{generated}/api/structs/VkAndroidHardwareBufferPropertiesANDROID.txt[]
2533
2534  * pname:sType is the type of this structure.
2535  * pname:pNext is `NULL` or a pointer to a structure extending this
2536    structure.
2537  * pname:allocationSize is the size of the external memory
2538  * pname:memoryTypeBits is a bitmask containing one bit set for every
2539    memory type which the specified Android hardware buffer can: be imported
2540    as.
2541
2542include::{generated}/validity/structs/VkAndroidHardwareBufferPropertiesANDROID.txt[]
2543--
2544
2545[open,refpage='VkAndroidHardwareBufferFormatPropertiesANDROID',desc='Structure describing the image format properties of an Android hardware buffer',type='structs']
2546--
2547To obtain format properties of an Android hardware buffer, include a
2548sname:VkAndroidHardwareBufferFormatPropertiesANDROID structure in the
2549pname:pNext chain of the slink:VkAndroidHardwareBufferPropertiesANDROID
2550structure passed to flink:vkGetAndroidHardwareBufferPropertiesANDROID.
2551This structure is defined as:
2552
2553include::{generated}/api/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[]
2554
2555  * pname:sType is the type of this structure.
2556  * pname:pNext is `NULL` or a pointer to a structure extending this
2557    structure.
2558  * pname:format is the Vulkan format corresponding to the Android hardware
2559    buffer's format, or ename:VK_FORMAT_UNDEFINED if there is not an
2560    equivalent Vulkan format.
2561  * pname:externalFormat is an implementation-defined external format
2562    identifier for use with slink:VkExternalFormatANDROID.
2563    It must: not be zero.
2564  * pname:formatFeatures describes the capabilities of this external format
2565    when used with an image bound to memory imported from pname:buffer.
2566  * pname:samplerYcbcrConversionComponents is the component swizzle that
2567    should: be used in slink:VkSamplerYcbcrConversionCreateInfo.
2568  * pname:suggestedYcbcrModel is a suggested color model to use in the
2569    slink:VkSamplerYcbcrConversionCreateInfo.
2570  * pname:suggestedYcbcrRange is a suggested numerical value range to use in
2571    slink:VkSamplerYcbcrConversionCreateInfo.
2572  * pname:suggestedXChromaOffset is a suggested X chroma offset to use in
2573    slink:VkSamplerYcbcrConversionCreateInfo.
2574  * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in
2575    slink:VkSamplerYcbcrConversionCreateInfo.
2576
2577If the Android hardware buffer has one of the formats listed in the
2578<<memory-external-android-hardware-buffer-formats,Format Equivalence
2579table>>, then pname:format must: have the equivalent Vulkan format listed in
2580the table.
2581Otherwise, pname:format may: be ename:VK_FORMAT_UNDEFINED, indicating the
2582Android hardware buffer can: only be used with an external format.
2583
2584The pname:formatFeatures member must: include
2585ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and at least one of
2586ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or
2587ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, and should: include
2588ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and
2589ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.
2590
2591[NOTE]
2592.Note
2593====
2594The pname:formatFeatures member only indicates the features available when
2595using an
2596<<memory-external-android-hardware-buffer-external-formats,external-format
2597image>> created from the Android hardware buffer.
2598Images from Android hardware buffers with a format other than
2599ename:VK_FORMAT_UNDEFINED are subject to the format capabilities obtained
2600from flink:vkGetPhysicalDeviceFormatProperties2, and
2601flink:vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters.
2602These sets of features are independent of each other, e.g. the external
2603format will support sampler {YCbCr} conversion even if the non-external
2604format does not, and writing to non-external format images is possible but
2605writing to external format images is not.
2606====
2607
2608Android hardware buffers with the same external format must: have the same
2609support for ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT,
2610ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT,
2611ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT,
2612ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT,
2613ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT,
2614and
2615ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT.
2616in pname:formatFeatures.
2617Other format features may: differ between Android hardware buffers that have
2618the same external format.
2619This allows applications to use the same slink:VkSamplerYcbcrConversion
2620object (and samplers and pipelines created from them) for any Android
2621hardware buffers that have the same external format.
2622
2623If pname:format is not ename:VK_FORMAT_UNDEFINED, then the value of
2624pname:samplerYcbcrConversionComponents must: be valid when used as the
2625pname:components member of slink:VkSamplerYcbcrConversionCreateInfo with
2626that format.
2627If pname:format is ename:VK_FORMAT_UNDEFINED, all members of
2628pname:samplerYcbcrConversionComponents must: be the
2629<<resources-image-views-identity-mappings,identity swizzle>>.
2630
2631Implementations may: not always be able to determine the color model,
2632numerical range, or chroma offsets of the image contents, so the values in
2633sname:VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions.
2634Applications should: treat these values as sensible defaults to use in the
2635absence of more reliable information obtained through some other means.
2636If the underlying physical device is also usable via OpenGL ES with the
2637https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`]
2638extension, the implementation should: suggest values that will produce
2639similar sampled values as would be obtained by sampling the same external
2640image via code:samplerExternalOES in OpenGL ES using equivalent sampler
2641parameters.
2642
2643[NOTE]
2644.Note
2645====
2646Since
2647https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[`GL_OES_EGL_image_external`]
2648does not require the same sampling and conversion calculations as Vulkan
2649does, achieving identical results between APIs may: not be possible on some
2650implementations.
2651====
2652
2653include::{generated}/validity/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[]
2654--
2655
2656ifdef::VK_KHR_format_feature_flags2[]
2657[open,refpage='VkAndroidHardwareBufferFormatProperties2ANDROID',desc='Structure describing the image format properties of an Android hardware buffer',type='structs']
2658--
2659The format properties of an Android hardware buffer can: be obtained by
2660including a sname:VkAndroidHardwareBufferFormatProperties2ANDROID structure
2661in the pname:pNext chain of the
2662slink:VkAndroidHardwareBufferPropertiesANDROID structure passed to
2663flink:vkGetAndroidHardwareBufferPropertiesANDROID.
2664This structure is defined as:
2665
2666include::{generated}/api/structs/VkAndroidHardwareBufferFormatProperties2ANDROID.txt[]
2667
2668  * pname:sType is the type of this structure.
2669  * pname:pNext is `NULL` or a pointer to a structure extending this
2670    structure.
2671  * pname:format is the Vulkan format corresponding to the Android hardware
2672    buffer's format, or ename:VK_FORMAT_UNDEFINED if there is not an
2673    equivalent Vulkan format.
2674  * pname:externalFormat is an implementation-defined external format
2675    identifier for use with slink:VkExternalFormatANDROID.
2676    It must: not be zero.
2677  * pname:formatFeatures describes the capabilities of this external format
2678    when used with an image bound to memory imported from pname:buffer.
2679  * pname:samplerYcbcrConversionComponents is the component swizzle that
2680    should: be used in slink:VkSamplerYcbcrConversionCreateInfo.
2681  * pname:suggestedYcbcrModel is a suggested color model to use in the
2682    slink:VkSamplerYcbcrConversionCreateInfo.
2683  * pname:suggestedYcbcrRange is a suggested numerical value range to use in
2684    slink:VkSamplerYcbcrConversionCreateInfo.
2685  * pname:suggestedXChromaOffset is a suggested X chroma offset to use in
2686    slink:VkSamplerYcbcrConversionCreateInfo.
2687  * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in
2688    slink:VkSamplerYcbcrConversionCreateInfo.
2689
2690The bits reported in pname:formatFeatures must: include the bits reported in
2691the corresponding fields of
2692sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures.
2693
2694include::{generated}/validity/structs/VkAndroidHardwareBufferFormatProperties2ANDROID.txt[]
2695--
2696endif::VK_KHR_format_feature_flags2[]
2697endif::VK_ANDROID_external_memory_android_hardware_buffer[]
2698
2699ifdef::VK_NV_external_memory_rdma[]
2700[open,refpage='vkGetMemoryRemoteAddressNV',desc='Get an address for a memory object accessible by remote devices',type='protos']
2701--
2702To export an address representing the payload of a Vulkan device memory
2703object accessible by remote devices, call:
2704
2705include::{generated}/api/protos/vkGetMemoryRemoteAddressNV.txt[]
2706
2707  * pname:device is the logical device that created the device memory being
2708    exported.
2709  * pname:pMemoryGetRemoteAddressInfo is a pointer to a
2710    slink:VkMemoryGetRemoteAddressInfoNV structure containing parameters of
2711    the export operation.
2712  * pname:pAddress will return the address representing the payload of the
2713    device memory object.
2714
2715More communication may be required between the kernel-mode drivers of the
2716devices involved.
2717This information is out of scope of this documentation and should be
2718requested from the vendors of the devices.
2719
2720include::{generated}/validity/protos/vkGetMemoryRemoteAddressNV.txt[]
2721--
2722
2723[open,refpage='VkMemoryGetRemoteAddressInfoNV',desc='Structure describing a remote accessible address export operation',type='structs']
2724--
2725The sname:VkMemoryGetRemoteAddressInfoNV structure is defined as:
2726
2727include::{generated}/api/structs/VkMemoryGetRemoteAddressInfoNV.txt[]
2728
2729  * pname:sType is the type of this structure.
2730  * pname:pNext is `NULL` or a pointer to a structure extending this
2731    structure.
2732  * pname:memory is the memory object from which the remote accessible
2733    address will be exported.
2734  * pname:handleType is the type of handle requested.
2735
2736.Valid Usage
2737****
2738  * [[VUID-VkMemoryGetRemoteAddressInfoNV-handleType-04966]]
2739    pname:handleType must: have been included in
2740    slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory
2741    was created
2742****
2743
2744include::{generated}/validity/structs/VkMemoryGetRemoteAddressInfoNV.txt[]
2745--
2746endif::VK_NV_external_memory_rdma[]
2747
2748ifdef::VK_FUCHSIA_external_memory[]
2749include::{chapters}/VK_FUCHSIA_external_memory/device_memory.txt[]
2750endif::VK_FUCHSIA_external_memory[]
2751
2752
2753ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
2754=== Device Group Memory Allocations
2755
2756[open,refpage='VkMemoryAllocateFlagsInfo',desc='Structure controlling how many instances of memory will be allocated',type='structs']
2757--
2758If the pname:pNext chain of slink:VkMemoryAllocateInfo includes a
2759sname:VkMemoryAllocateFlagsInfo structure, then that structure includes
2760flags and a device mask controlling how many instances of the memory will be
2761allocated.
2762
2763The sname:VkMemoryAllocateFlagsInfo structure is defined as:
2764
2765include::{generated}/api/structs/VkMemoryAllocateFlagsInfo.txt[]
2766
2767ifdef::VK_KHR_device_group[]
2768or the equivalent
2769
2770include::{generated}/api/structs/VkMemoryAllocateFlagsInfoKHR.txt[]
2771endif::VK_KHR_device_group[]
2772
2773  * pname:sType is the type of this structure.
2774  * pname:pNext is `NULL` or a pointer to a structure extending this
2775    structure.
2776  * pname:flags is a bitmask of elink:VkMemoryAllocateFlagBits controlling
2777    the allocation.
2778  * pname:deviceMask is a mask of physical devices in the logical device,
2779    indicating that memory must: be allocated on each device in the mask, if
2780    ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set in pname:flags.
2781
2782If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is not set, the number of
2783instances allocated depends on whether
2784ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set in the memory heap.
2785If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set, then memory is allocated
2786for every physical device in the logical device (as if pname:deviceMask has
2787bits set for all device indices).
2788If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is not set, then a single
2789instance of memory is allocated (as if pname:deviceMask is set to one).
2790
2791On some implementations, allocations from a multi-instance heap may: consume
2792memory on all physical devices even if the pname:deviceMask excludes some
2793devices.
2794If slink:VkPhysicalDeviceGroupProperties::pname:subsetAllocation is
2795ename:VK_TRUE, then memory is only consumed for the devices in the device
2796mask.
2797
2798[NOTE]
2799.Note
2800====
2801In practice, most allocations on a multi-instance heap will be allocated
2802across all physical devices.
2803Unicast allocation support is an optional optimization for a minority of
2804allocations.
2805====
2806
2807.Valid Usage
2808****
2809  * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00675]]
2810    If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask
2811    must: be a valid device mask
2812  * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00676]]
2813    If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask
2814    must: not be zero
2815****
2816
2817include::{generated}/validity/structs/VkMemoryAllocateFlagsInfo.txt[]
2818--
2819
2820[open,refpage='VkMemoryAllocateFlagBits',desc='Bitmask specifying flags for a device memory allocation',type='enums']
2821--
2822Bits which can: be set in slink:VkMemoryAllocateFlagsInfo::pname:flags,
2823controlling device memory allocation, are:
2824
2825include::{generated}/api/enums/VkMemoryAllocateFlagBits.txt[]
2826
2827ifdef::VK_KHR_device_group[]
2828or the equivalent
2829
2830include::{generated}/api/enums/VkMemoryAllocateFlagBitsKHR.txt[]
2831endif::VK_KHR_device_group[]
2832
2833  * ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT specifies that memory will be
2834    allocated for the devices in
2835    slink:VkMemoryAllocateFlagsInfo::pname:deviceMask.
2836ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
2837  * ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT specifies that the memory
2838    can: be attached to a buffer object created with the
2839    ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT bit set in pname:usage,
2840    and that the memory handle can: be used to retrieve an opaque address
2841    via flink:vkGetDeviceMemoryOpaqueCaptureAddress.
2842  * ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies
2843    that the memory's address can: be saved and reused on a subsequent run
2844    (e.g. for trace capture and replay), see
2845    slink:VkBufferOpaqueCaptureAddressCreateInfo for more detail.
2846endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
2847--
2848
2849[open,refpage='VkMemoryAllocateFlags',desc='Bitmask of VkMemoryAllocateFlagBits',type='flags']
2850--
2851include::{generated}/api/flags/VkMemoryAllocateFlags.txt[]
2852
2853ifdef::VK_KHR_device_group[]
2854or the equivalent
2855
2856include::{generated}/api/flags/VkMemoryAllocateFlagsKHR.txt[]
2857endif::VK_KHR_device_group[]
2858
2859tname:VkMemoryAllocateFlags is a bitmask type for setting a mask of zero or
2860more elink:VkMemoryAllocateFlagBits.
2861--
2862endif::VK_VERSION_1_1,VK_KHR_device_group[]
2863
2864
2865ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
2866=== Opaque Capture Address Allocation
2867
2868[open,refpage='VkMemoryOpaqueCaptureAddressAllocateInfo',desc='Request a specific address for a memory allocation',type='structs',alias='VkMemoryOpaqueCaptureAddressAllocateInfoKHR']
2869--
2870To request a specific device address for a memory allocation, add a
2871slink:VkMemoryOpaqueCaptureAddressAllocateInfo structure to the pname:pNext
2872chain of the slink:VkMemoryAllocateInfo structure.
2873The sname:VkMemoryOpaqueCaptureAddressAllocateInfo structure is defined as:
2874
2875include::{generated}/api/structs/VkMemoryOpaqueCaptureAddressAllocateInfo.txt[]
2876
2877ifdef::VK_KHR_buffer_device_address[]
2878or the equivalent
2879
2880include::{generated}/api/structs/VkMemoryOpaqueCaptureAddressAllocateInfoKHR.txt[]
2881endif::VK_KHR_buffer_device_address[]
2882
2883  * pname:sType is the type of this structure.
2884  * pname:pNext is `NULL` or a pointer to a structure extending this
2885    structure.
2886  * pname:opaqueCaptureAddress is the opaque capture address requested for
2887    the memory allocation.
2888
2889If pname:opaqueCaptureAddress is zero, no specific address is requested.
2890
2891If pname:opaqueCaptureAddress is not zero, it should: be an address
2892retrieved from flink:vkGetDeviceMemoryOpaqueCaptureAddress on an identically
2893created memory allocation on the same implementation.
2894
2895[NOTE]
2896.Note
2897====
2898In most cases, it is expected that a non-zero pname:opaqueAddress is an
2899address retrieved from flink:vkGetDeviceMemoryOpaqueCaptureAddress on an
2900identically created memory allocation.
2901If this is not the case, it is likely that
2902ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors will occur.
2903
2904This is, however, not a strict requirement because trace capture/replay
2905tools may need to adjust memory allocation parameters for imported memory.
2906====
2907
2908If this structure is not present, it is as if pname:opaqueCaptureAddress is
2909zero.
2910
2911include::{generated}/validity/structs/VkMemoryOpaqueCaptureAddressAllocateInfo.txt[]
2912--
2913
2914endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
2915
2916
2917=== Freeing Device Memory
2918
2919[open,refpage='vkFreeMemory',desc='Free device memory',type='protos']
2920--
2921To free a memory object, call:
2922
2923include::{generated}/api/protos/vkFreeMemory.txt[]
2924
2925  * pname:device is the logical device that owns the memory.
2926  * pname:memory is the slink:VkDeviceMemory object to be freed.
2927  * pname:pAllocator controls host memory allocation as described in the
2928    <<memory-allocation, Memory Allocation>> chapter.
2929
2930Before freeing a memory object, an application must: ensure the memory
2931object is no longer in use by the device -- for example by command buffers
2932in the _pending state_.
2933Memory can: be freed whilst still bound to resources, but those resources
2934must: not be used afterwards.
2935Freeing a memory object releases the reference it held, if any, to its
2936payload.
2937If there are still any bound images or buffers, the memory object's payload
2938may: not be immediately released by the implementation, but must: be
2939released by the time all bound images and buffers have been destroyed.
2940Once all references to a payload are released, it is returned to the heap
2941from which it was allocated.
2942
2943How memory objects are bound to Images and Buffers is described in detail in
2944the <<resources-association, Resource Memory Association>> section.
2945
2946If a memory object is mapped at the time it is freed, it is implicitly
2947unmapped.
2948
2949[NOTE]
2950.Note
2951====
2952As described <<memory-device-unmap-does-not-flush, below>>, host writes are
2953not implicitly flushed when the memory object is unmapped, but the
2954implementation must: guarantee that writes that have not been flushed do not
2955affect any other memory.
2956====
2957
2958.Valid Usage
2959****
2960  * [[VUID-vkFreeMemory-memory-00677]]
2961    All submitted commands that refer to pname:memory (via images or
2962    buffers) must: have completed execution
2963****
2964
2965include::{generated}/validity/protos/vkFreeMemory.txt[]
2966--
2967
2968
2969[[memory-device-hostaccess]]
2970=== Host Access to Device Memory Objects
2971
2972Memory objects created with flink:vkAllocateMemory are not directly host
2973accessible.
2974
2975Memory objects created with the memory property
2976ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered _mappable_.
2977Memory objects must: be mappable in order to be successfully mapped on the
2978host.
2979
2980[open,refpage='vkMapMemory',desc='Map a memory object into application address space',type='protos']
2981--
2982To retrieve a host virtual address pointer to a region of a mappable memory
2983object, call:
2984
2985include::{generated}/api/protos/vkMapMemory.txt[]
2986
2987  * pname:device is the logical device that owns the memory.
2988  * pname:memory is the slink:VkDeviceMemory object to be mapped.
2989  * pname:offset is a zero-based byte offset from the beginning of the
2990    memory object.
2991  * pname:size is the size of the memory range to map, or
2992    ename:VK_WHOLE_SIZE to map from pname:offset to the end of the
2993    allocation.
2994  * pname:flags is reserved for future use.
2995  * pname:ppData is a pointer to a `void *` variable in which is returned a
2996    host-accessible pointer to the beginning of the mapped range.
2997    This pointer minus pname:offset must: be aligned to at least
2998    slink:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment.
2999
3000After a successful call to fname:vkMapMemory the memory object pname:memory
3001is considered to be currently _host mapped_.
3002
3003[NOTE]
3004.Note
3005====
3006It is an application error to call fname:vkMapMemory on a memory object that
3007is already _host mapped_.
3008====
3009
3010[NOTE]
3011.Note
3012====
3013fname:vkMapMemory will fail if the implementation is unable to allocate an
3014appropriately sized contiguous virtual address range, e.g. due to virtual
3015address space fragmentation or platform limits.
3016In such cases, fname:vkMapMemory must: return
3017ename:VK_ERROR_MEMORY_MAP_FAILED.
3018The application can: improve the likelihood of success by reducing the size
3019of the mapped range and/or removing unneeded mappings using
3020flink:vkUnmapMemory.
3021====
3022
3023[[memory-device-hostaccess-hazards]]
3024fname:vkMapMemory does not check whether the device memory is currently in
3025use before returning the host-accessible pointer.
3026The application must: guarantee that any previously submitted command that
3027writes to this range has completed before the host reads from or writes to
3028that range, and that any previously submitted command that reads from that
3029range has completed before the host writes to that region (see
3030<<synchronization-submission-host-writes, here>> for details on fulfilling
3031such a guarantee).
3032If the device memory was allocated without the
3033ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must: be
3034made for an extended range: the application must: round down the start of
3035the range to the nearest multiple of
3036slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, and round the end
3037of the range up to the nearest multiple of
3038slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize.
3039
3040While a range of device memory is host mapped, the application is
3041responsible for synchronizing both device and host access to that memory
3042range.
3043
3044[NOTE]
3045.Note
3046====
3047It is important for the application developer to become meticulously
3048familiar with all of the mechanisms described in the chapter on
3049<<synchronization, Synchronization and Cache Control>> as they are crucial
3050to maintaining memory access ordering.
3051====
3052
3053.Valid Usage
3054****
3055  * [[VUID-vkMapMemory-memory-00678]]
3056    pname:memory must: not be currently host mapped
3057  * [[VUID-vkMapMemory-offset-00679]]
3058    pname:offset must: be less than the size of pname:memory
3059  * [[VUID-vkMapMemory-size-00680]]
3060    If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
3061    greater than `0`
3062  * [[VUID-vkMapMemory-size-00681]]
3063    If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be
3064    less than or equal to the size of the pname:memory minus pname:offset
3065  * [[VUID-vkMapMemory-memory-00682]]
3066    pname:memory must: have been created with a memory type that reports
3067    ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
3068ifdef::VK_KHR_device_group[]
3069  * [[VUID-vkMapMemory-memory-00683]]
3070    pname:memory must: not have been allocated with multiple instances
3071endif::VK_KHR_device_group[]
3072****
3073
3074include::{generated}/validity/protos/vkMapMemory.txt[]
3075--
3076
3077[open,refpage='VkMemoryMapFlags',desc='Reserved for future use',type='flags']
3078--
3079include::{generated}/api/flags/VkMemoryMapFlags.txt[]
3080
3081tname:VkMemoryMapFlags is a bitmask type for setting a mask, but is
3082currently reserved for future use.
3083--
3084
3085Two commands are provided to enable applications to work with non-coherent
3086memory allocations: fname:vkFlushMappedMemoryRanges and
3087fname:vkInvalidateMappedMemoryRanges.
3088
3089[NOTE]
3090.Note
3091====
3092If the memory object was created with the
3093ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set,
3094fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are
3095unnecessary and may: have a performance cost.
3096However, <<synchronization-dependencies-available-and-visible, availability
3097and visibility operations>> still need to be managed on the device.
3098See the description of <<synchronization-host-access-types, host access
3099types>> for more information.
3100====
3101
3102ifdef::VK_EXT_external_memory_host[]
3103[NOTE]
3104.Note
3105====
3106While memory objects imported from a handle type of
3107ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or
3108ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT are
3109inherently mapped to host address space, they are not considered to be host
3110mapped device memory unless they are explicitly host mapped using
3111flink:vkMapMemory.
3112That means flushing or invalidating host caches with respect to host
3113accesses performed on such memory through the original host pointer
3114specified at import time is the responsibility of the application and must:
3115be performed with appropriate synchronization primitives provided by the
3116platform which are outside the scope of Vulkan.
3117fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges,
3118however, can: still be used on such memory objects to synchronize host
3119accesses performed through the host pointer of the host mapped device memory
3120range returned by flink:vkMapMemory.
3121====
3122endif::VK_EXT_external_memory_host[]
3123
3124[open,refpage='vkFlushMappedMemoryRanges',desc='Flush mapped memory ranges',type='protos']
3125--
3126To flush ranges of non-coherent memory from the host caches, call:
3127
3128include::{generated}/api/protos/vkFlushMappedMemoryRanges.txt[]
3129
3130  * pname:device is the logical device that owns the memory ranges.
3131  * pname:memoryRangeCount is the length of the pname:pMemoryRanges array.
3132  * pname:pMemoryRanges is a pointer to an array of
3133    slink:VkMappedMemoryRange structures describing the memory ranges to
3134    flush.
3135
3136fname:vkFlushMappedMemoryRanges guarantees that host writes to the memory
3137ranges described by pname:pMemoryRanges are made available to the host
3138memory domain, such that they can: be made available to the device memory
3139domain via <<synchronization-dependencies-available-and-visible, memory
3140domain operations>> using the ename:VK_ACCESS_HOST_WRITE_BIT
3141<<synchronization-access-types,access type>>.
3142
3143Within each range described by pname:pMemoryRanges, each set of
3144pname:nonCoherentAtomSize bytes in that range is flushed if any byte in that
3145set has been written by the host since it was first host mapped, or the last
3146time it was flushed.
3147If pname:pMemoryRanges includes sets of pname:nonCoherentAtomSize bytes
3148where no bytes have been written by the host, those bytes must: not be
3149flushed.
3150
3151[[memory-device-unmap-does-not-flush]]
3152Unmapping non-coherent memory does not implicitly flush the host mapped
3153memory, and host writes that have not been flushed may: not ever be visible
3154to the device.
3155However, implementations must: ensure that writes that have not been flushed
3156do not become visible to any other memory.
3157
3158[NOTE]
3159.Note
3160====
3161The above guarantee avoids a potential memory corruption in scenarios where
3162host writes to a mapped memory object have not been flushed before the
3163memory is unmapped (or freed), and the virtual address range is subsequently
3164reused for a different mapping (or memory allocation).
3165====
3166
3167include::{generated}/validity/protos/vkFlushMappedMemoryRanges.txt[]
3168--
3169
3170[open,refpage='vkInvalidateMappedMemoryRanges',desc='Invalidate ranges of mapped memory objects',type='protos']
3171--
3172To invalidate ranges of non-coherent memory from the host caches, call:
3173
3174include::{generated}/api/protos/vkInvalidateMappedMemoryRanges.txt[]
3175
3176  * pname:device is the logical device that owns the memory ranges.
3177  * pname:memoryRangeCount is the length of the pname:pMemoryRanges array.
3178  * pname:pMemoryRanges is a pointer to an array of
3179    slink:VkMappedMemoryRange structures describing the memory ranges to
3180    invalidate.
3181
3182fname:vkInvalidateMappedMemoryRanges guarantees that device writes to the
3183memory ranges described by pname:pMemoryRanges, which have been made
3184available to the host memory domain using the ename:VK_ACCESS_HOST_WRITE_BIT
3185and ename:VK_ACCESS_HOST_READ_BIT <<synchronization-access-types, access
3186types>>, are made visible to the host.
3187If a range of non-coherent memory is written by the host and then
3188invalidated without first being flushed, its contents are undefined:.
3189
3190Within each range described by pname:pMemoryRanges, each set of
3191pname:nonCoherentAtomSize bytes in that range is invalidated if any byte in
3192that set has been written by the device since it was first host mapped, or
3193the last time it was invalidated.
3194
3195[NOTE]
3196.Note
3197====
3198Mapping non-coherent memory does not implicitly invalidate that memory.
3199====
3200
3201include::{generated}/validity/protos/vkInvalidateMappedMemoryRanges.txt[]
3202--
3203
3204[open,refpage='VkMappedMemoryRange',desc='Structure specifying a mapped memory range',type='structs']
3205--
3206The sname:VkMappedMemoryRange structure is defined as:
3207
3208include::{generated}/api/structs/VkMappedMemoryRange.txt[]
3209
3210  * pname:sType is the type of this structure.
3211  * pname:pNext is `NULL` or a pointer to a structure extending this
3212    structure.
3213  * pname:memory is the memory object to which this range belongs.
3214  * pname:offset is the zero-based byte offset from the beginning of the
3215    memory object.
3216  * pname:size is either the size of range, or ename:VK_WHOLE_SIZE to affect
3217    the range from pname:offset to the end of the current mapping of the
3218    allocation.
3219
3220.Valid Usage
3221****
3222  * [[VUID-VkMappedMemoryRange-memory-00684]]
3223    pname:memory must: be currently host mapped
3224  * [[VUID-VkMappedMemoryRange-size-00685]]
3225    If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:offset and
3226    pname:size must: specify a range contained within the currently mapped
3227    range of pname:memory
3228  * [[VUID-VkMappedMemoryRange-size-00686]]
3229    If pname:size is equal to ename:VK_WHOLE_SIZE, pname:offset must: be
3230    within the currently mapped range of pname:memory
3231  * [[VUID-VkMappedMemoryRange-offset-00687]]
3232    pname:offset must: be a multiple of
3233    slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize
3234  * [[VUID-VkMappedMemoryRange-size-01389]]
3235    If pname:size is equal to ename:VK_WHOLE_SIZE, the end of the current
3236    mapping of pname:memory must: either be a multiple of
3237    slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize bytes from the
3238    beginning of the memory object, or be equal to the end of the memory
3239    object
3240  * [[VUID-VkMappedMemoryRange-size-01390]]
3241    If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must:
3242    either be a multiple of
3243    slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, or pname:offset
3244    plus pname:size must: equal the size of pname:memory
3245****
3246
3247include::{generated}/validity/structs/VkMappedMemoryRange.txt[]
3248--
3249
3250
3251[open,refpage='vkUnmapMemory',desc='Unmap a previously mapped memory object',type='protos']
3252--
3253To unmap a memory object once host access to it is no longer needed by the
3254application, call:
3255
3256include::{generated}/api/protos/vkUnmapMemory.txt[]
3257
3258  * pname:device is the logical device that owns the memory.
3259  * pname:memory is the memory object to be unmapped.
3260
3261.Valid Usage
3262****
3263  * [[VUID-vkUnmapMemory-memory-00689]]
3264    pname:memory must: be currently host mapped
3265****
3266
3267include::{generated}/validity/protos/vkUnmapMemory.txt[]
3268--
3269
3270
3271[[memory-device-lazy_allocation]]
3272=== Lazily Allocated Memory
3273
3274If the memory object is allocated from a heap with the
3275ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, that object's backing
3276memory may: be provided by the implementation lazily.
3277The actual committed size of the memory may: initially be as small as zero
3278(or as large as the requested size), and monotonically increases as
3279additional memory is needed.
3280
3281A memory type with this flag set is only allowed to be bound to a
3282sname:VkImage whose usage flags include
3283ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT.
3284
3285[NOTE]
3286.Note
3287====
3288Using lazily allocated memory objects for framebuffer attachments that are
3289not needed once a render pass instance has completed may: allow some
3290implementations to never allocate memory for such attachments.
3291====
3292
3293[open,refpage='vkGetDeviceMemoryCommitment',desc='Query the current commitment for a VkDeviceMemory',type='protos']
3294--
3295To determine the amount of lazily-allocated memory that is currently
3296committed for a memory object, call:
3297
3298include::{generated}/api/protos/vkGetDeviceMemoryCommitment.txt[]
3299
3300  * pname:device is the logical device that owns the memory.
3301  * pname:memory is the memory object being queried.
3302  * pname:pCommittedMemoryInBytes is a pointer to a basetype:VkDeviceSize
3303    value in which the number of bytes currently committed is returned, on
3304    success.
3305
3306The implementation may: update the commitment at any time, and the value
3307returned by this query may: be out of date.
3308
3309The implementation guarantees to allocate any committed memory from the
3310pname:heapIndex indicated by the memory type that the memory object was
3311created with.
3312
3313.Valid Usage
3314****
3315  * [[VUID-vkGetDeviceMemoryCommitment-memory-00690]]
3316    pname:memory must: have been created with a memory type that reports
3317    ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
3318****
3319
3320include::{generated}/validity/protos/vkGetDeviceMemoryCommitment.txt[]
3321--
3322
3323
3324ifdef::VK_VERSION_1_1[]
3325[[memory-protected-memory]]
3326=== Protected Memory
3327
3328_Protected memory_ divides device memory into protected device memory and
3329unprotected device memory.
3330
3331Protected memory adds the following concepts:
3332
3333  * Memory:
3334  ** Unprotected device memory, which can: be visible to the device and can:
3335     be visible to the host
3336  ** Protected device memory, which can: be visible to the device but must:
3337     not be visible to the host
3338  * Resources:
3339  ** Unprotected images and unprotected buffers, to which unprotected memory
3340     can: be bound
3341  ** Protected images and protected buffers, to which protected memory can:
3342     be bound
3343  * Command buffers:
3344  ** Unprotected command buffers, which can: be submitted to a device queue
3345     to execute unprotected queue operations
3346  ** Protected command buffers, which can: be submitted to a
3347     protected-capable device queue to execute protected queue operations
3348  * Device queues:
3349  ** Unprotected device queues, to which unprotected command buffers can: be
3350     submitted
3351  ** Protected-capable device queues, to which unprotected command buffers
3352     or protected command buffers can: be submitted
3353  * Queue submissions
3354  ** Unprotected queue submissions, through which unprotected command
3355     buffers can: be submitted
3356  ** Protected queue submissions, through which protected command buffers
3357     can: be submitted
3358  * Queue operations
3359  ** Unprotected queue operations
3360  ** Protected queue operations
3361
3362[[memory-protected-access-rules]]
3363==== Protected Memory Access Rules
3364
3365If slink:VkPhysicalDeviceProtectedMemoryProperties::pname:protectedNoFault
3366is ename:VK_FALSE, applications must: not perform any of the following
3367operations:
3368
3369  * Write to unprotected memory within protected queue operations.
3370  * Access protected memory within protected queue operations other than in
3371    framebuffer-space pipeline stages, the compute shader stage, or the
3372    transfer stage.
3373  * Perform a query within protected queue operations.
3374
3375If slink:VkPhysicalDeviceProtectedMemoryProperties::pname:protectedNoFault
3376is ename:VK_TRUE, these operations are valid, but reads will return
3377undefined: values, and writes will either be dropped or store undefined:
3378values.
3379
3380Additionally, indirect operations must: not be performed within protected
3381queue operations.
3382
3383Whether these operations are valid or not, or if any other invalid usage is
3384performed, the implementation must: guarantee that:
3385
3386  * Protected device memory must: never be visible to the host.
3387  * Values written to unprotected device memory must: not be a function of
3388    values from protected memory.
3389endif::VK_VERSION_1_1[]
3390
3391
3392ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[]
3393[[memory-external-handle-types]]
3394=== External Memory Handle Types
3395
3396
3397[[memory-external-android-hardware-buffer]]
3398==== Android Hardware Buffer
3399
3400Android's NDK defines basetype:AHardwareBuffer objects, which represent
3401device memory that is shareable across processes and that can: be accessed
3402by a variety of media APIs and the hardware used to implement them.
3403These Android hardware buffer objects may: be imported into
3404slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan.
3405An slink:VkImage or slink:VkBuffer can: be bound to the imported or exported
3406slink:VkDeviceMemory object if it is created with
3407ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
3408
3409[open,refpage='AHardwareBuffer',desc='Android hardware buffer type',type='basetypes']
3410--
3411To remove an unnecessary compile-time dependency, an incomplete type
3412definition of basetype:AHardwareBuffer is provided in the Vulkan headers:
3413
3414include::{generated}/api/basetypes/AHardwareBuffer.txt[]
3415
3416The actual basetype:AHardwareBuffer type is defined in Android NDK headers.
3417--
3418
3419[NOTE]
3420.Note
3421====
3422The NDK format, usage, and size/dimensions of an basetype:AHardwareBuffer
3423object can be obtained with the code:AHardwareBuffer_describe function.
3424While Android hardware buffers can be imported to or exported from Vulkan
3425without using that function, valid usage and implementation behavior is
3426defined in terms of the code:AHardwareBuffer_Desc properties it returns.
3427====
3428
3429Android hardware buffer objects are reference-counted using Android NDK
3430functions outside of the scope of this specification.
3431A slink:VkDeviceMemory imported from an Android hardware buffer or that can:
3432be exported to an Android hardware buffer must: acquire a reference to its
3433basetype:AHardwareBuffer object, and must: release this reference when the
3434device memory is freed.
3435During the host execution of a Vulkan command that has an Android hardware
3436buffer as a parameter (including indirect parameters via pname:pNext
3437chains), the application must: not decrement the Android hardware buffer's
3438reference count to zero.
3439
3440Android hardware buffers can: be mapped and unmapped for CPU access using
3441the NDK functions.
3442These lock and unlock APIs are considered to acquire and release ownership
3443of the Android hardware buffer, and applications must: follow the rules
3444described in <<resources-external-sharing,External Resource Sharing>> to
3445transfer ownership between the Vulkan instance and these native APIs.
3446
3447Android hardware buffers can: be shared with external APIs and Vulkan
3448instances on the same device, and also with foreign devices.
3449When transferring ownership of the Android hardware buffer, the external and
3450foreign special queue families described in
3451<<synchronization-queue-transfers>> are not identical.
3452All APIs which produce or consume Android hardware buffers are considered to
3453use foreign devices, except OpenGL ES contexts and Vulkan logical devices
3454that have matching device and driver UUIDs.
3455Implementations may: treat a transfer to or from the foreign queue family as
3456if it were a transfer to or from the external queue family when the Android
3457hardware buffer's usage only permits it to be used on the same physical
3458device.
3459
3460
3461[[memory-external-android-hardware-buffer-optimal-usages]]
3462===== Android Hardware Buffer Optimal Usages =====
3463
3464Vulkan buffer and image usage flags do not correspond exactly to Android
3465hardware buffer usage flags.
3466When allocating Android hardware buffers with non-Vulkan APIs, if any
3467code:AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the
3468allocator must: allocate the memory in such a way that it supports Vulkan
3469usages and creation flags in the
3470<<memory-external-android-hardware-buffer-usage, usage equivalence table>>
3471which do not have Android hardware buffer equivalents.
3472
3473An slink:VkAndroidHardwareBufferUsageANDROID structure can: be included in
3474the pname:pNext chain of a slink:VkImageFormatProperties2 structure passed
3475to flink:vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android
3476hardware buffer usage flags for specific Vulkan resource creation
3477parameters.
3478Some usage flags returned by these commands are required: based on the input
3479parameters, but additional vendor-specific usage flags
3480(code:AHARDWAREBUFFER_USAGE_VENDOR_*) may: also be returned.
3481Any Android hardware buffer allocated with these vendor-specific usage flags
3482and imported to Vulkan must: only be bound to resources created with
3483parameters that are a subset of the parameters used to obtain the Android
3484hardware buffer usage, since the memory may: have been allocated in a way
3485incompatible with other parameters.
3486If an Android hardware buffer is successfully allocated with additional
3487non-vendor-specific usage flags in addition to the recommended usage, it
3488must: support being used in the same ways as an Android hardware buffer
3489allocated with only the recommended usage, and also in ways indicated by the
3490additional usage.
3491
3492[[memory-external-android-hardware-buffer-external-formats]]
3493===== Android Hardware Buffer External Formats =====
3494
3495Android hardware buffers may: represent images using implementation-specific
3496formats, layouts, color models, etc., which do not have Vulkan equivalents.
3497Such _external formats_ are commonly used by external image sources such as
3498video decoders or cameras.
3499Vulkan can: import Android hardware buffers that have external formats, but
3500since the image contents are in an undiscoverable and possibly proprietary
3501representation, images with external formats must: only be used as sampled
3502images, must: only be sampled with a sampler that has {YCbCr} conversion
3503enabled, and must: have optimal tiling.
3504
3505Images that will be backed by an Android hardware buffer can: use an
3506external format by setting slink:VkImageCreateInfo::pname:format to
3507ename:VK_FORMAT_UNDEFINED and including a slink:VkExternalFormatANDROID
3508structure in the pname:pNext chain.
3509Images can: be created with an external format even if the Android hardware
3510buffer has a format which has an
3511<<memory-external-android-hardware-buffer-formats,equivalent Vulkan format>>
3512to enable consistent handling of images from sources that might use either
3513category of format.
3514However, all images created with an external format are subject to the valid
3515usage requirements associated with external formats, even if the Android
3516hardware buffer's format has a Vulkan equivalent.
3517The external format of an Android hardware buffer can: be obtained by
3518passing a slink:VkAndroidHardwareBufferFormatPropertiesANDROID structure to
3519flink:vkGetAndroidHardwareBufferPropertiesANDROID.
3520
3521[[memory-external-android-hardware-buffer-image-resources]]
3522===== Android Hardware Buffer Image Resources
3523
3524Android hardware buffers have intrinsic width, height, format, and usage
3525properties, so Vulkan images bound to memory imported from an Android
3526hardware buffer must: use dedicated allocations:
3527sname:VkMemoryDedicatedRequirements::pname:requiresDedicatedAllocation must:
3528be ename:VK_TRUE for images created with
3529slink:VkExternalMemoryImageCreateInfo::pname:handleTypes that includes
3530ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
3531When creating an image that will be bound to an imported Android hardware
3532buffer, the image creation parameters must: be equivalent to the
3533basetype:AHardwareBuffer properties as described by the valid usage of
3534slink:VkMemoryAllocateInfo.
3535Similarly, device memory allocated for a dedicated image must: not be
3536exported to an Android hardware buffer until it has been bound to that
3537image, and the implementation must: return an Android hardware buffer with
3538properties derived from the image:
3539
3540  * The code:width and code:height members of code:AHardwareBuffer_Desc
3541    must: be the same as the pname:width and pname:height members of
3542    slink:VkImageCreateInfo::pname:extent, respectively.
3543  * The code:layers member of code:AHardwareBuffer_Desc must: be the same as
3544    the pname:arrayLayers member of slink:VkImageCreateInfo.
3545  * The code:format member of code:AHardwareBuffer_Desc must: be equivalent
3546    to slink:VkImageCreateInfo::pname:format as defined by
3547    <<memory-external-android-hardware-buffer-formats,AHardwareBuffer Format
3548    Equivalence>>.
3549  * The code:usage member of code:AHardwareBuffer_Desc must: include bits
3550    corresponding to bits included in slink:VkImageCreateInfo::pname:usage
3551    and slink:VkImageCreateInfo::pname:flags where such a correspondence
3552    exists according to
3553    <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage
3554    Equivalence>>.
3555    It may: also include additional usage bits, including vendor-specific
3556    usages.
3557    Presence of vendor usage bits may: make the Android hardware buffer only
3558    usable in ways indicated by the image creation parameters, even when
3559    used outside Vulkan, in a similar way that allocating the Android
3560    hardware buffer with usage returned in
3561    slink:VkAndroidHardwareBufferUsageANDROID does.
3562
3563Implementations may: support fewer combinations of image creation parameters
3564for images with Android hardware buffer external handle type than for
3565non-external images.
3566Support for a given set of parameters can: be determined by passing
3567slink:VkExternalImageFormatProperties to
3568flink:vkGetPhysicalDeviceImageFormatProperties2 with pname:handleType set to
3569ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
3570Any Android hardware buffer successfully allocated outside Vulkan with usage
3571that includes code:AHARDWAREBUFFER_USAGE_GPU_* must: be supported when using
3572equivalent Vulkan image parameters.
3573If a given choice of image parameters are supported for import, they can:
3574also be used to create an image and memory that will be exported to an
3575Android hardware buffer.
3576
3577[[memory-external-android-hardware-buffer-formats]]
3578.AHardwareBuffer Format Equivalence
3579[width="100%",options="header"]
3580|====
3581| AHardwareBuffer Format                         | Vulkan Format
3582| code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM     | ename:VK_FORMAT_R8G8B8A8_UNORM
3583| code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM ^1^ | ename:VK_FORMAT_R8G8B8A8_UNORM
3584| code:AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM       | ename:VK_FORMAT_R8G8B8_UNORM
3585| code:AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM       | ename:VK_FORMAT_R5G6B5_UNORM_PACK16
3586| code:AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT | ename:VK_FORMAT_R16G16B16A16_SFLOAT
3587| code:AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM  | ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32
3588| code:AHARDWAREBUFFER_FORMAT_D16_UNORM          | ename:VK_FORMAT_D16_UNORM
3589| code:AHARDWAREBUFFER_FORMAT_D24_UNORM          | ename:VK_FORMAT_X8_D24_UNORM_PACK32
3590| code:AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT  | ename:VK_FORMAT_D24_UNORM_S8_UINT
3591| code:AHARDWAREBUFFER_FORMAT_D32_FLOAT          | ename:VK_FORMAT_D32_SFLOAT
3592| code:AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT  | ename:VK_FORMAT_D32_SFLOAT_S8_UINT
3593| code:AHARDWAREBUFFER_FORMAT_S8_UINT            | ename:VK_FORMAT_S8_UINT
3594|====
3595
3596[[memory-external-android-hardware-buffer-usage]]
3597.AHardwareBuffer Usage Equivalence
3598[width="100%",options="header"]
3599|====
3600| AHardwareBuffer Usage                          | Vulkan Usage or Creation Flag
3601| None                                           | ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT
3602| None                                           | ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT
3603| code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE   | ename:VK_IMAGE_USAGE_SAMPLED_BIT
3604| code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE   | ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
3605| code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER ^3^ | ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
3606| code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER ^3^ | ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
3607| code:AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP        | ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT
3608| code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE | None ^2^
3609ifdef::VK_VERSION_1_1[]
3610| code:AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT   | ename:VK_IMAGE_CREATE_PROTECTED_BIT
3611endif::VK_VERSION_1_1[]
3612| None                                           | ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
3613| None                                           | ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT
3614|====
3615
36161::
3617    Vulkan does not differentiate between
3618    code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM and
3619    code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM: they both behave as
3620    ename:VK_FORMAT_R8G8B8A8_UNORM.
3621    After an external entity writes to a
3622    code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM Android hardware buffer, the
3623    values read by Vulkan from the X/A component are undefined:.
3624    To emulate the traditional behavior of the X component during sampling
3625    or blending, applications should: use ename:VK_COMPONENT_SWIZZLE_ONE in
3626    image view component mappings and ename:VK_BLEND_FACTOR_ONE in color
3627    blend factors.
3628    There is no way to avoid copying these undefined: values when copying
3629    from such an image to another image or buffer.
3630
36312::
3632    The code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE flag does not
3633    correspond to a Vulkan image usage or creation flag.
3634    Instead, its presence indicates that the Android hardware buffer
3635    contains a complete mipmap chain, and its absence indicates that the
3636    Android hardware buffer contains only a single mip level.
3637
36383::
3639    Only image usages valid for the format are valid.
3640    It would be invalid to take a Android Hardware Buffer with a format of
3641    code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM that has a
3642    code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER usage and try to create an
3643    image with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT.
3644
3645ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[]
3646[NOTE]
3647.Note
3648====
3649When using ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT with Android hardware
3650buffer images, applications should: use slink:VkImageFormatListCreateInfo to
3651inform the implementation which view formats will be used with the image.
3652For some common sets of format, this allows some implementations to provide
3653significantly better performance when accessing the image via Vulkan.
3654====
3655endif::VK_VERSION_1_2,VK_KHR_image_format_list[]
3656
3657[[memory-external-android-hardware-buffer-buffer-resources]]
3658===== Android Hardware Buffer Buffer Resources
3659
3660Android hardware buffers with a format of code:AHARDWAREBUFFER_FORMAT_BLOB
3661and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can: be
3662used as the backing store for slink:VkBuffer objects.
3663Such Android hardware buffers have a size in bytes specified by their
3664code:width; code:height and code:layers are both `1`.
3665
3666Unlike images, buffer resources backed by Android hardware buffers do not
3667require dedicated allocations.
3668
3669Exported basetype:AHardwareBuffer objects that do not have dedicated images
3670must: have a format of code:AHARDWAREBUFFER_FORMAT_BLOB, usage must: include
3671code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, code:width must: equal the
3672device memory allocation size, and code:height and code:layers must: be `1`.
3673endif::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[]
3674
3675
3676ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
3677[[memory-peer-memory-features]]
3678=== Peer Memory Features
3679
3680[open,refpage='vkGetDeviceGroupPeerMemoryFeatures',desc='Query supported peer memory features of a device',type='protos']
3681--
3682_Peer memory_ is memory that is allocated for a given physical device and
3683then bound to a resource and accessed by a different physical device, in a
3684logical device that represents multiple physical devices.
3685Some ways of reading and writing peer memory may: not be supported by a
3686device.
3687
3688To determine how peer memory can: be accessed, call:
3689
3690ifdef::VK_VERSION_1_1[]
3691include::{generated}/api/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[]
3692endif::VK_VERSION_1_1[]
3693
3694ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command]
3695
3696ifdef::VK_KHR_device_group[]
3697include::{generated}/api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHR.txt[]
3698endif::VK_KHR_device_group[]
3699
3700  * pname:device is the logical device that owns the memory.
3701  * pname:heapIndex is the index of the memory heap from which the memory is
3702    allocated.
3703  * pname:localDeviceIndex is the device index of the physical device that
3704    performs the memory access.
3705  * pname:remoteDeviceIndex is the device index of the physical device that
3706    the memory is allocated for.
3707  * pname:pPeerMemoryFeatures is a pointer to a
3708    tlink:VkPeerMemoryFeatureFlags bitmask indicating which types of memory
3709    accesses are supported for the combination of heap, local, and remote
3710    devices.
3711
3712.Valid Usage
3713****
3714  * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-heapIndex-00691]]
3715    pname:heapIndex must: be less than pname:memoryHeapCount
3716  * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00692]]
3717    pname:localDeviceIndex must: be a valid device index
3718  * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-remoteDeviceIndex-00693]]
3719    pname:remoteDeviceIndex must: be a valid device index
3720  * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00694]]
3721    pname:localDeviceIndex must: not equal pname:remoteDeviceIndex
3722****
3723
3724include::{generated}/validity/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[]
3725--
3726
3727[open,refpage='VkPeerMemoryFeatureFlagBits',desc='Bitmask specifying supported peer memory features',type='enums']
3728--
3729Bits which may: be set in the value returned for
3730flink:vkGetDeviceGroupPeerMemoryFeatures::pname:pPeerMemoryFeatures,
3731indicating the supported peer memory features, are:
3732
3733include::{generated}/api/enums/VkPeerMemoryFeatureFlagBits.txt[]
3734
3735ifdef::VK_KHR_device_group[]
3736or the equivalent
3737
3738include::{generated}/api/enums/VkPeerMemoryFeatureFlagBitsKHR.txt[]
3739endif::VK_KHR_device_group[]
3740
3741  * ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT specifies that the memory can:
3742    be accessed as the source of any ftext:vkCmdCopy* command.
3743  * ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT specifies that the memory can:
3744    be accessed as the destination of any ftext:vkCmdCopy* command.
3745  * ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT specifies that the memory
3746    can: be read as any memory access type.
3747  * ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT specifies that the memory
3748    can: be written as any memory access type.
3749    Shader atomics are considered to be writes.
3750
3751[NOTE]
3752.Note
3753====
3754The peer memory features of a memory heap also apply to any accesses that
3755may: be performed during <<synchronization-image-layout-transitions, image
3756layout transitions>>.
3757====
3758
3759ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must: be supported for all host
3760local heaps and for at least one device-local memory heap.
3761
3762If a device does not support a peer memory feature, it is still valid to use
3763a resource that includes both local and peer memory bindings with the
3764corresponding access type as long as only the local bindings are actually
3765accessed.
3766For example, an application doing split-frame rendering would use
3767framebuffer attachments that include both local and peer memory bindings,
3768but would scissor the rendering to only update local memory.
3769--
3770
3771[open,refpage='VkPeerMemoryFeatureFlags',desc='Bitmask of VkPeerMemoryFeatureFlagBits',type='flags']
3772--
3773include::{generated}/api/flags/VkPeerMemoryFeatureFlags.txt[]
3774
3775ifdef::VK_KHR_device_group[]
3776or the equivalent
3777
3778include::{generated}/api/flags/VkPeerMemoryFeatureFlagsKHR.txt[]
3779endif::VK_KHR_device_group[]
3780
3781tname:VkPeerMemoryFeatureFlags is a bitmask type for setting a mask of zero
3782or more elink:VkPeerMemoryFeatureFlagBits.
3783--
3784endif::VK_VERSION_1_1,VK_KHR_device_group[]
3785
3786ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
3787=== Opaque Capture Address Query
3788
3789[open,refpage='vkGetDeviceMemoryOpaqueCaptureAddress',desc='Query an opaque capture address of a memory object',type='protos',alias='vkGetDeviceMemoryOpaqueCaptureAddressKHR']
3790--
3791To query a 64-bit opaque capture address value from a memory object, call:
3792
3793ifdef::VK_VERSION_1_2[]
3794include::{generated}/api/protos/vkGetDeviceMemoryOpaqueCaptureAddress.txt[]
3795endif::VK_VERSION_1_2[]
3796
3797ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command]
3798
3799ifdef::VK_KHR_buffer_device_address[]
3800include::{generated}/api/protos/vkGetDeviceMemoryOpaqueCaptureAddressKHR.txt[]
3801endif::VK_KHR_buffer_device_address[]
3802
3803  * pname:device is the logical device that the memory object was allocated
3804    on.
3805  * pname:pInfo is a pointer to a
3806    slink:VkDeviceMemoryOpaqueCaptureAddressInfo structure specifying the
3807    memory object to retrieve an address for.
3808
3809The 64-bit return value is an opaque address representing the start of
3810pname:pInfo->memory.
3811
3812If the memory object was allocated with a non-zero value of
3813slink:VkMemoryOpaqueCaptureAddressAllocateInfo::pname:opaqueCaptureAddress,
3814the return value must: be the same address.
3815
3816[NOTE]
3817.Note
3818====
3819The expected usage for these opaque addresses is only for trace
3820capture/replay tools to store these addresses in a trace and subsequently
3821specify them during replay.
3822====
3823
3824.Valid Usage
3825****
3826  * [[VUID-vkGetDeviceMemoryOpaqueCaptureAddress-None-03334]]
3827    The <<features-bufferDeviceAddress,bufferDeviceAddress>> feature must:
3828    be enabled
3829  * [[VUID-vkGetDeviceMemoryOpaqueCaptureAddress-device-03335]]
3830    If pname:device was created with multiple physical devices, then the
3831    <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>>
3832    feature must: be enabled
3833****
3834
3835include::{generated}/validity/protos/vkGetDeviceMemoryOpaqueCaptureAddress.txt[]
3836--
3837
3838[open,refpage='VkDeviceMemoryOpaqueCaptureAddressInfo',desc='Structure specifying the memory object to query an address for',type='structs',alias='VkDeviceMemoryOpaqueCaptureAddressInfoKHR']
3839--
3840The sname:VkDeviceMemoryOpaqueCaptureAddressInfo structure is defined as:
3841
3842include::{generated}/api/structs/VkDeviceMemoryOpaqueCaptureAddressInfo.txt[]
3843
3844ifdef::VK_KHR_buffer_device_address[]
3845or the equivalent
3846
3847include::{generated}/api/structs/VkDeviceMemoryOpaqueCaptureAddressInfoKHR.txt[]
3848endif::VK_KHR_buffer_device_address[]
3849
3850  * pname:sType is the type of this structure.
3851  * pname:pNext is `NULL` or a pointer to a structure extending this
3852    structure.
3853  * pname:memory specifies the memory whose address is being queried.
3854
3855.Valid Usage
3856****
3857  * [[VUID-VkDeviceMemoryOpaqueCaptureAddressInfo-memory-03336]]
3858    pname:memory must: have been allocated with
3859    ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT
3860****
3861
3862include::{generated}/validity/structs/VkDeviceMemoryOpaqueCaptureAddressInfo.txt[]
3863--
3864endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[]
3865