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