1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[memory]] 6= Memory Allocation 7 8Vulkan memory is broken up into two categories, _host memory_ and _device 9memory_. 10 11 12[[memory-host]] 13== Host Memory 14 15Host memory is memory needed by the Vulkan implementation for 16non-device-visible storage. 17 18[NOTE] 19.Note 20==== 21This memory may: be used to store the implementation's representation and 22state of Vulkan objects. 23==== 24 25[[memory-allocation]] 26Vulkan provides applications the opportunity to perform host memory 27allocations on behalf of the Vulkan implementation. 28If this feature is not used, the implementation will perform its own memory 29allocations. 30Since most memory allocations are off the critical path, this is not meant 31as a performance feature. 32Rather, this can: be useful for certain embedded systems, for debugging 33purposes (e.g. putting a guard page after all host allocations), or for 34memory allocation logging. 35 36[open,refpage='VkAllocationCallbacks',desc='Structure containing callback function pointers for memory allocation',type='structs'] 37-- 38 39Allocators are provided by the application as a pointer to a 40sname:VkAllocationCallbacks structure: 41 42include::../api/structs/VkAllocationCallbacks.txt[] 43 44 * pname:pUserData is a value to be interpreted by the implementation of 45 the callbacks. 46 When any of the callbacks in sname:VkAllocationCallbacks are called, the 47 Vulkan implementation will pass this value as the first parameter to the 48 callback. 49 This value can: vary each time an allocator is passed into a command, 50 even when the same object takes an allocator in multiple commands. 51 * pname:pfnAllocation is a pointer to an application-defined memory 52 allocation function of type tlink:PFN_vkAllocationFunction. 53 * pname:pfnReallocation is a pointer to an application-defined memory 54 reallocation function of type tlink:PFN_vkReallocationFunction. 55 * pname:pfnFree is a pointer to an application-defined memory free 56 function of type tlink:PFN_vkFreeFunction. 57 * pname:pfnInternalAllocation is a pointer to an application-defined 58 function that is called by the implementation when the implementation 59 makes internal allocations, and it is of type 60 tlink:PFN_vkInternalAllocationNotification. 61 * pname:pfnInternalFree is a pointer to an application-defined function 62 that is called by the implementation when the implementation frees 63 internal allocations, and it is of type 64 tlink:PFN_vkInternalFreeNotification. 65 66.Valid Usage 67**** 68 * [[VUID-VkAllocationCallbacks-pfnAllocation-00632]] 69 pname:pfnAllocation must: be a valid pointer to a valid user-defined 70 tlink:PFN_vkAllocationFunction 71 * [[VUID-VkAllocationCallbacks-pfnReallocation-00633]] 72 pname:pfnReallocation must: be a valid pointer to a valid user-defined 73 tlink:PFN_vkReallocationFunction 74 * [[VUID-VkAllocationCallbacks-pfnFree-00634]] 75 pname:pfnFree must: be a valid pointer to a valid user-defined 76 tlink:PFN_vkFreeFunction 77 * [[VUID-VkAllocationCallbacks-pfnInternalAllocation-00635]] 78 If either of pname:pfnInternalAllocation or pname:pfnInternalFree is not 79 `NULL`, both must: be valid callbacks 80**** 81 82include::../validity/structs/VkAllocationCallbacks.txt[] 83-- 84 85[open,refpage='PFN_vkAllocationFunction',desc='Application-defined memory allocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] 86-- 87 88The type of pname:pfnAllocation is: 89 90include::../api/funcpointers/PFN_vkAllocationFunction.txt[] 91 92 * pname:pUserData is the value specified for 93 slink:VkAllocationCallbacks::pname:pUserData in the allocator specified 94 by the application. 95 * pname:size is the size in bytes of the requested allocation. 96 * pname:alignment is the requested alignment of the allocation in bytes 97 and must: be a power of two. 98 * pname:allocationScope is a elink:VkSystemAllocationScope value 99 specifying the allocation scope of the lifetime of the allocation, as 100 described <<memory-host-allocation-scope,here>>. 101 102[[vkAllocationFunction_return_rules]] 103If pname:pfnAllocation is unable to allocate the requested memory, it must: 104return `NULL`. 105If the allocation was successful, it must: return a valid pointer to memory 106allocation containing at least pname:size bytes, and with the pointer value 107being a multiple of pname:alignment. 108 109[NOTE] 110.Note 111==== 112Correct Vulkan operation cannot: be assumed if the application does not 113follow these rules. 114 115For example, pname:pfnAllocation (or pname:pfnReallocation) could cause 116termination of running Vulkan instance(s) on a failed allocation for 117debugging purposes, either directly or indirectly. 118In these circumstances, it cannot: be assumed that any part of any affected 119slink:VkInstance objects are going to operate correctly (even 120flink:vkDestroyInstance), and the application must: ensure it cleans up 121properly via other means (e.g. process termination). 122==== 123 124If pname:pfnAllocation returns `NULL`, and if the implementation is unable 125to continue correct processing of the current command without the requested 126allocation, it must: treat this as a run-time error, and generate 127ename:VK_ERROR_OUT_OF_HOST_MEMORY at the appropriate time for the command in 128which the condition was detected, as described in <<fundamentals-errorcodes, 129Return Codes>>. 130 131If the implementation is able to continue correct processing of the current 132command without the requested allocation, then it may: do so, and must: not 133generate ename:VK_ERROR_OUT_OF_HOST_MEMORY as a result of this failed 134allocation. 135 136-- 137 138[open,refpage='PFN_vkReallocationFunction',desc='Application-defined memory reallocation function',type='funcpointers',xrefs='VkAllocationCallbacks'] 139-- 140 141The type of pname:pfnReallocation is: 142 143include::../api/funcpointers/PFN_vkReallocationFunction.txt[] 144 145 * pname:pUserData is the value specified for 146 slink:VkAllocationCallbacks::pname:pUserData in the allocator specified 147 by the application. 148 * pname:pOriginal must: be either `NULL` or a pointer previously returned 149 by pname:pfnReallocation or pname:pfnAllocation of the same allocator. 150 * pname:size is the size in bytes of the requested allocation. 151 * pname:alignment is the requested alignment of the allocation in bytes 152 and must: be a power of two. 153 * pname:allocationScope is a elink:VkSystemAllocationScope value 154 specifying the allocation scope of the lifetime of the allocation, as 155 described <<memory-host-allocation-scope,here>>. 156 157pname:pfnReallocation must: return an allocation with enough space for 158pname:size bytes, and the contents of the original allocation from bytes 159zero to [eq]#min(original size, new size) - 1# must: be preserved in the 160returned allocation. 161If pname:size is larger than the old size, the contents of the additional 162space are undefined. 163If satisfying these requirements involves creating a new allocation, then 164the old allocation should: be freed. 165 166If pname:pOriginal is `NULL`, then pname:pfnReallocation must: behave 167equivalently to a call to tlink:PFN_vkAllocationFunction with the same 168parameter values (without pname:pOriginal). 169 170If pname:size is zero, then pname:pfnReallocation must: behave equivalently 171to a call to tlink:PFN_vkFreeFunction with the same pname:pUserData 172parameter value, and pname:pMemory equal to pname:pOriginal. 173 174If pname:pOriginal is non-`NULL`, the implementation must: ensure that 175pname:alignment is equal to the pname:alignment used to originally allocate 176pname:pOriginal. 177 178If this function fails and pname:pOriginal is non-`NULL` the application 179must: not free the old allocation. 180 181pname:pfnReallocation must: follow the same 182<<vkAllocationFunction_return_rules, rules for return values as 183tname:PFN_vkAllocationFunction>>. 184 185-- 186 187[open,refpage='PFN_vkFreeFunction',desc='Application-defined memory free function',type='funcpointers',xrefs='VkAllocationCallbacks'] 188-- 189 190The type of pname:pfnFree is: 191 192include::../api/funcpointers/PFN_vkFreeFunction.txt[] 193 194 * pname:pUserData is the value specified for 195 slink:VkAllocationCallbacks::pname:pUserData in the allocator specified 196 by the application. 197 * pname:pMemory is the allocation to be freed. 198 199pname:pMemory may: be `NULL`, which the callback must: handle safely. 200If pname:pMemory is non-`NULL`, it must: be a pointer previously allocated 201by pname:pfnAllocation or pname:pfnReallocation. 202The application should: free this memory. 203 204-- 205 206[open,refpage='PFN_vkInternalAllocationNotification',desc='Application-defined memory allocation notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] 207-- 208 209The type of pname:pfnInternalAllocation is: 210 211include::../api/funcpointers/PFN_vkInternalAllocationNotification.txt[] 212 213 * pname:pUserData is the value specified for 214 slink:VkAllocationCallbacks::pname:pUserData in the allocator specified 215 by the application. 216 * pname:size is the requested size of an allocation. 217 * pname:allocationType is a elink:VkInternalAllocationType value 218 specifying the requested type of an allocation. 219 * pname:allocationScope is a elink:VkSystemAllocationScope value 220 specifying the allocation scope of the lifetime of the allocation, as 221 described <<memory-host-allocation-scope,here>>. 222 223This is a purely informational callback. 224 225-- 226 227[open,refpage='PFN_vkInternalFreeNotification',desc='Application-defined memory free notification function',type='funcpointers',xrefs='VkAllocationCallbacks'] 228-- 229 230The type of pname:pfnInternalFree is: 231 232include::../api/funcpointers/PFN_vkInternalFreeNotification.txt[] 233 234 * pname:pUserData is the value specified for 235 slink:VkAllocationCallbacks::pname:pUserData in the allocator specified 236 by the application. 237 * pname:size is the requested size of an allocation. 238 * pname:allocationType is a elink:VkInternalAllocationType value 239 specifying the requested type of an allocation. 240 * pname:allocationScope is a elink:VkSystemAllocationScope value 241 specifying the allocation scope of the lifetime of the allocation, as 242 described <<memory-host-allocation-scope,here>>. 243 244-- 245 246[open,refpage='VkSystemAllocationScope',desc='Allocation scope',type='enums',xrefs='VkAllocationCallbacks'] 247-- 248 249[[memory-host-allocation-scope]] 250Each allocation has an _allocation scope_ which defines its lifetime and 251which object it is associated with. 252Possible values passed to the pname:allocationScope parameter of the 253callback functions specified by slink:VkAllocationCallbacks, indicating the 254allocation scope, are: 255 256include::../api/enums/VkSystemAllocationScope.txt[] 257 258 * ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND specifies that the allocation 259 is scoped to the duration of the Vulkan command. 260 * ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT specifies that the allocation is 261 scoped to the lifetime of the Vulkan object that is being created or 262 used. 263 * ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE specifies that the allocation is 264 scoped to the lifetime of a sname:VkPipelineCache 265ifdef::VK_EXT_validation_cache[] 266 or sname:VkValidationCacheEXT 267endif::VK_EXT_validation_cache[] 268 object. 269 * ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE specifies that the allocation is 270 scoped to the lifetime of the Vulkan device. 271 * ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE specifies that the allocation 272 is scoped to the lifetime of the Vulkan instance. 273 274Most Vulkan commands operate on a single object, or there is a sole object 275that is being created or manipulated. 276When an allocation uses an allocation scope of 277ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or 278ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the 279object being created or manipulated. 280 281When an implementation requires host memory, it will make callbacks to the 282application using the most specific allocator and allocation scope 283available: 284 285 * If an allocation is scoped to the duration of a command, the allocator 286 will use the ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND allocation scope. 287 The most specific allocator available is used: if the object being 288 created or manipulated has an allocator, that object's allocator will be 289 used, else if the parent sname:VkDevice has an allocator it will be 290 used, else if the parent sname:VkInstance has an allocator it will be 291 used. 292 Else, 293 * If an allocation is associated with an object of type 294ifdef::VK_EXT_validation_cache[] 295 sname:VkValidationCacheEXT or 296endif::VK_EXT_validation_cache[] 297 sname:VkPipelineCache, the allocator will use the 298 ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE allocation scope. 299 The most specific allocator available is used (cache, else device, else 300 instance). 301 Else, 302 * If an allocation is scoped to the lifetime of an object, that object is 303 being created or manipulated by the command, and that object's type is 304 not sname:VkDevice or sname:VkInstance, the allocator will use an 305 allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT. 306 The most specific allocator available is used (object, else device, else 307 instance). 308 Else, 309 * If an allocation is scoped to the lifetime of a device, the allocator 310 will use an allocation scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE. 311 The most specific allocator available is used (device, else instance). 312 Else, 313 * If the allocation is scoped to the lifetime of an instance and the 314 instance has an allocator, its allocator will be used with an allocation 315 scope of ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE. 316 * Otherwise an implementation will allocate memory through an alternative 317 mechanism that is unspecified. 318 319-- 320 321Objects that are allocated from pools do not specify their own allocator. 322When an implementation requires host memory for such an object, that memory 323is sourced from the object's parent pool's allocator. 324 325The application is not expected to handle allocating memory that is intended 326for execution by the host due to the complexities of differing security 327implementations across multiple platforms. 328The implementation will allocate such memory internally and invoke an 329application provided informational callback when these _internal 330allocations_ are allocated and freed. 331Upon allocation of executable memory, pname:pfnInternalAllocation will be 332called. 333Upon freeing executable memory, pname:pfnInternalFree will be called. 334An implementation will only call an informational callback for executable 335memory allocations and frees. 336 337[open,refpage='VkInternalAllocationType',desc='Allocation type',type='enums',xrefs='PFN_vkInternalAllocationNotification PFN_vkInternalFreeNotification'] 338-- 339 340The pname:allocationType parameter to the pname:pfnInternalAllocation and 341pname:pfnInternalFree functions may: be one of the following values: 342 343include::../api/enums/VkInternalAllocationType.txt[] 344 345 * ename:VK_INTERNAL_ALLOCATION_TYPE_EXECUTABLE specifies that the 346 allocation is intended for execution by the host. 347 348-- 349 350An implementation must: only make calls into an application-provided 351allocator during the execution of an API command. 352An implementation must: only make calls into an application-provided 353allocator from the same thread that called the provoking API command. 354The implementation should: not synchronize calls to any of the callbacks. 355If synchronization is needed, the callbacks must: provide it themselves. 356The informational callbacks are subject to the same restrictions as the 357allocation callbacks. 358 359If an implementation intends to make calls through a 360sname:VkAllocationCallbacks structure between the time a ftext:vkCreate* 361command returns and the time a corresponding ftext:vkDestroy* command 362begins, that implementation must: save a copy of the allocator before the 363ftext:vkCreate* command returns. 364The callback functions and any data structures they rely upon must: remain 365valid for the lifetime of the object they are associated with. 366 367If an allocator is provided to a ftext:vkCreate* command, a _compatible_ 368allocator must: be provided to the corresponding ftext:vkDestroy* command. 369Two sname:VkAllocationCallbacks structures are compatible if memory 370allocated with pname:pfnAllocation or pname:pfnReallocation in each can: be 371freed with pname:pfnReallocation or pname:pfnFree in the other. 372An allocator must: not be provided to a ftext:vkDestroy* command if an 373allocator was not provided to the corresponding ftext:vkCreate* command. 374 375If a non-`NULL` allocator is used, the pname:pfnAllocation, 376pname:pfnReallocation and pname:pfnFree members must: be non-`NULL` and 377point to valid implementations of the callbacks. 378An application can: choose to not provide informational callbacks by setting 379both pname:pfnInternalAllocation and pname:pfnInternalFree to `NULL`. 380pname:pfnInternalAllocation and pname:pfnInternalFree must: either both be 381`NULL` or both be non-`NULL`. 382 383If pname:pfnAllocation or pname:pfnReallocation fail, the implementation 384may: fail object creation and/or generate an 385ename:VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate. 386 387Allocation callbacks must: not call any Vulkan commands. 388 389The following sets of rules define when an implementation is permitted to 390call the allocator callbacks. 391 392pname:pfnAllocation or pname:pfnReallocation may: be called in the following 393situations: 394 395 * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be 396 allocated from any API command. 397 * Allocations scoped to a command may: be allocated from any API command. 398 * Allocations scoped to a sname:VkPipelineCache may: only be allocated 399 from: 400 ** fname:vkCreatePipelineCache 401 ** fname:vkMergePipelineCaches for pname:dstCache 402 ** fname:vkCreateGraphicsPipelines for pname:pipelineCache 403 ** fname:vkCreateComputePipelines for pname:pipelineCache 404ifdef::VK_EXT_validation_cache[] 405 * Allocations scoped to a sname:VkValidationCacheEXT may: only be 406 allocated from: 407 ** fname:vkCreateValidationCacheEXT 408 ** fname:vkMergeValidationCachesEXT for pname:dstCache 409 ** fname:vkCreateShaderModule for pname:validationCache in 410 sname:VkShaderModuleValidationCacheCreateInfoEXT 411endif::VK_EXT_validation_cache[] 412 * Allocations scoped to a sname:VkDescriptorPool may: only be allocated 413 from: 414 ** any command that takes the pool as a direct argument 415 ** fname:vkAllocateDescriptorSets for the pname:descriptorPool member of 416 its pname:pAllocateInfo parameter 417 ** fname:vkCreateDescriptorPool 418 * Allocations scoped to a sname:VkCommandPool may: only be allocated from: 419 ** any command that takes the pool as a direct argument 420 ** fname:vkCreateCommandPool 421 ** fname:vkAllocateCommandBuffers for the pname:commandPool member of its 422 pname:pAllocateInfo parameter 423 ** any ftext:vkCmd* command whose pname:commandBuffer was allocated from 424 that sname:VkCommandPool 425 * Allocations scoped to any other object may: only be allocated in that 426 object's ftext:vkCreate* command. 427 428pname:pfnFree may: be called in the following situations: 429 430 * Allocations scoped to a sname:VkDevice or sname:VkInstance may: be freed 431 from any API command. 432 * Allocations scoped to a command must: be freed by any API command which 433 allocates such memory. 434 * Allocations scoped to a sname:VkPipelineCache may: be freed from 435 fname:vkDestroyPipelineCache. 436ifdef::VK_EXT_validation_cache[] 437 * Allocations scoped to a sname:VkValidationCacheEXT may: be freed from 438 fname:vkDestroyValidationCacheEXT. 439endif::VK_EXT_validation_cache[] 440 * Allocations scoped to a sname:VkDescriptorPool may: be freed from 441 ** any command that takes the pool as a direct argument 442 * Allocations scoped to a sname:VkCommandPool may: be freed from: 443 ** any command that takes the pool as a direct argument 444 ** fname:vkResetCommandBuffer whose pname:commandBuffer was allocated from 445 that sname:VkCommandPool 446 * Allocations scoped to any other object may: be freed in that object's 447 ftext:vkDestroy* command. 448 * Any command that allocates host memory may: also free host memory of the 449 same scope. 450 451 452[[memory-device]] 453== Device Memory 454 455_Device memory_ is memory that is visible to the device -- for example the 456contents of the image or buffer objects, which can: be natively used by the 457device. 458 459Memory properties of a physical device describe the memory heaps and memory 460types available. 461 462[open,refpage='vkGetPhysicalDeviceMemoryProperties',desc='Reports memory information for the specified physical device',type='protos'] 463-- 464 465To query memory properties, call: 466 467include::../api/protos/vkGetPhysicalDeviceMemoryProperties.txt[] 468 469 * pname:physicalDevice is the handle to the device to query. 470 * pname:pMemoryProperties points to an instance of 471 sname:VkPhysicalDeviceMemoryProperties structure in which the properties 472 are returned. 473 474include::../validity/protos/vkGetPhysicalDeviceMemoryProperties.txt[] 475-- 476 477[open,refpage='VkPhysicalDeviceMemoryProperties',desc='Structure specifying physical device memory properties',type='structs'] 478-- 479 480The sname:VkPhysicalDeviceMemoryProperties structure is defined as: 481 482include::../api/structs/VkPhysicalDeviceMemoryProperties.txt[] 483 484 * pname:memoryTypeCount is the number of valid elements in the 485 pname:memoryTypes array. 486 * pname:memoryTypes is an array of slink:VkMemoryType structures 487 describing the _memory types_ that can: be used to access memory 488 allocated from the heaps specified by pname:memoryHeaps. 489 * pname:memoryHeapCount is the number of valid elements in the 490 pname:memoryHeaps array. 491 * pname:memoryHeaps is an array of slink:VkMemoryHeap structures 492 describing the _memory heaps_ from which memory can: be allocated. 493 494The sname:VkPhysicalDeviceMemoryProperties structure describes a number of 495_memory heaps_ as well as a number of _memory types_ that can: be used to 496access memory allocated in those heaps. 497Each heap describes a memory resource of a particular size, and each memory 498type describes a set of memory properties (e.g. host cached vs uncached) 499that can: be used with a given memory heap. 500Allocations using a particular memory type will consume resources from the 501heap indicated by that memory type's heap index. 502More than one memory type may: share each heap, and the heaps and memory 503types provide a mechanism to advertise an accurate size of the physical 504memory resources while allowing the memory to be used with a variety of 505different properties. 506 507The number of memory heaps is given by pname:memoryHeapCount and is less 508than or equal to ename:VK_MAX_MEMORY_HEAPS. 509Each heap is described by an element of the pname:memoryHeaps array as a 510slink:VkMemoryHeap structure. 511The number of memory types available across all memory heaps is given by 512pname:memoryTypeCount and is less than or equal to 513ename:VK_MAX_MEMORY_TYPES. 514Each memory type is described by an element of the pname:memoryTypes array 515as a slink:VkMemoryType structure. 516 517At least one heap must: include ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT in 518slink:VkMemoryHeap::pname:flags. 519If there are multiple heaps that all have similar performance 520characteristics, they may: all include 521ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT. 522In a unified memory architecture (UMA) system there is often only a single 523memory heap which is considered to be equally "`local`" to the host and to 524the device, and such an implementation must: advertise the heap as 525device-local. 526 527[[memory-device-bitmask-list]] 528Each memory type returned by flink:vkGetPhysicalDeviceMemoryProperties must: 529have its pname:propertyFlags set to one of the following values: 530 531 * 0 532 * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 533 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT 534 * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 535 ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT 536 * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 537 ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | + 538 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT 539 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT 540 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + 541 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 542 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT 543 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + 544 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 545 ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT 546 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + 547 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | + 548 ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT | + 549 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT 550 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | + 551 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT 552ifdef::VK_VERSION_1_1[] 553 * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT 554 * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT | 555 ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT 556endif::VK_VERSION_1_1[] 557 558There must: be at least one memory type with both the 559ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT and 560ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bits set in its 561pname:propertyFlags. 562There must: be at least one memory type with the 563ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set in its 564pname:propertyFlags. 565 566For each pair of elements *X* and *Y* returned in pname:memoryTypes, *X* 567must: be placed at a lower index position than *Y* if: 568 569 * either the set of bit flags returned in the pname:propertyFlags member 570 of *X* is a strict subset of the set of bit flags returned in the 571 pname:propertyFlags member of *Y*. 572 * or the pname:propertyFlags members of *X* and *Y* are equal, and *X* 573 belongs to a memory heap with greater performance (as determined in an 574 implementation-specific manner). 575 576[NOTE] 577.Note 578==== 579There is no ordering requirement between *X* and *Y* elements for the case 580their pname:propertyFlags members are not in a subset relation. 581That potentially allows more than one possible way to order the same set of 582memory types. 583Notice that the <<memory-device-bitmask-list,list of all allowed memory 584property flag combinations>> is written in the required order. 585But if instead ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT was before 586ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | 587ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, the list would still be in the 588required order. 589==== 590 591This ordering requirement enables applications to use a simple search loop 592to select the desired memory type along the lines of: 593 594[source,c++] 595--------------------------------------------------- 596// Find a memory in `memoryTypeBitsRequirement` that includes all of `requiredProperties` 597int32_t findProperties(const VkPhysicalDeviceMemoryProperties* pMemoryProperties, 598 uint32_t memoryTypeBitsRequirement, 599 VkMemoryPropertyFlags requiredProperties) { 600 const uint32_t memoryCount = pMemoryProperties->memoryTypeCount; 601 for (uint32_t memoryIndex = 0; memoryIndex < memoryCount; ++memoryIndex) { 602 const uint32_t memoryTypeBits = (1 << memoryIndex); 603 const bool isRequiredMemoryType = memoryTypeBitsRequirement & memoryTypeBits; 604 605 const VkMemoryPropertyFlags properties = 606 pMemoryProperties->memoryTypes[memoryIndex].propertyFlags; 607 const bool hasRequiredProperties = 608 (properties & requiredProperties) == requiredProperties; 609 610 if (isRequiredMemoryType && hasRequiredProperties) 611 return static_cast<int32_t>(memoryIndex); 612 } 613 614 // failed to find memory type 615 return -1; 616} 617 618// Try to find an optimal memory type, or if it does not exist try fallback memory type 619// `device` is the VkDevice 620// `image` is the VkImage that requires memory to be bound 621// `memoryProperties` properties as returned by vkGetPhysicalDeviceMemoryProperties 622// `requiredProperties` are the property flags that must be present 623// `optimalProperties` are the property flags that are preferred by the application 624VkMemoryRequirements memoryRequirements; 625vkGetImageMemoryRequirements(device, image, &memoryRequirements); 626int32_t memoryType = 627 findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, optimalProperties); 628if (memoryType == -1) // not found; try fallback properties 629 memoryType = 630 findProperties(&memoryProperties, memoryRequirements.memoryTypeBits, requiredProperties); 631--------------------------------------------------- 632 633 634include::../validity/structs/VkPhysicalDeviceMemoryProperties.txt[] 635-- 636 637ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 638 639[open,refpage='vkGetPhysicalDeviceMemoryProperties2',desc='Reports memory information for the specified physical device',type='protos'] 640-- 641 642To query memory properties, call: 643 644ifdef::VK_VERSION_1_1[] 645include::../api/protos/vkGetPhysicalDeviceMemoryProperties2.txt[] 646endif::VK_VERSION_1_1[] 647 648ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 649 650ifdef::VK_KHR_get_physical_device_properties2[] 651include::../api/protos/vkGetPhysicalDeviceMemoryProperties2KHR.txt[] 652endif::VK_KHR_get_physical_device_properties2[] 653 654 * pname:physicalDevice is the handle to the device to query. 655 * pname:pMemoryProperties points to an instance of 656 sname:VkPhysicalDeviceMemoryProperties2 structure in which the 657 properties are returned. 658 659fname:vkGetPhysicalDeviceMemoryProperties2 behaves similarly to 660flink:vkGetPhysicalDeviceMemoryProperties, with the ability to return 661extended information in a pname:pNext chain of output structures. 662 663include::../validity/protos/vkGetPhysicalDeviceMemoryProperties2.txt[] 664-- 665 666[open,refpage='VkPhysicalDeviceMemoryProperties2',desc='Structure specifying physical device memory properties',type='structs'] 667-- 668 669The sname:VkPhysicalDeviceMemoryProperties2 structure is defined as: 670 671include::../api/structs/VkPhysicalDeviceMemoryProperties2.txt[] 672 673ifdef::VK_KHR_get_physical_device_properties2[] 674or the equivalent 675 676include::../api/structs/VkPhysicalDeviceMemoryProperties2KHR.txt[] 677endif::VK_KHR_get_physical_device_properties2[] 678 679 * pname:sType is the type of this structure. 680 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 681 * pname:memoryProperties is a structure of type 682 slink:VkPhysicalDeviceMemoryProperties which is populated with the same 683 values as in flink:vkGetPhysicalDeviceMemoryProperties. 684 685include::../validity/structs/VkPhysicalDeviceMemoryProperties2.txt[] 686-- 687 688endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 689 690 691[open,refpage='VkMemoryHeap',desc='Structure specifying a memory heap',type='structs'] 692-- 693 694The sname:VkMemoryHeap structure is defined as: 695 696include::../api/structs/VkMemoryHeap.txt[] 697 698 * pname:size is the total memory size in bytes in the heap. 699 * pname:flags is a bitmask of elink:VkMemoryHeapFlagBits specifying 700 attribute flags for the heap. 701 702include::../validity/structs/VkMemoryHeap.txt[] 703-- 704 705[open,refpage='VkMemoryHeapFlagBits',desc='Bitmask specifying attribute flags for a heap',type='enums'] 706-- 707 708Bits which may: be set in slink:VkMemoryHeap::pname:flags, indicating 709attribute flags for the heap, are: 710 711include::../api/enums/VkMemoryHeapFlagBits.txt[] 712 713 * ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT specifies that the heap 714 corresponds to device local memory. 715 Device local memory may: have different performance characteristics than 716 host local memory, and may: support different memory property flags. 717ifdef::VK_KHR_device_group_creation[] 718 * ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT specifies that in a logical 719 device representing more than one physical device, there is a 720 per-physical device instance of the heap memory. 721 By default, an allocation from such a heap will be replicated to each 722 physical device's instance of the heap. 723endif::VK_KHR_device_group_creation[] 724 725-- 726 727[open,refpage='VkMemoryHeapFlags',desc='Bitmask of VkMemoryHeapFlagBits',type='enums'] 728-- 729include::../api/flags/VkMemoryHeapFlags.txt[] 730 731sname:VkMemoryHeapFlags is a bitmask type for setting a mask of zero or more 732slink:VkMemoryHeapFlagBits. 733-- 734 735[open,refpage='VkMemoryType',desc='Structure specifying memory type',type='structs'] 736-- 737 738The sname:VkMemoryType structure is defined as: 739 740include::../api/structs/VkMemoryType.txt[] 741 742 * pname:heapIndex describes which memory heap this memory type corresponds 743 to, and must: be less than pname:memoryHeapCount from the 744 slink:VkPhysicalDeviceMemoryProperties structure. 745 * pname:propertyFlags is a bitmask of elink:VkMemoryPropertyFlagBits of 746 properties for this memory type. 747 748include::../validity/structs/VkMemoryType.txt[] 749-- 750 751[open,refpage='VkMemoryPropertyFlagBits',desc='Bitmask specifying properties for a memory type',type='enums'] 752-- 753 754Bits which may: be set in slink:VkMemoryType::pname:propertyFlags, 755indicating properties of a memory heap, are: 756 757include::../api/enums/VkMemoryPropertyFlagBits.txt[] 758 759 * ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit specifies that memory 760 allocated with this type is the most efficient for device access. 761 This property will be set if and only if the memory type belongs to a 762 heap with the ename:VK_MEMORY_HEAP_DEVICE_LOCAL_BIT set. 763 * ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit specifies that memory 764 allocated with this type can: be mapped for host access using 765 flink:vkMapMemory. 766 * ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit specifies that the host 767 cache management commands flink:vkFlushMappedMemoryRanges and 768 flink:vkInvalidateMappedMemoryRanges are not needed to flush host writes 769 to the device or make device writes visible to the host, respectively. 770 * ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT bit specifies that memory 771 allocated with this type is cached on the host. 772 Host memory accesses to uncached memory are slower than to cached 773 memory, however uncached memory is always host coherent. 774 * ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit specifies that the 775 memory type only allows device access to the memory. 776 Memory types must: not have both 777 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT and 778 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set. 779 Additionally, the object's backing memory may: be provided by the 780 implementation lazily as specified in <<memory-device-lazy_allocation, 781 Lazily Allocated Memory>>. 782ifdef::VK_VERSION_1_1[] 783 * ename:VK_MEMORY_PROPERTY_PROTECTED_BIT bit specifies that the memory 784 type only allows device access to the memory, and allows protected queue 785 operations to access the memory. 786 Memory types must: not have ename:VK_MEMORY_PROPERTY_PROTECTED_BIT set 787 and any of ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT set, or 788 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, or 789 ename:VK_MEMORY_PROPERTY_HOST_CACHED_BIT set. 790endif::VK_VERSION_1_1[] 791 792-- 793 794[open,refpage='VkMemoryPropertyFlags',desc='Bitmask of VkMemoryPropertyFlagBits',type='enums'] 795-- 796include::../api/flags/VkMemoryPropertyFlags.txt[] 797 798sname:VkMemoryPropertyFlags is a bitmask type for setting a mask of zero or 799more slink:VkMemoryPropertyFlagBits. 800-- 801 802[open,refpage='VkDeviceMemory',desc='Opaque handle to a device memory object',type='handles'] 803-- 804 805A Vulkan device operates on data in device memory via memory objects that 806are represented in the API by a sname:VkDeviceMemory handle: 807 808include::../api/handles/VkDeviceMemory.txt[] 809 810-- 811 812[open,refpage='vkAllocateMemory',desc='Allocate device memory',type='protos'] 813-- 814 815To allocate memory objects, call: 816 817include::../api/protos/vkAllocateMemory.txt[] 818 819 * pname:device is the logical device that owns the memory. 820 * pname:pAllocateInfo is a pointer to an instance of the 821 slink:VkMemoryAllocateInfo structure describing parameters of the 822 allocation. 823 A successful returned allocation must: use the requested parameters -- 824 no substitution is permitted by the implementation. 825 * pname:pAllocator controls host memory allocation as described in the 826 <<memory-allocation, Memory Allocation>> chapter. 827 * pname:pMemory is a pointer to a slink:VkDeviceMemory handle in which 828 information about the allocated memory is returned. 829 830Allocations returned by fname:vkAllocateMemory are guaranteed to meet any 831alignment requirement of the implementation. 832For example, if an implementation requires 128 byte alignment for images and 83364 byte alignment for buffers, the device memory returned through this 834mechanism would be 128-byte aligned. 835This ensures that applications can: correctly suballocate objects of 836different types (with potentially different alignment requirements) in the 837same memory object. 838 839ifndef::VK_VERSION_1_1[] 840When memory is allocated, its contents are undefined. 841endif::VK_VERSION_1_1[] 842ifdef::VK_VERSION_1_1[] 843When memory is allocated, its contents are undefined with the following 844constraint: 845 846 * The contents of unprotected memory must: not be a function of data 847 protected memory objects, even if those memory objects were previously 848 freed. 849 850[NOTE] 851.Note 852==== 853The contents of memory allocated by one application should: not be a 854function of data from protected memory objects of another application, even 855if those memory objects were previously freed. 856==== 857endif::VK_VERSION_1_1[] 858 859The maximum number of valid memory allocations that can: exist 860simultaneously within a slink:VkDevice may: be restricted by implementation- 861or platform-dependent limits. 862If a call to flink:vkAllocateMemory would cause the total number of 863allocations to exceed these limits, such a call will fail and must: return 864ename:VK_ERROR_TOO_MANY_OBJECTS. 865The 866<<features-limits-maxMemoryAllocationCount,pname:maxMemoryAllocationCount>> 867feature describes the number of allocations that can: exist simultaneously 868before encountering these internal limits. 869 870Some platforms may: have a limit on the maximum size of a single allocation. 871For example, certain systems may: fail to create allocations with a size 872greater than or equal to 4GB. 873Such a limit is implementation-dependent, and if such a failure occurs then 874the error ename:VK_ERROR_OUT_OF_DEVICE_MEMORY must: be returned. 875ifdef::VK_KHR_maintenance3[] 876This limit is advertised in 877slink:VkPhysicalDeviceMaintenance3Properties::pname:maxMemoryAllocationSize. 878endif::VK_KHR_maintenance3[] 879 880.Valid Usage 881**** 882 * [[VUID-vkAllocateMemory-pAllocateInfo-01713]] 883 pname:pAllocateInfo\->pname:allocationSize must: be less than or equal 884 to 885 slink:VkPhysicalDeviceMemoryProperties::pname:memoryHeaps[pname:pAllocateInfo\->pname:memoryTypeIndex].pname:size 886 as returned by flink:vkGetPhysicalDeviceMemoryProperties for the 887 slink:VkPhysicalDevice that pname:device was created from. 888 * [[VUID-vkAllocateMemory-pAllocateInfo-01714]] 889 pname:pAllocateInfo\->pname:memoryTypeIndex must: be less than 890 slink:VkPhysicalDeviceMemoryProperties::pname:memoryTypeCount as 891 returned by flink:vkGetPhysicalDeviceMemoryProperties for the 892 slink:VkPhysicalDevice that pname:device was created from. 893**** 894 895include::../validity/protos/vkAllocateMemory.txt[] 896-- 897 898[open,refpage='VkMemoryAllocateInfo',desc='Structure containing parameters of a memory allocation',type='structs'] 899-- 900 901The sname:VkMemoryAllocateInfo structure is defined as: 902 903include::../api/structs/VkMemoryAllocateInfo.txt[] 904 905 * pname:sType is the type of this structure. 906 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 907 * pname:allocationSize is the size of the allocation in bytes 908 * pname:memoryTypeIndex is an index identifying a memory type from the 909 pname:memoryTypes array of the slink:VkPhysicalDeviceMemoryProperties 910 structure 911 912ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[] 913An instance of the slink:VkMemoryAllocateInfo structure defines a memory 914import operation if the pname:pNext chain contains an instance of one of the 915following structures: 916 917ifdef::VK_KHR_external_memory_win32[] 918 * slink:VkImportMemoryWin32HandleInfoKHR with non-zero pname:handleType 919 value 920endif::VK_KHR_external_memory_win32[] 921ifdef::VK_KHR_external_memory_fd[] 922 * slink:VkImportMemoryFdInfoKHR with a non-zero pname:handleType value 923endif::VK_KHR_external_memory_fd[] 924ifdef::VK_EXT_external_memory_host[] 925 * slink:VkImportMemoryHostPointerInfoEXT with a non-zero pname:handleType 926 value 927endif::VK_EXT_external_memory_host[] 928ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 929 * slink:VkImportAndroidHardwareBufferInfoANDROID with a non-`NULL` 930 pname:buffer value 931endif::VK_ANDROID_external_memory_android_hardware_buffer[] 932 933Importing memory must: not modify the content of the memory. 934Implementations must: ensure that importing memory does not enable the 935importing Vulkan instance to access any memory or resources in other Vulkan 936instances other than that corresponding to the memory object imported. 937Implementations must: also ensure accessing imported memory which has not 938been initialized does not allow the importing Vulkan instance to obtain data 939from the exporting Vulkan instance or vice-versa. 940 941[NOTE] 942.Note 943==== 944How exported and imported memory is isolated is left to the implementation, 945but applications should be aware that such isolation may: prevent 946implementations from placing multiple exportable memory objects in the same 947physical or virtual page. 948Hence, applications should: avoid creating many small external memory 949objects whenever possible. 950==== 951 952When performing a memory import operation, it is the responsibility of the 953application to ensure the external handles meet all valid usage 954requirements. 955However, implementations must: perform sufficient validation of external 956handles to ensure that the operation results in a valid memory object which 957will not cause program termination, device loss, queue stalls, or corruption 958of other resources when used as allowed according to its allocation 959parameters. 960If the external handle provided does not meet these requirements, the 961implementation must: fail the memory import operation with the error code 962ename:VK_ERROR_INVALID_EXTERNAL_HANDLE. 963 964endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_memory_host,VK_ANDROID_external_memory_android_hardware_buffer[] 965 966.Valid Usage 967**** 968ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 969 * [[VUID-VkMemoryAllocateInfo-allocationSize-00638]] 970 pname:allocationSize must: be greater than `0` 971endif::VK_ANDROID_external_memory_android_hardware_buffer[] 972ifdef::VK_KHR_external_memory[] 973ifdef::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[] 974 * [[VUID-VkMemoryAllocateInfo-pNext-00639]] 975 If the pname:pNext chain contains an instance of 976 sname:VkExportMemoryAllocateInfo, and any of the handle types specified 977 in sname:VkExportMemoryAllocateInfo::pname:handleTypes require a 978 dedicated allocation, as reported by 979 flink:vkGetPhysicalDeviceImageFormatProperties2 in 980 sname:VkExternalImageFormatProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures 981 or 982 sname:VkExternalBufferProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures, 983 the pname:pNext chain must contain an instance of 984ifdef::VK_KHR_dedicated_allocation[slink:VkMemoryDedicatedAllocateInfo] 985ifdef::VK_KHR_dedicated_allocation[] 986ifdef::VK_NV_dedicated_allocation[or] 987endif::VK_KHR_dedicated_allocation[] 988ifdef::VK_NV_dedicated_allocation[slink:VkDedicatedAllocationMemoryAllocateInfoNV] 989 with either its pname:image or pname:buffer field set to a value other 990 than ename:VK_NULL_HANDLE. 991endif::VK_KHR_dedicated_allocation,VK_NV_dedicated_allocation[] 992endif::VK_KHR_external_memory[] 993ifdef::VK_KHR_external_memory[] 994ifdef::VK_NV_external_memory[] 995 * [[VUID-VkMemoryAllocateInfo-pNext-00640]] 996 If the pname:pNext chain contains an instance of 997 slink:VkExportMemoryAllocateInfo, it must: not contain an instance of 998 slink:VkExportMemoryAllocateInfoNV or 999 slink:VkExportMemoryWin32HandleInfoNV. 1000endif::VK_NV_external_memory[] 1001endif::VK_KHR_external_memory[] 1002ifdef::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[] 1003 * [[VUID-VkMemoryAllocateInfo-pNext-00641]] 1004 If the pname:pNext chain contains an instance of 1005 slink:VkImportMemoryWin32HandleInfoKHR, it must: not contain an instance 1006 of slink:VkImportMemoryWin32HandleInfoNV. 1007endif::VK_KHR_external_memory_win32+VK_NV_external_memory_win32[] 1008ifdef::VK_KHR_external_memory_fd[] 1009 * [[VUID-VkMemoryAllocateInfo-allocationSize-01742]] 1010 If the parameters define an import operation, the external handle 1011 specified was created by the Vulkan API, and the external handle type is 1012 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR, then the values 1013 of pname:allocationSize and pname:memoryTypeIndex must: match those 1014 specified when the memory object being imported was created. 1015endif::VK_KHR_external_memory_fd[] 1016ifdef::VK_KHR_external_memory+VK_KHR_device_group[] 1017 * [[VUID-VkMemoryAllocateInfo-None-00643]] 1018 If the parameters define an import operation and the external handle 1019 specified was created by the Vulkan API, the device mask specified by 1020 slink:VkMemoryAllocateFlagsInfo must: match that specified when the 1021 memory object being imported was allocated. 1022 * [[VUID-VkMemoryAllocateInfo-None-00644]] 1023 If the parameters define an import operation and the external handle 1024 specified was created by the Vulkan API, the list of physical devices 1025 that comprise the logical device passed to flink:vkAllocateMemory must: 1026 match the list of physical devices that comprise the logical device on 1027 which the memory was originally allocated. 1028endif::VK_KHR_external_memory+VK_KHR_device_group[] 1029ifdef::VK_KHR_external_memory_win32[] 1030 * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-00645]] 1031 If the parameters define an import operation and the external handle is 1032 an NT handle or a global share handle created outside of the Vulkan API, 1033 the value of pname:memoryTypeIndex must: be one of those returned by 1034 flink:vkGetMemoryWin32HandlePropertiesKHR. 1035 * [[VUID-VkMemoryAllocateInfo-allocationSize-01743]] 1036 If the parameters define an import operation, the external handle was 1037 created by the Vulkan API, and the external handle type is 1038 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT_KHR or 1039 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT_KHR, then the 1040 values of pname:allocationSize and pname:memoryTypeIndex must: match 1041 those specified when the memory object being imported was created. 1042 * [[VUID-VkMemoryAllocateInfo-allocationSize-00646]] 1043 If the parameters define an import operation and the external handle 1044 type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 1045 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or 1046 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, 1047 pname:allocationSize must: match the size reported in the memory 1048 requirements of the pname:image or pname:buffer member of the instance 1049 of sname:VkDedicatedAllocationMemoryAllocateInfoNV included in the 1050 pname:pNext chain. 1051 * [[VUID-VkMemoryAllocateInfo-allocationSize-00647]] 1052 If the parameters define an import operation and the external handle 1053 type is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, 1054 pname:allocationSize must: match the size specified when creating the 1055 Direct3D 12 heap from which the external handle was extracted. 1056endif::VK_KHR_external_memory_win32[] 1057ifdef::VK_KHR_external_memory_fd[] 1058 * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-00648]] 1059 If the parameters define an import operation and the external handle is 1060 a POSIX file descriptor created outside of the Vulkan API, the value of 1061 pname:memoryTypeIndex must: be one of those returned by 1062 flink:vkGetMemoryFdPropertiesKHR. 1063endif::VK_KHR_external_memory_fd[] 1064ifdef::VK_VERSION_1_1[] 1065 * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01872]] 1066 If the protected memory feature is not enabled, the 1067 sname:VkMemoryAllocateInfo::pname:memoryTypeIndex must: not indicate a 1068 memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT. 1069endif::VK_VERSION_1_1[] 1070ifdef::VK_EXT_external_memory_host[] 1071 * [[VUID-VkMemoryAllocateInfo-memoryTypeIndex-01744]] 1072 If the parameters define an import operation and the external handle is 1073 a host pointer, the value of pname:memoryTypeIndex must: be one of those 1074 returned by flink:vkGetMemoryHostPointerPropertiesEXT 1075 * [[VUID-VkMemoryAllocateInfo-allocationSize-01745]] 1076 If the parameters define an import operation and the external handle is 1077 a host pointer, pname:allocationSize must: be an integer multiple of 1078 sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment 1079endif::VK_EXT_external_memory_host[] 1080ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1081 * [[VUID-VkMemoryAllocateInfo-None-01873]] 1082 If the parameters define an import operation and the external handle 1083 type is 1084 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BIT_ANDROID: 1085 ** pname:allocationSize must: be the size returned by 1086 flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android 1087 hardware buffer 1088 ** If the pname:pNext chain does not contain an instance of 1089 slink:VkMemoryDedicatedAllocateInfo or 1090 pname:VkMemoryDedicatedAllocateInfo::pname:image is 1091 dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a format 1092 of code:AHARDWAREBUFFER_FORMAT_BLOB and a usage that includes 1093 code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER 1094 ** pname:memoryTypeIndex must: be one of those returned by 1095 flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android 1096 hardware buffer 1097 * [[VUID-VkMemoryAllocateInfo-pNext-01874]] 1098 If the parameters do not define an import operation, and the pname:pNext 1099 chain contains an instance of sname:VkExportMemoryAllocateInfo with 1100 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 1101 included in its pname:handleTypes member, and the pname:pNext contains 1102 an instance of slink:VkMemoryDedicatedAllocateInfo with pname:image not 1103 equal to dlink:VK_NULL_HANDLE, then pname:allocationSize must: be `0`, 1104 otherwise pname:allocationSize must: be greater than `0`. 1105 * [[VUID-VkMemoryAllocateInfo-pNext-01875]] 1106 If the parameters define an import operation, the external handle is an 1107 Android hardware buffer, and the pname:pNext chain includes an instance 1108 of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not 1109 dlink:VK_NULL_HANDLE: 1110 ** The Android hardware buffer's usage must: include at least one of 1111 code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or 1112 code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE 1113 ** The format of pname:image must: be ename:VK_FORMAT_UNDEFINED or the 1114 format returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID 1115 in slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format 1116 for the Android hardware buffer. 1117 ** The width, height, and array layer dimensions of pname:image and the 1118 Android hardware buffer must: be identical 1119 ** If the Android hardware buffer's usage includes 1120 code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: 1121 have [eq]#{lfloor}log~2~(max(code:width, code:height)){rfloor} {plus} 1122 1# mip levels, otherwise it must: have exactly `1` mip level. 1123 ** Each bit set in the usage of pname:image must: be listed in 1124 <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage 1125 Equivalence>>, and if there is a corresponding 1126 code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in 1127 the Android hardware buffer's usage 1128endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1129**** 1130 1131include::../validity/structs/VkMemoryAllocateInfo.txt[] 1132-- 1133 1134ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 1135 1136[open,refpage='VkMemoryDedicatedAllocateInfo',desc='Specify a dedicated memory allocation resource',type='structs'] 1137-- 1138 1139If the pname:pNext chain includes a sname:VkMemoryDedicatedAllocateInfo 1140structure, then that structure includes a handle of the sole buffer or image 1141resource that the memory can: be bound to. 1142 1143The sname:VkMemoryDedicatedAllocateInfo structure is defined as: 1144 1145include::../api/structs/VkMemoryDedicatedAllocateInfo.txt[] 1146 1147ifdef::VK_KHR_dedicated_allocation[] 1148or the equivalent 1149 1150include::../api/structs/VkMemoryDedicatedAllocateInfoKHR.txt[] 1151endif::VK_KHR_dedicated_allocation[] 1152 1153 * pname:sType is the type of this structure. 1154 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1155 * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this 1156 memory will be bound to. 1157 * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this 1158 memory will be bound to. 1159 1160.Valid Usage 1161**** 1162 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01432]] 1163 At least one of pname:image and pname:buffer must: be 1164 dlink:VK_NULL_HANDLE 1165 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01433]] 1166 If pname:image is not dlink:VK_NULL_HANDLE, 1167 sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the 1168 sname:VkMemoryRequirements::pname:size of the image 1169 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01434]] 1170 If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: have been 1171 created without ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT set in 1172 sname:VkImageCreateInfo::pname:flags 1173 * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01435]] 1174 If pname:buffer is not dlink:VK_NULL_HANDLE, 1175 sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the 1176 sname:VkMemoryRequirements::pname:size of the buffer 1177 * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01436]] 1178 If pname:buffer is not dlink:VK_NULL_HANDLE, pname:buffer must: have 1179 been created without ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT set in 1180 slink:VkBufferCreateInfo::pname:flags 1181ifdef::VK_KHR_external_memory_win32[] 1182 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01876]] 1183 If pname:image is not sname:VK_NULL_HANDLE and 1184 slink:VkMemoryAllocateInfo defines a memory import operation with handle 1185 type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, 1186 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, 1187 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 1188 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, 1189 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or 1190 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the 1191 external handle was created by the Vulkan API, then the memory being 1192 imported must: also be a dedicated image allocation and pname:image must 1193 be identical to the image associated with the imported memory. 1194 * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01877]] 1195 If pname:buffer is not dlink:VK_NULL_HANDLE and 1196 slink:VkMemoryAllocateInfo defines a memory import operation with handle 1197 type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, 1198 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_KMT_BIT, 1199 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 1200 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, 1201 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or 1202 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, and the 1203 external handle was created by the Vulkan API, then the memory being 1204 imported must: also be a dedicated buffer allocation and pname:buffer 1205 must be identical to the buffer associated with the imported memory. 1206endif::VK_KHR_external_memory_win32[] 1207ifdef::VK_KHR_external_memory_fd[] 1208 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01878]] 1209 If pname:image is not sname:VK_NULL_HANDLE and 1210 slink:VkMemoryAllocateInfo defines a memory import operation with handle 1211 type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory 1212 being imported must: also be a dedicated image allocation and 1213 pname:image must be identical to the image associated with the imported 1214 memory. 1215 * [[VUID-VkMemoryDedicatedAllocateInfo-buffer-01879]] 1216 If pname:buffer is not sname:VK_NULL_HANDLE and 1217 slink:VkMemoryAllocateInfo defines a memory import operation with handle 1218 type ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT, the memory 1219 being imported must: also be a dedicated buffer allocation and 1220 pname:buffer must be identical to the buffer associated with the 1221 imported memory. 1222endif::VK_KHR_external_memory_fd[] 1223ifdef::VK_KHR_sampler_ycbcr_conversion[] 1224 * [[VUID-VkMemoryDedicatedAllocateInfo-image-01797]] 1225 If pname:image is not dlink:VK_NULL_HANDLE, pname:image must: not have 1226 been created with ename:VK_IMAGE_CREATE_DISJOINT_BIT set in 1227 slink:VkImageCreateInfo::pname:flags 1228endif::VK_KHR_sampler_ycbcr_conversion[] 1229**** 1230 1231include::../validity/structs/VkMemoryDedicatedAllocateInfo.txt[] 1232-- 1233 1234endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 1235 1236ifdef::VK_NV_dedicated_allocation[] 1237 1238[open,refpage='VkDedicatedAllocationMemoryAllocateInfoNV',desc='Specify a dedicated memory allocation resource',type='structs'] 1239-- 1240 1241If the pname:pNext chain includes a 1242sname:VkDedicatedAllocationMemoryAllocateInfoNV structure, then that 1243structure includes a handle of the sole buffer or image resource that the 1244memory can: be bound to. 1245 1246The sname:VkDedicatedAllocationMemoryAllocateInfoNV structure is defined as: 1247 1248include::../api/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[] 1249 1250 * pname:sType is the type of this structure. 1251 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1252 * pname:image is dlink:VK_NULL_HANDLE or a handle of an image which this 1253 memory will be bound to. 1254 * pname:buffer is dlink:VK_NULL_HANDLE or a handle of a buffer which this 1255 memory will be bound to. 1256 1257.Valid Usage 1258**** 1259 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00649]] 1260 At least one of pname:image and pname:buffer must: be 1261 dlink:VK_NULL_HANDLE 1262 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00650]] 1263 If pname:image is not dlink:VK_NULL_HANDLE, the image must: have been 1264 created with 1265 sname:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation 1266 equal to ename:VK_TRUE 1267 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00651]] 1268 If pname:buffer is not dlink:VK_NULL_HANDLE, the buffer must: have been 1269 created with 1270 sname:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation 1271 equal to ename:VK_TRUE 1272 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00652]] 1273 If pname:image is not dlink:VK_NULL_HANDLE, 1274 sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the 1275 sname:VkMemoryRequirements::pname:size of the image 1276 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00653]] 1277 If pname:buffer is not dlink:VK_NULL_HANDLE, 1278 sname:VkMemoryAllocateInfo::pname:allocationSize must: equal the 1279 sname:VkMemoryRequirements::pname:size of the buffer 1280ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[] 1281 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-image-00654]] 1282 If pname:image is not dlink:VK_NULL_HANDLE and 1283 slink:VkMemoryAllocateInfo defines a memory import operation, the memory 1284 being imported must: also be a dedicated image allocation and 1285 pname:image must: be identical to the image associated with the imported 1286 memory. 1287 * [[VUID-VkDedicatedAllocationMemoryAllocateInfoNV-buffer-00655]] 1288 If pname:buffer is not dlink:VK_NULL_HANDLE and 1289 slink:VkMemoryAllocateInfo defines a memory import operation, the memory 1290 being imported must: also be a dedicated buffer allocation and 1291 pname:buffer must: be identical to the buffer associated with the 1292 imported memory. 1293endif::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd[] 1294**** 1295 1296include::../validity/structs/VkDedicatedAllocationMemoryAllocateInfoNV.txt[] 1297-- 1298 1299endif::VK_NV_dedicated_allocation[] 1300 1301ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1302 1303[open,refpage='VkExportMemoryAllocateInfo',desc='Specify exportable handle types for a device memory object',type='structs'] 1304-- 1305 1306When allocating memory that may: be exported to another process or Vulkan 1307instance, add a slink:VkExportMemoryAllocateInfo structure to the 1308pname:pNext chain of the slink:VkMemoryAllocateInfo structure, specifying 1309the handle types that may: be exported. 1310 1311The slink:VkExportMemoryAllocateInfo structure is defined as: 1312 1313include::../api/structs/VkExportMemoryAllocateInfo.txt[] 1314 1315ifdef::VK_KHR_external_memory[] 1316or the equivalent 1317 1318include::../api/structs/VkExportMemoryAllocateInfoKHR.txt[] 1319endif::VK_KHR_external_memory[] 1320 1321 * pname:sType is the type of this structure. 1322 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1323 * pname:handleTypes is a bitmask of 1324 elink:VkExternalMemoryHandleTypeFlagBits specifying one or more memory 1325 handle types the application can: export from the resulting allocation. 1326 The application can: request multiple handle types for the same 1327 allocation. 1328 1329.Valid Usage 1330**** 1331 * [[VUID-VkExportMemoryAllocateInfo-handleTypes-00656]] 1332 The bits in pname:handleTypes must: be supported and compatible, as 1333 reported by slink:VkExternalImageFormatProperties or 1334 slink:VkExternalBufferProperties. 1335**** 1336 1337include::../validity/structs/VkExportMemoryAllocateInfo.txt[] 1338-- 1339 1340endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1341 1342ifdef::VK_KHR_external_memory_win32[] 1343 1344[open,refpage='VkExportMemoryWin32HandleInfoKHR',desc='Structure specifying additional attributes of Windows handles exported from a memory',type='structs'] 1345-- 1346 1347To specify additional attributes of NT handles exported from a memory 1348object, add the slink:VkExportMemoryWin32HandleInfoKHR structure to the 1349pname:pNext chain of the slink:VkMemoryAllocateInfo structure. 1350The sname:VkExportMemoryWin32HandleInfoKHR structure is defined as: 1351 1352include::../api/structs/VkExportMemoryWin32HandleInfoKHR.txt[] 1353 1354 * pname:sType is the type of this structure. 1355 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1356 * pname:pAttributes is a pointer to a Windows code:SECURITY_ATTRIBUTES 1357 structure specifying security attributes of the handle. 1358 * pname:dwAccess is a code:DWORD specifying access rights of the handle. 1359 * pname:name is a NULL-terminated UTF-16 string to associate with the 1360 underlying resource referenced by NT handles exported from the created 1361 memory. 1362 1363If this structure is not present, or if pname:pAttributes is set to `NULL`, 1364default security descriptor values will be used, and child processes created 1365by the application will not inherit the handle, as described in the MSDN 1366documentation for "`Synchronization Object Security and Access Rights`"^1^. 1367Further, if the structure is not present, the access rights will be 1368 1369code:DXGI_SHARED_RESOURCE_READ | code:DXGI_SHARED_RESOURCE_WRITE 1370 1371for handles of the following types: 1372 1373ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT 1374ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT 1375 1376And 1377 1378code:GENERIC_ALL 1379 1380for handles of the following types: 1381 1382ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT 1383ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT 1384 13851:: 1386 https://msdn.microsoft.com/en-us/library/windows/desktop/ms686670.aspx 1387 1388.Valid Usage 1389**** 1390 * [[VUID-VkExportMemoryWin32HandleInfoKHR-handleTypes-00657]] 1391 If slink:VkExportMemoryAllocateInfo::pname:handleTypes does not include 1392 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, 1393 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 1394 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or 1395 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, 1396 sname:VkExportMemoryWin32HandleInfoKHR must: not be in the pname:pNext 1397 chain of slink:VkMemoryAllocateInfo. 1398**** 1399 1400include::../validity/structs/VkExportMemoryWin32HandleInfoKHR.txt[] 1401-- 1402 1403[open,refpage='VkImportMemoryWin32HandleInfoKHR',desc='import Win32 memory created on the same physical device',type='structs'] 1404-- 1405 1406To import memory from a Windows handle, add a 1407slink:VkImportMemoryWin32HandleInfoKHR structure to the pname:pNext chain of 1408the slink:VkMemoryAllocateInfo structure. 1409 1410The sname:VkImportMemoryWin32HandleInfoKHR structure is defined as: 1411 1412include::../api/structs/VkImportMemoryWin32HandleInfoKHR.txt[] 1413 1414 * pname:sType is the type of this structure. 1415 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1416 * pname:handleType specifies the type of pname:handle or pname:name. 1417 * pname:handle is the external handle to import, or `NULL`. 1418 * pname:name is a NULL-terminated UTF-16 string naming the underlying 1419 memory resource to import, or `NULL`. 1420 1421Importing memory objects from Windows handles does not transfer ownership of 1422the handle to the Vulkan implementation. 1423For handle types defined as NT handles, the application must: release 1424ownership using the code:CloseHandle system call when the handle is no 1425longer needed. 1426 1427Applications can: import the same underlying memory into multiple instances 1428of Vulkan, into the same instance from which it was exported, and multiple 1429times into a given Vulkan instance. 1430In all cases, each import operation must: create a distinct 1431sname:VkDeviceMemory object. 1432 1433.Valid Usage 1434**** 1435 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00658]] 1436 If pname:handleType is not `0`, it must: be supported for import, as 1437 reported by slink:VkExternalImageFormatProperties or 1438 slink:VkExternalBufferProperties. 1439 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-00659]] 1440 The memory from which pname:handle was exported, or the memory named by 1441 pname:name must: have been created on the same underlying physical 1442 device as pname:device. 1443 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00660]] 1444 If pname:handleType is not `0`, it must: be defined as an NT handle or a 1445 global share handle. 1446 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01439]] 1447 If pname:handleType is not 1448 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_WIN32_BIT, 1449 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 1450 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT, or 1451 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT, pname:name 1452 must: be `NULL`. 1453 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-01440]] 1454 If pname:handleType is not `0` and pname:handle is `NULL`, pname:name 1455 must: name a valid memory resource of the type specified by 1456 pname:handleType. 1457 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handleType-00661]] 1458 If pname:handleType is not `0` and pname:name is `NULL`, pname:handle 1459 must: be a valid handle of the type specified by pname:handleType. 1460 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01441]] 1461 if pname:handle is not `NULL`, pname:name must be `NULL`. 1462 * [[VUID-VkImportMemoryWin32HandleInfoKHR-handle-01518]] 1463 If pname:handle is not `NULL`, it must: obey any requirements listed for 1464 pname:handleType in 1465 <<external-memory-handle-types-compatibility,external memory handle 1466 types compatibility>>. 1467 * [[VUID-VkImportMemoryWin32HandleInfoKHR-name-01519]] 1468 If pname:name is not `NULL`, it must: obey any requirements listed for 1469 pname:handleType in 1470 <<external-memory-handle-types-compatibility,external memory handle 1471 types compatibility>>. 1472**** 1473 1474include::../validity/structs/VkImportMemoryWin32HandleInfoKHR.txt[] 1475-- 1476 1477[open,refpage='vkGetMemoryWin32HandleKHR',desc='Get a Windows HANDLE for a memory object',type='protos'] 1478-- 1479 1480To export a Windows handle representing the underlying resources of a Vulkan 1481device memory object, call: 1482 1483include::../api/protos/vkGetMemoryWin32HandleKHR.txt[] 1484 1485 * pname:device is the logical device that created the device memory being 1486 exported. 1487 * pname:pGetWin32HandleInfo is a pointer to an instance of the 1488 slink:VkMemoryGetWin32HandleInfoKHR structure containing parameters of 1489 the export operation. 1490 * pname:pHandle will return the Windows handle representing the underlying 1491 resources of the device memory object. 1492 1493For handle types defined as NT handles, the handles returned by 1494fname:vkGetMemoryWin32HandleKHR are owned by the application. 1495To avoid leaking resources, the application must: release ownership of them 1496using the code:CloseHandle system call when they are no longer needed. 1497 1498include::../validity/protos/vkGetMemoryWin32HandleKHR.txt[] 1499-- 1500 1501[open,refpage='VkMemoryGetWin32HandleInfoKHR',desc='Structure describing a Win32 handle semaphore export operation',type='structs'] 1502-- 1503 1504The sname:VkMemoryGetWin32HandleInfoKHR structure is defined as: 1505 1506include::../api/structs/VkMemoryGetWin32HandleInfoKHR.txt[] 1507 1508 * pname:sType is the type of this structure. 1509 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1510 * pname:memory is the memory object from which the handle will be 1511 exported. 1512 * pname:handleType is the type of handle requested. 1513 1514The properties of the handle returned depend on the value of 1515pname:handleType. 1516See elink:VkExternalMemoryHandleTypeFlagBits for a description of the 1517properties of the defined external memory handle types. 1518 1519.Valid Usage 1520**** 1521 * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00662]] 1522 pname:handleType must: have been included in 1523 slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory 1524 was created. 1525 * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00663]] 1526 If pname:handleType is defined as an NT handle, 1527 flink:vkGetMemoryWin32HandleKHR must: be called no more than once for 1528 each valid unique combination of pname:memory and pname:handleType. 1529 * [[VUID-VkMemoryGetWin32HandleInfoKHR-handleType-00664]] 1530 pname:handleType must: be defined as an NT handle or a global share 1531 handle. 1532**** 1533 1534include::../validity/structs/VkMemoryGetWin32HandleInfoKHR.txt[] 1535-- 1536 1537[open,refpage='vkGetMemoryWin32HandlePropertiesKHR',desc='Get Properties of External Memory Win32 Handles',type='protos'] 1538-- 1539 1540Windows memory handles compatible with Vulkan may: also be created by 1541non-Vulkan APIs using methods beyond the scope of this specification. 1542To determine the correct parameters to use when importing such handles, 1543call: 1544 1545include::../api/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[] 1546 1547 * pname:device is the logical device that will be importing pname:handle. 1548 * pname:handleType is the type of the handle pname:handle. 1549 * pname:handle is the handle which will be imported. 1550 * pname:pMemoryWin32HandleProperties will return properties of 1551 pname:handle. 1552 1553.Valid Usage 1554**** 1555 * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handle-00665]] 1556 pname:handle must: be an external memory handle created outside of the 1557 Vulkan API. 1558 * [[VUID-vkGetMemoryWin32HandlePropertiesKHR-handleType-00666]] 1559 pname:handleType must: not be one of the handle types defined as opaque. 1560**** 1561 1562include::../validity/protos/vkGetMemoryWin32HandlePropertiesKHR.txt[] 1563 1564-- 1565 1566[open,refpage='VkMemoryWin32HandlePropertiesKHR',desc='Properties of External Memory Windows Handles',type='structs'] 1567-- 1568 1569The sname:VkMemoryWin32HandlePropertiesKHR structure returned is defined as: 1570 1571include::../api/structs/VkMemoryWin32HandlePropertiesKHR.txt[] 1572 1573 * pname:sType is the type of this structure. 1574 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1575 * pname:memoryTypeBits is a bitmask containing one bit set for every 1576 memory type which the specified windows handle can: be imported as. 1577 1578-- 1579 1580endif::VK_KHR_external_memory_win32[] 1581 1582ifdef::VK_KHR_external_memory_fd[] 1583 1584[open,refpage='VkImportMemoryFdInfoKHR',desc='import memory created on the same physical device from a file descriptor',type='structs'] 1585-- 1586 1587To import memory from a POSIX file descriptor handle, add a 1588slink:VkImportMemoryFdInfoKHR structure to the pname:pNext chain of the 1589slink:VkMemoryAllocateInfo structure. 1590The sname:VkImportMemoryFdInfoKHR structure is defined as: 1591 1592include::../api/structs/VkImportMemoryFdInfoKHR.txt[] 1593 1594 * pname:sType is the type of this structure. 1595 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1596 * pname:handleType specifies the handle type of pname:fd. 1597 * pname:fd is the external handle to import. 1598 1599Importing memory from a file descriptor transfers ownership of the file 1600descriptor from the application to the Vulkan implementation. 1601The application must: not perform any operations on the file descriptor 1602after a successful import. 1603 1604Applications can: import the same underlying memory into multiple instances 1605of Vulkan, into the same instance from which it was exported, and multiple 1606times into a given Vulkan instance. 1607In all cases, each import operation must: create a distinct 1608sname:VkDeviceMemory object. 1609 1610.Valid Usage 1611**** 1612 * [[VUID-VkImportMemoryFdInfoKHR-handleType-00667]] 1613 If pname:handleType is not `0`, it must: be supported for import, as 1614 reported by slink:VkExternalImageFormatProperties or 1615 slink:VkExternalBufferProperties. 1616 * [[VUID-VkImportMemoryFdInfoKHR-fd-00668]] 1617 The memory from which pname:fd was exported must: have been created on 1618 the same underlying physical device as pname:device. 1619 * [[VUID-VkImportMemoryFdInfoKHR-handleType-00669]] 1620 If pname:handleType is not `0`, it must: be defined as a POSIX file 1621 descriptor handle. 1622 * [[VUID-VkImportMemoryFdInfoKHR-handleType-00670]] 1623 If pname:handleType is not `0`, pname:fd must: be a valid handle of the 1624 type specified by pname:handleType. 1625 * [[VUID-VkImportMemoryFdInfoKHR-fd-01746]] 1626 The memory represented by pname:fd must: have been created from a 1627 physical device and driver that is compatible with pname:device and 1628 pname:handleType, as described in 1629 <<external-memory-handle-types-compatibility>>. 1630 * [[VUID-VkImportMemoryFdInfoKHR-fd-01520]] 1631 pname:fd must: obey any requirements listed for pname:handleType in 1632 <<external-memory-handle-types-compatibility,external memory handle 1633 types compatibility>>. 1634**** 1635 1636include::../validity/structs/VkImportMemoryFdInfoKHR.txt[] 1637-- 1638 1639[open,refpage='vkGetMemoryFdKHR',desc='Get a POSIX file descriptor for a memory object',type='protos'] 1640-- 1641 1642To export a POSIX file descriptor representing the underlying resources of a 1643Vulkan device memory object, call: 1644 1645include::../api/protos/vkGetMemoryFdKHR.txt[] 1646 1647 * pname:device is the logical device that created the device memory being 1648 exported. 1649 * pname:pGetFdInfo is a pointer to an instance of the 1650 slink:VkMemoryGetFdInfoKHR structure containing parameters of the export 1651 operation. 1652 * pname:pFd will return a file descriptor representing the underlying 1653 resources of the device memory object. 1654 1655Each call to fname:vkGetMemoryFdKHR must: create a new file descriptor and 1656transfer ownership of it to the application. 1657To avoid leaking resources, the application must: release ownership of the 1658file descriptor using the code:close system call when it is no longer 1659needed, or by importing a Vulkan memory object from it. 1660Where supported by the operating system, the implementation must: set the 1661file descriptor to be closed automatically when an code:execve system call 1662is made. 1663 1664include::../validity/protos/vkGetMemoryFdKHR.txt[] 1665-- 1666 1667[open,refpage='VkMemoryGetFdInfoKHR',desc='Structure describing a POSIX FD semaphore export operation',type='structs'] 1668-- 1669 1670The sname:VkMemoryGetFdInfoKHR structure is defined as: 1671 1672include::../api/structs/VkMemoryGetFdInfoKHR.txt[] 1673 1674 * pname:sType is the type of this structure. 1675 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1676 * pname:memory is the memory object from which the handle will be 1677 exported. 1678 * pname:handleType is the type of handle requested. 1679 1680The properties of the file descriptor exported depend on the value of 1681pname:handleType. 1682See elink:VkExternalMemoryHandleTypeFlagBits for a description of the 1683properties of the defined external memory handle types. 1684 1685ifdef::VK_EXT_external_memory_dma_buf[] 1686[NOTE] 1687.Note 1688==== 1689The size of the exported file may: be larger than the size requested by 1690slink:VkMemoryAllocateInfo::allocationSize. 1691If pname:handleType is ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT, 1692then the application can: query the file's actual size with 1693link:man:lseek(2)[lseek(2)]. 1694==== 1695endif::VK_EXT_external_memory_dma_buf[] 1696 1697.Valid Usage 1698**** 1699 * [[VUID-VkMemoryGetFdInfoKHR-handleType-00671]] 1700 pname:handleType must: have been included in 1701 slink:VkExportMemoryAllocateInfo::pname:handleTypes when pname:memory 1702 was created. 1703 * [[VUID-VkMemoryGetFdInfoKHR-handleType-00672]] 1704 pname:handleType must: be defined as a POSIX file descriptor handle. 1705**** 1706 1707include::../validity/structs/VkMemoryGetFdInfoKHR.txt[] 1708-- 1709 1710[open,refpage='vkGetMemoryFdPropertiesKHR',desc='Get Properties of External Memory File Descriptors',type='protos'] 1711-- 1712 1713POSIX file descriptor memory handles compatible with Vulkan may: also be 1714created by non-Vulkan APIs using methods beyond the scope of this 1715specification. 1716To determine the correct parameters to use when importing such handles, 1717call: 1718 1719include::../api/protos/vkGetMemoryFdPropertiesKHR.txt[] 1720 1721 * pname:device is the logical device that will be importing pname:fd. 1722 * pname:handleType is the type of the handle pname:fd. 1723 * pname:fd is the handle which will be imported. 1724 * pname:pMemoryFdProperties will return properties of the handle pname:fd. 1725 1726.Valid Usage 1727**** 1728 * [[VUID-vkGetMemoryFdPropertiesKHR-fd-00673]] 1729 pname:fd must: be an external memory handle created outside of the 1730 Vulkan API. 1731 * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]] 1732 pname:handleType must: not be 1733 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR. 1734**** 1735 1736include::../validity/protos/vkGetMemoryFdPropertiesKHR.txt[] 1737 1738-- 1739 1740[open,refpage='VkMemoryFdPropertiesKHR',desc='Properties of External Memory File Descriptors',type='structs'] 1741-- 1742 1743The sname:VkMemoryFdPropertiesKHR structure returned is defined as: 1744 1745include::../api/structs/VkMemoryFdPropertiesKHR.txt[] 1746 1747 * pname:sType is the type of this structure. 1748 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1749 * pname:memoryTypeBits is a bitmask containing one bit set for every 1750 memory type which the specified file descriptor can: be imported as. 1751 1752-- 1753 1754endif::VK_KHR_external_memory_fd[] 1755 1756ifdef::VK_EXT_external_memory_host[] 1757 1758[open,refpage='VkImportMemoryHostPointerInfoEXT',desc='import memory from a host pointer',type='structs'] 1759-- 1760 1761To import memory from a host pointer, add a 1762slink:VkImportMemoryHostPointerInfoEXT structure to the pname:pNext chain of 1763the slink:VkMemoryAllocateInfo structure. 1764The sname:VkImportMemoryHostPointerInfoEXT structure is defined as: 1765 1766include::../api/structs/VkImportMemoryHostPointerInfoEXT.txt[] 1767 1768 * pname:sType is the type of this structure. 1769 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1770 * pname:handleType specifies the handle type. 1771 * pname:pHostPointer is the host pointer to import from. 1772 1773Importing memory from a host pointer shares ownership of the memory between 1774the host and the Vulkan implementation. 1775The application can: continue to access the memory through the host pointer 1776but it is the application's responsibility to synchronize device and 1777non-device access to the underlying memory as defined in 1778<<memory-device-hostaccess,Host Access to Device Memory Objects>>. 1779 1780Applications can: import the same underlying memory into multiple instances 1781of Vulkan and multiple times into a given Vulkan instance. 1782However, implementations may: fail to import the same underlying memory 1783multiple times into a given physical device due to platform constraints. 1784 1785Importing memory from a particular host pointer may: not be possible due to 1786additional platform-specific restrictions beyond the scope of this 1787specification in which case the implementation must: fail the memory import 1788operation with the error code ename:VK_ERROR_INVALID_EXTERNAL_HANDLE_KHR. 1789 1790The application must: ensure that the imported memory range remains valid 1791and accessible for the lifetime of the imported memory object. 1792 1793.Valid Usage 1794**** 1795 * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01747]] 1796 If pname:handleType is not `0`, it must: be supported for import, as 1797 reported in slink:VkExternalMemoryPropertiesKHR 1798 * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01748]] 1799 If pname:handleType is not `0`, it must: be 1800 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or 1801 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT 1802 * [[VUID-VkImportMemoryHostPointerInfoEXT-pHostPointer-01749]] 1803 pname:pHostPointer must: be a pointer aligned to an integer multiple of 1804 sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment 1805 * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01750]] 1806 If pname:handleType is 1807 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, 1808 pname:pHostPointer must: be a pointer to pname:allocationSize number of 1809 bytes of host memory, where pname:allocationSize is the member of the 1810 sname:VkMemoryAllocateInfo structure this structure is chained to 1811 * [[VUID-VkImportMemoryHostPointerInfoEXT-handleType-01751]] 1812 If pname:handleType is 1813 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, 1814 pname:pHostPointer must: be a pointer to pname:allocationSize number of 1815 bytes of host mapped foreign memory, where pname:allocationSize is the 1816 member of the sname:VkMemoryAllocateInfo structure this structure is 1817 chained to 1818**** 1819 1820include::../validity/structs/VkImportMemoryHostPointerInfoEXT.txt[] 1821 1822-- 1823 1824[open,refpage='vkGetMemoryHostPointerPropertiesEXT',desc='Get properties of external memory host pointer',type='protos'] 1825-- 1826 1827To determine the correct parameters to use when importing host pointers, 1828call: 1829 1830include::../api/protos/vkGetMemoryHostPointerPropertiesEXT.txt[] 1831 1832 * pname:device is the logical device that will be importing 1833 pname:pHostPointer. 1834 * pname:handleType is the type of the handle pname:pHostPointer. 1835 * pname:pHostPointer is the host pointer to import from. 1836 1837.Valid Usage 1838**** 1839 * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01752]] 1840 pname:handleType must: be 1841 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or 1842 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT 1843 * [[VUID-vkGetMemoryHostPointerPropertiesEXT-pHostPointer-01753]] 1844 pname:pHostPointer must: be a pointer aligned to an integer multiple of 1845 sname:VkPhysicalDeviceExternalMemoryHostPropertiesEXT::pname:minImportedHostPointerAlignment 1846 * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01754]] 1847 If pname:handleType is 1848 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, 1849 pname:pHostPointer must: be a pointer to host memory 1850 * [[VUID-vkGetMemoryHostPointerPropertiesEXT-handleType-01755]] 1851 If pname:handleType is 1852 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, 1853 pname:pHostPointer must: be a pointer to host mapped foreign memory 1854**** 1855 1856include::../validity/protos/vkGetMemoryHostPointerPropertiesEXT.txt[] 1857 1858-- 1859 1860[open,refpage='VkMemoryHostPointerPropertiesEXT',desc'Properties of external memory host pointer',type='structs'] 1861-- 1862 1863The sname:VkMemoryHostPointerPropertiesEXT structure is defined as: 1864 1865include::../api/structs/VkMemoryHostPointerPropertiesEXT.txt[] 1866 1867 * pname:sType is the type of this structure. 1868 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1869 * pname:memoryTypeBits is a bitmask containing one bit set for every 1870 memory type which the specified host pointer can: be imported as. 1871 1872include::../validity/structs/VkMemoryHostPointerPropertiesEXT.txt[] 1873 1874-- 1875 1876endif::VK_EXT_external_memory_host[] 1877 1878ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1879 1880[open,refpage='VkImportAndroidHardwareBufferInfoANDROID',desc='Import memory from an Android hardware buffer',type='structs'] 1881-- 1882 1883To import memory created outside of the current Vulkan instance from an 1884Android hardware buffer, add a 1885sname:VkImportAndroidHardwareBufferInfoANDROID structure to the pname:pNext 1886chain of the slink:VkMemoryAllocateInfo structure. 1887The sname:VkImportAndroidHardwareBufferInfoANDROID structure is defined as: 1888 1889include::../api/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] 1890 1891 * pname:sType is the type of this structure. 1892 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1893 * pname:buffer is the Android hardware buffer to import. 1894 1895If the flink:vkAllocateMemory command succeeds, the implementation must: 1896acquire a reference to the imported hardware buffer, which it must: release 1897when the device memory object is freed. 1898If the command fails, the implementation must: not retain a reference. 1899 1900.Valid Usage 1901**** 1902 * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01880]] 1903 If pname:buffer is not `NULL`, Android hardware buffers must: be 1904 supported for import, as reported by 1905 slink:VkExternalImageFormatProperties or 1906 slink:VkExternalBufferProperties. 1907 * [[VUID-VkImportAndroidHardwareBufferInfoANDROID-buffer-01881]] 1908 If pname:buffer is not `NULL`, it must: be a valid Android hardware 1909 buffer object with format and usage compatible with Vulkan as described 1910 by elink:VkExternalMemoryHandleTypeFlagBits. 1911**** 1912 1913include::../validity/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] 1914 1915-- 1916 1917[open,refpage='vkGetMemoryAndroidHardwareBufferANDROID',desc='Get an Android hardware buffer for a memory object',type='protos'] 1918-- 1919 1920To export an Android hardware buffer representing the underlying resources 1921of a Vulkan device memory object, call: 1922 1923include::../api/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[] 1924 1925 * pname:device is the logical device that created the device memory being 1926 exported. 1927 * pname:pInfo is a pointer to an instance of the 1928 slink:VkMemoryGetAndroidHardwareBufferInfoANDROID structure containing 1929 parameters of the export operation. 1930 * pname:pBuffer will return an Android hardware buffer representing the 1931 underlying resources of the device memory object. 1932 1933Each call to fname:vkGetMemoryAndroidHardwareBufferANDROID must: return an 1934Android hardware buffer with a new reference acquired in addition to the 1935reference held by the slink:VkDeviceMemory. 1936To avoid leaking resources, the application must: release the reference by 1937calling code:AHardwareBuffer_release when it is no longer needed. 1938When called with the same handle in 1939slink:VkMemoryGetAndroidHardwareBufferInfoANDROID::pname:memory, 1940fname:vkGetMemoryAndroidHardwareBufferANDROID must: return the same Android 1941hardware buffer object. 1942If the device memory was created by importing an Android hardware buffer, 1943fname:vkGetMemoryAndroidHardwareBufferANDROID must: return that same Android 1944hardware buffer object. 1945 1946include::../validity/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[] 1947 1948-- 1949 1950[open,refpage='VkMemoryGetAndroidHardwareBufferInfoANDROID',desc='Structure describing an Android hardware buffer memory export operation',type='structs'] 1951-- 1952 1953The sname:VkMemoryGetAndroidHardwareBufferInfoANDROID structure is defined 1954as: 1955 1956include::../api/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[] 1957 1958 * pname:sType is the type of this structure. 1959 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1960 * pname:memory is the memory object from which the Android hardware buffer 1961 will be exported. 1962 1963.Valid Usage 1964**** 1965 * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-handleTypes-01882]] 1966 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 1967 must: have been included in 1968 slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes when pname:memory 1969 was created. 1970 * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-01883]] 1971 If the pname:pNext chain of the slink:VkMemoryAllocateInfo used to 1972 allocate pname:memory included a slink:VkMemoryDedicatedAllocateInfo 1973 with non-`NULL` pname:image member, then that pname:image must: already 1974 be bound to pname:memory. 1975**** 1976 1977-- 1978 1979[open,refpage='vkGetAndroidHardwareBufferPropertiesANDROID',desc='Get Properties of External Memory Android Hardware Buffers',type='protos'] 1980-- 1981 1982To determine the memory parameters to use when importing an Android hardware 1983buffer, call: 1984 1985include::../api/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] 1986 1987 * pname:device is the logical device that will be importing pname:buffer. 1988 * pname:buffer is the Android hardware buffer which will be imported. 1989 * pname:pProperties will return properties of pname:buffer. 1990 1991.Valid Usage 1992**** 1993 * [[VUID-vkGetAndroidHardwareBufferPropertiesANDROID-buffer-01884]] 1994 pname:buffer must: be a valid Android hardware buffer object with at 1995 least one of the code:AHARDWAREBUFFER_USAGE_GPU_* usage flags. 1996**** 1997 1998include::../validity/protos/vkGetAndroidHardwareBufferPropertiesANDROID.txt[] 1999 2000-- 2001 2002[open,refpage='VkAndroidHardwareBufferPropertiesANDROID',desc='Properties of External Memory Android Hardware Buffers',type='structs'] 2003-- 2004 2005The sname:VkAndroidHardwareBufferPropertiesANDROID structure returned is 2006defined as: 2007 2008include::../api/structs/VkAndroidHardwareBufferPropertiesANDROID.txt[] 2009 2010 * pname:sType is the type of this structure. 2011 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2012 * pname:allocationSize is the size of the external memory 2013 * pname:memoryTypeBits is a bitmask containing one bit set for every 2014 memory type which the specified Android hardware buffer can: be imported 2015 as. 2016 2017-- 2018 2019[open,refpage='VkAndroidHardwareBufferFormatPropertiesANDROID',desc='Structure describing the image format properties of an Android hardware buffer',type='structs'] 2020-- 2021To obtain format properties of an Android hardware buffer, include an 2022instance of sname:VkAndroidHardwareBufferFormatPropertiesANDROID in the 2023pname:pNext chain of the slink:VkAndroidHardwareBufferPropertiesANDROID 2024instance passed to flink:vkGetAndroidHardwareBufferPropertiesANDROID. 2025This structure is defined as: 2026 2027include::../api/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[] 2028 2029 * pname:sType is the type of this structure. 2030 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2031 * pname:format is the Vulkan format corresponding to the Android hardware 2032 buffer's format, or ename:VK_FORMAT_UNDEFINED if there is not an 2033 equivalent Vulkan format. 2034 * pname:externalFormat is an implementation-defined external format 2035 identifier for use with slink:VkExternalFormatANDROID. 2036 It must: not be zero. 2037 * pname:formatFeatures describes the capabilities of this external format 2038 when used with an image bound to memory imported from pname:buffer. 2039 * pname:samplerYcbcrConversionComponents is the component swizzle that 2040 should: be used in slink:VkSamplerYcbcrConversionCreateInfo. 2041 * pname:suggestedYcbcrModel is a suggested color model to use in the 2042 slink:VkSamplerYcbcrConversionCreateInfo. 2043 * pname:suggestedYcbcrRange is a suggested numerical value range to use in 2044 slink:VkSamplerYcbcrConversionCreateInfo. 2045 * pname:suggestedXChromaOffset is a suggested X chroma offset to use in 2046 slink:VkSamplerYcbcrConversionCreateInfo. 2047 * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in 2048 slink:VkSamplerYcbcrConversionCreateInfo. 2049 2050If the Android hardware buffer has one of the formats listed in the 2051<<memory-external-android-hardware-buffer-formats,Format Equivalence 2052table>>, then pname:format must: have the equivalent Vulkan format listed in 2053the table. 2054Otherwise, pname:format may: be ename:VK_FORMAT_UNDEFINED, indicating the 2055Android hardware buffer can: only be used with an external format. 2056 2057The pname:formatFeatures member must: include 2058ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and at least one of 2059ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or 2060ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, and should: include 2061ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and 2062ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT. 2063 2064[NOTE] 2065.Note 2066==== 2067The pname:formatFeatures member only indicates the features available when 2068using an 2069<<memory-external-android-hardware-buffer-external-formats,external-format 2070image>> created from the Android hardware buffer. 2071Images from Android hardware buffers with a format other than 2072ename:VK_FORMAT_UNDEFINED are subject to the format capabilities obtained 2073from flink:vkGetPhysicalDeviceFormatProperties2, and 2074flink:vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters. 2075These sets of features are independent of each other, e.g. the external 2076format will support sampler Y'C~B~C~R~ conversion even if the non-external 2077format does not, and writing to non-external format images is possible but 2078writing to external format images is not. 2079==== 2080 2081Android hardware buffers with the same external format must: have the same 2082support for ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT, 2083ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, 2084ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, 2085ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, 2086ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, 2087and 2088ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT. 2089in pname:formatFeatures. 2090Other format features may: differ between Android hardware buffers that have 2091the same external format. 2092This allows applications to use the same slink:VkSamplerYcbcrConversion 2093object (and samplers and pipelines created from them) for any Android 2094hardware buffers that have the same external format. 2095 2096If pname:format is not ename:VK_FORMAT_UNDEFINED, then the value of 2097pname:samplerYcbcrConversionComponents must: be valid when used as the 2098pname:components member of slink:VkSamplerYcbcrConversionCreateInfo with 2099that format. 2100If pname:format is ename:VK_FORMAT_UNDEFINED, all members of 2101pname:samplerYcbcrConversionComponents must: be 2102ename:VK_COMPONENT_SWIZZLE_IDENTITY. 2103 2104Implementations may: not always be able to determine the color model, 2105numerical range, or chroma offsets of the image contents, so the values in 2106sname:VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions. 2107Applications should: treat these values as sensible defaults to use in the 2108absence of more reliable information obtained through some other means. 2109If the underlying physical device is also usable via OpenGL ES with the 2110https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] 2111extension, the implementation should: suggest values that will produce 2112similar sampled values as would be obtained by sampling the same external 2113image via code:samplerExternalOES in OpenGL ES using equivalent sampler 2114parameters. 2115 2116[NOTE] 2117.Note 2118==== 2119Since 2120https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] 2121does not require the same sampling and conversion calculations as Vulkan 2122does, achieving identical results between APIs may: not be possible on some 2123implementations. 2124==== 2125 2126include::../validity/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[] 2127-- 2128 2129endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2130 2131ifdef::VK_NV_external_memory[] 2132include::VK_NV_external_memory/allocate_memory.txt[] 2133endif::VK_NV_external_memory[] 2134 2135ifdef::VK_NV_external_memory_win32[] 2136 2137include::VK_NV_external_memory_win32/handle_permissions.txt[] 2138 2139include::VK_NV_external_memory_win32/import_memory_win32.txt[] 2140 2141include::VK_NV_external_memory_win32/get_handle_win32.txt[] 2142 2143endif::VK_NV_external_memory_win32[] 2144 2145ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2146 2147[open,refpage='VkMemoryAllocateFlagsInfo',desc='Structure controlling how many instances of memory will be allocated',type='structs'] 2148-- 2149 2150If the pname:pNext chain of slink:VkMemoryAllocateInfo includes a 2151sname:VkMemoryAllocateFlagsInfo structure, then that structure includes 2152flags and a device mask controlling how many instances of the memory will be 2153allocated. 2154 2155The sname:VkMemoryAllocateFlagsInfo structure is defined as: 2156 2157include::../api/structs/VkMemoryAllocateFlagsInfo.txt[] 2158 2159ifdef::VK_KHR_device_group[] 2160or the equivalent 2161 2162include::../api/structs/VkMemoryAllocateFlagsInfoKHR.txt[] 2163endif::VK_KHR_device_group[] 2164 2165 * pname:sType is the type of this structure. 2166 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2167 * pname:flags is a bitmask of elink:VkMemoryAllocateFlagBits controlling 2168 the allocation. 2169 * pname:deviceMask is a mask of physical devices in the logical device, 2170 indicating that memory must: be allocated on each device in the mask, if 2171 ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set in pname:flags. 2172 2173If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is not set, the number of 2174instances allocated depends on whether 2175ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set in the memory heap. 2176If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is set, then memory is allocated 2177for every physical device in the logical device (as if pname:deviceMask has 2178bits set for all device indices). 2179If ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT is not set, then a single 2180instance of memory is allocated (as if pname:deviceMask is set to one). 2181 2182On some implementations, allocations from a multi-instance heap may: consume 2183memory on all physical devices even if the pname:deviceMask excludes some 2184devices. 2185If slink:VkPhysicalDeviceGroupProperties::pname:subsetAllocation is 2186ename:VK_TRUE, then memory is only consumed for the devices in the device 2187mask. 2188 2189[NOTE] 2190.Note 2191==== 2192In practice, most allocations on a multi-instance heap will be allocated 2193across all physical devices. 2194Unicast allocation support is an optional optimization for a minority of 2195allocations. 2196==== 2197 2198.Valid Usage 2199**** 2200 * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00675]] 2201 If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask 2202 must: be a valid device mask. 2203 * [[VUID-VkMemoryAllocateFlagsInfo-deviceMask-00676]] 2204 If ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT is set, pname:deviceMask 2205 must: not be zero 2206**** 2207 2208include::../validity/structs/VkMemoryAllocateFlagsInfo.txt[] 2209-- 2210 2211[open,refpage='VkMemoryAllocateFlagBits',desc='Bitmask specifying flags for a device memory allocation',type='enums'] 2212-- 2213 2214Bits which can: be set in slink:VkMemoryAllocateFlagsInfo::pname:flags, 2215controlling device memory allocation, are: 2216 2217include::../api/enums/VkMemoryAllocateFlagBits.txt[] 2218 2219ifdef::VK_KHR_device_group[] 2220or the equivalent 2221 2222include::../api/enums/VkMemoryAllocateFlagBitsKHR.txt[] 2223endif::VK_KHR_device_group[] 2224 2225 * ename:VK_MEMORY_ALLOCATE_DEVICE_MASK_BIT specifies that memory will be 2226 allocated for the devices in 2227 slink:VkMemoryAllocateFlagsInfo::pname:deviceMask. 2228 2229-- 2230 2231[open,refpage='VkMemoryAllocateFlags',desc='Bitmask of VkMemoryAllocateFlagBits',type='enums'] 2232-- 2233include::../api/flags/VkMemoryAllocateFlags.txt[] 2234 2235ifdef::VK_KHR_device_group[] 2236or the equivalent 2237 2238include::../api/flags/VkMemoryAllocateFlagsKHR.txt[] 2239endif::VK_KHR_device_group[] 2240 2241sname:VkMemoryAllocateFlags is a bitmask type for setting a mask of zero or 2242more slink:VkMemoryAllocateFlagBits. 2243-- 2244 2245endif::VK_VERSION_1_1,VK_KHR_device_group[] 2246 2247[open,refpage='vkFreeMemory',desc='Free device memory',type='protos'] 2248-- 2249 2250To free a memory object, call: 2251 2252include::../api/protos/vkFreeMemory.txt[] 2253 2254 * pname:device is the logical device that owns the memory. 2255 * pname:memory is the slink:VkDeviceMemory object to be freed. 2256 * pname:pAllocator controls host memory allocation as described in the 2257 <<memory-allocation, Memory Allocation>> chapter. 2258 2259Before freeing a memory object, an application must: ensure the memory 2260object is no longer in use by the device--for example by command buffers in 2261the _pending state_. 2262The memory can: remain bound to images or buffers at the time the memory 2263object is freed, but any further use of them (on host or device) for 2264anything other than destroying those objects will result in undefined 2265behavior. 2266If there are still any bound images or buffers, the memory may: not be 2267immediately released by the implementation, but must: be released by the 2268time all bound images and buffers have been destroyed. 2269Once memory is released, it is returned to the heap from which it was 2270allocated. 2271 2272How memory objects are bound to Images and Buffers is described in detail in 2273the <<resources-association, Resource Memory Association>> section. 2274 2275If a memory object is mapped at the time it is freed, it is implicitly 2276unmapped. 2277 2278[NOTE] 2279.Note 2280==== 2281As described <<memory-device-unmap-does-not-flush, below>>, host writes are 2282not implicitly flushed when the memory object is unmapped, but the 2283implementation must: guarantee that writes that have not been flushed do not 2284affect any other memory. 2285==== 2286 2287.Valid Usage 2288**** 2289 * [[VUID-vkFreeMemory-memory-00677]] 2290 All submitted commands that refer to pname:memory (via images or 2291 buffers) must: have completed execution 2292**** 2293 2294include::../validity/protos/vkFreeMemory.txt[] 2295-- 2296 2297 2298[[memory-device-hostaccess]] 2299=== Host Access to Device Memory Objects 2300 2301Memory objects created with flink:vkAllocateMemory are not directly host 2302accessible. 2303 2304Memory objects created with the memory property 2305ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT are considered _mappable_. 2306Memory objects must: be mappable in order to be successfully mapped on the 2307host. 2308 2309[open,refpage='vkMapMemory',desc='Map a memory object into application address space',type='protos'] 2310-- 2311 2312To retrieve a host virtual address pointer to a region of a mappable memory 2313object, call: 2314 2315include::../api/protos/vkMapMemory.txt[] 2316 2317 * pname:device is the logical device that owns the memory. 2318 * pname:memory is the slink:VkDeviceMemory object to be mapped. 2319 * pname:offset is a zero-based byte offset from the beginning of the 2320 memory object. 2321 * pname:size is the size of the memory range to map, or 2322 ename:VK_WHOLE_SIZE to map from pname:offset to the end of the 2323 allocation. 2324 * pname:flags is reserved for future use. 2325 * pname:ppData points to a pointer in which is returned a host-accessible 2326 pointer to the beginning of the mapped range. 2327 This pointer minus pname:offset must: be aligned to at least 2328 slink:VkPhysicalDeviceLimits::pname:minMemoryMapAlignment. 2329 2330It is an application error to call fname:vkMapMemory on a memory object that 2331is already mapped. 2332 2333[NOTE] 2334.Note 2335==== 2336fname:vkMapMemory will fail if the implementation is unable to allocate an 2337appropriately sized contiguous virtual address range, e.g. due to virtual 2338address space fragmentation or platform limits. 2339In such cases, fname:vkMapMemory must: return 2340ename:VK_ERROR_MEMORY_MAP_FAILED. 2341The application can: improve the likelihood of success by reducing the size 2342of the mapped range and/or removing unneeded mappings using 2343fname:VkUnmapMemory. 2344==== 2345 2346[[memory-device-hostaccess-hazards]] 2347fname:vkMapMemory does not check whether the device memory is currently in 2348use before returning the host-accessible pointer. 2349The application must: guarantee that any previously submitted command that 2350writes to this range has completed before the host reads from or writes to 2351that range, and that any previously submitted command that reads from that 2352range has completed before the host writes to that region (see 2353<<synchronization-submission-host-writes, here>> for details on fulfilling 2354such a guarantee). 2355If the device memory was allocated without the 2356ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, these guarantees must: be 2357made for an extended range: the application must: round down the start of 2358the range to the nearest multiple of 2359slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, and round the end 2360of the range up to the nearest multiple of 2361slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize. 2362 2363While a range of device memory is mapped for host access, the application is 2364responsible for synchronizing both device and host access to that memory 2365range. 2366 2367[NOTE] 2368.Note 2369==== 2370It is important for the application developer to become meticulously 2371familiar with all of the mechanisms described in the chapter on 2372<<synchronization, Synchronization and Cache Control>> as they are crucial 2373to maintaining memory access ordering. 2374==== 2375 2376.Valid Usage 2377**** 2378 * [[VUID-vkMapMemory-memory-00678]] 2379 pname:memory must: not be currently mapped 2380 * [[VUID-vkMapMemory-offset-00679]] 2381 pname:offset must: be less than the size of pname:memory 2382 * [[VUID-vkMapMemory-size-00680]] 2383 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be 2384 greater than `0` 2385 * [[VUID-vkMapMemory-size-00681]] 2386 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: be 2387 less than or equal to the size of the pname:memory minus pname:offset 2388 * [[VUID-vkMapMemory-memory-00682]] 2389 pname:memory must: have been created with a memory type that reports 2390 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT 2391ifdef::VK_KHR_device_group[] 2392 * [[VUID-vkMapMemory-memory-00683]] 2393 pname:memory must: not have been allocated with multiple instances. 2394endif::VK_KHR_device_group[] 2395**** 2396 2397include::../validity/protos/vkMapMemory.txt[] 2398-- 2399 2400[open,refpage='VkMemoryMapFlags',desc='Reserved for future use',type='enums'] 2401-- 2402include::../api/flags/VkMemoryMapFlags.txt[] 2403 2404sname:VkMemoryMapFlags is a bitmask type for setting a mask, but is 2405currently reserved for future use. 2406-- 2407 2408Two commands are provided to enable applications to work with non-coherent 2409memory allocations: fname:vkFlushMappedMemoryRanges and 2410fname:vkInvalidateMappedMemoryRanges. 2411 2412[NOTE] 2413.Note 2414==== 2415If the memory object was created with the 2416ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT set, 2417fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are 2418unnecessary and may: have a performance cost. 2419However, <<synchronization-dependencies-available-and-visible, availability 2420and visibility operations>> still need to be managed on the device. 2421See the description of <<synchronization-host-access-types, host access 2422types>> for more information. 2423==== 2424 2425[open,refpage='vkFlushMappedMemoryRanges',desc='Flush mapped memory ranges',type='protos'] 2426-- 2427 2428To flush ranges of non-coherent memory from the host caches, call: 2429 2430include::../api/protos/vkFlushMappedMemoryRanges.txt[] 2431 2432 * pname:device is the logical device that owns the memory ranges. 2433 * pname:memoryRangeCount is the length of the pname:pMemoryRanges array. 2434 * pname:pMemoryRanges is a pointer to an array of 2435 slink:VkMappedMemoryRange structures describing the memory ranges to 2436 flush. 2437 2438fname:vkFlushMappedMemoryRanges guarantees that host writes to the memory 2439ranges described by pname:pMemoryRanges can: be made available to device 2440access, via <<synchronization-dependencies-available-and-visible, 2441availability operations>> from the ename:VK_ACCESS_HOST_WRITE_BIT 2442<<synchronization-access-types,access type>>. 2443 2444Within each range described by pname:pMemoryRanges, each set of 2445pname:nonCoherentAtomSize bytes in that range is flushed if any byte in that 2446set has been written by the host since it was first mapped, or the last time 2447it was flushed. 2448If pname:pMemoryRanges includes sets of pname:nonCoherentAtomSize bytes 2449where no bytes have been written by the host, those bytes must: not be 2450flushed. 2451 2452[[memory-device-unmap-does-not-flush]] 2453Unmapping non-coherent memory does not implicitly flush the mapped memory, 2454and host writes that have not been flushed may: not ever be visible to the 2455device. 2456However, implementations must: ensure that writes that have not been flushed 2457do not become visible to any other memory. 2458 2459[NOTE] 2460.Note 2461==== 2462The above guarantee avoids a potential memory corruption in scenarios where 2463host writes to a mapped memory object have not been flushed before the 2464memory is unmapped (or freed), and the virtual address range is subsequently 2465reused for a different mapping (or memory allocation). 2466==== 2467 2468include::../validity/protos/vkFlushMappedMemoryRanges.txt[] 2469-- 2470 2471[open,refpage='vkInvalidateMappedMemoryRanges',desc='Invalidate ranges of mapped memory objects',type='protos'] 2472-- 2473 2474To invalidate ranges of non-coherent memory from the host caches, call: 2475 2476include::../api/protos/vkInvalidateMappedMemoryRanges.txt[] 2477 2478 * pname:device is the logical device that owns the memory ranges. 2479 * pname:memoryRangeCount is the length of the pname:pMemoryRanges array. 2480 * pname:pMemoryRanges is a pointer to an array of 2481 slink:VkMappedMemoryRange structures describing the memory ranges to 2482 invalidate. 2483 2484fname:vkInvalidateMappedMemoryRanges guarantees that device writes to the 2485memory ranges described by pname:pMemoryRanges, which have been made visible 2486to the ename:VK_ACCESS_HOST_WRITE_BIT and ename:VK_ACCESS_HOST_READ_BIT 2487<<synchronization-access-types, access types>>, are made visible to the 2488host. 2489If a range of non-coherent memory is written by the host and then 2490invalidated without first being flushed, its contents are undefined. 2491 2492Within each range described by pname:pMemoryRanges, each set of 2493pname:nonCoherentAtomSize bytes in that range is invalidated if any byte in 2494that set has been written by the device since it was first mapped, or the 2495last time it was invalidated. 2496 2497[NOTE] 2498.Note 2499==== 2500Mapping non-coherent memory does not implicitly invalidate the mapped 2501memory, and device writes that have not been invalidated must: be made 2502visible before the host reads or overwrites them. 2503==== 2504 2505include::../validity/protos/vkInvalidateMappedMemoryRanges.txt[] 2506-- 2507 2508[open,refpage='VkMappedMemoryRange',desc='Structure specifying a mapped memory range',type='structs'] 2509-- 2510 2511The sname:VkMappedMemoryRange structure is defined as: 2512 2513include::../api/structs/VkMappedMemoryRange.txt[] 2514 2515 * pname:sType is the type of this structure. 2516 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2517 * pname:memory is the memory object to which this range belongs. 2518 * pname:offset is the zero-based byte offset from the beginning of the 2519 memory object. 2520 * pname:size is either the size of range, or ename:VK_WHOLE_SIZE to affect 2521 the range from pname:offset to the end of the current mapping of the 2522 allocation. 2523 2524.Valid Usage 2525**** 2526 * [[VUID-VkMappedMemoryRange-memory-00684]] 2527 pname:memory must: be currently mapped 2528 * [[VUID-VkMappedMemoryRange-size-00685]] 2529 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:offset and 2530 pname:size must: specify a range contained within the currently mapped 2531 range of pname:memory 2532 * [[VUID-VkMappedMemoryRange-size-00686]] 2533 If pname:size is equal to ename:VK_WHOLE_SIZE, pname:offset must: be 2534 within the currently mapped range of pname:memory 2535 * [[VUID-VkMappedMemoryRange-size-01389]] 2536 If pname:size is equal to ename:VK_WHOLE_SIZE, the end of the current 2537 mapping of pname:memory must: be a multiple of 2538 slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize bytes from the 2539 beginning of the memory object. 2540 * [[VUID-VkMappedMemoryRange-offset-00687]] 2541 pname:offset must: be a multiple of 2542 slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize 2543 * [[VUID-VkMappedMemoryRange-size-01390]] 2544 If pname:size is not equal to ename:VK_WHOLE_SIZE, pname:size must: 2545 either be a multiple of 2546 slink:VkPhysicalDeviceLimits::pname:nonCoherentAtomSize, or pname:offset 2547 plus pname:size must: equal the size of pname:memory. 2548**** 2549 2550include::../validity/structs/VkMappedMemoryRange.txt[] 2551-- 2552 2553 2554[open,refpage='vkUnmapMemory',desc='Unmap a previously mapped memory object',type='protos'] 2555-- 2556 2557To unmap a memory object once host access to it is no longer needed by the 2558application, call: 2559 2560include::../api/protos/vkUnmapMemory.txt[] 2561 2562 * pname:device is the logical device that owns the memory. 2563 * pname:memory is the memory object to be unmapped. 2564 2565.Valid Usage 2566**** 2567 * [[VUID-vkUnmapMemory-memory-00689]] 2568 pname:memory must: be currently mapped 2569**** 2570 2571include::../validity/protos/vkUnmapMemory.txt[] 2572-- 2573 2574 2575[[memory-device-lazy_allocation]] 2576=== Lazily Allocated Memory 2577 2578If the memory object is allocated from a heap with the 2579ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set, that object's backing 2580memory may: be provided by the implementation lazily. 2581The actual committed size of the memory may: initially be as small as zero 2582(or as large as the requested size), and monotonically increases as 2583additional memory is needed. 2584 2585A memory type with this flag set is only allowed to be bound to a 2586sname:VkImage whose usage flags include 2587ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT. 2588 2589[NOTE] 2590.Note 2591==== 2592Using lazily allocated memory objects for framebuffer attachments that are 2593not needed once a render pass instance has completed may: allow some 2594implementations to never allocate memory for such attachments. 2595==== 2596 2597[open,refpage='vkGetDeviceMemoryCommitment',desc='Query the current commitment for a VkDeviceMemory',type='protos'] 2598-- 2599 2600To determine the amount of lazily-allocated memory that is currently 2601committed for a memory object, call: 2602 2603include::../api/protos/vkGetDeviceMemoryCommitment.txt[] 2604 2605 * pname:device is the logical device that owns the memory. 2606 * pname:memory is the memory object being queried. 2607 * pname:pCommittedMemoryInBytes is a pointer to a basetype:VkDeviceSize 2608 value in which the number of bytes currently committed is returned, on 2609 success. 2610 2611The implementation may: update the commitment at any time, and the value 2612returned by this query may: be out of date. 2613 2614The implementation guarantees to allocate any committed memory from the 2615heapIndex indicated by the memory type that the memory object was created 2616with. 2617 2618.Valid Usage 2619**** 2620 * [[VUID-vkGetDeviceMemoryCommitment-memory-00690]] 2621 pname:memory must: have been created with a memory type that reports 2622 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT 2623**** 2624 2625include::../validity/protos/vkGetDeviceMemoryCommitment.txt[] 2626-- 2627 2628 2629ifdef::VK_VERSION_1_1[] 2630[[memory-protected-memory]] 2631=== Protected Memory 2632 2633_Protected memory_ divides device memory into protected device memory and 2634unprotected device memory. 2635 2636Protected memory adds the following concepts: 2637 2638 * Memory: 2639 ** Unprotected device memory, which can: be visible to the device and can: 2640 be visible to the host 2641 ** Protected device memory, which can: be visible to the device but must: 2642 not be visible to the host 2643 * Resources: 2644 ** Unprotected images and unprotected buffers, to which unprotected memory 2645 can: be bound 2646 ** Protected images and protected buffers, to which protected memory can: 2647 be bound 2648 * Command buffers: 2649 ** Unprotected command buffers, which can: be submitted to a device queue 2650 to execute unprotected queue operations 2651 ** Protected command buffers, which can: be submitted to a 2652 protected-capable device queue to execute protected queue operations 2653 * Device queues: 2654 ** Unprotected device queues, to which unprotected command buffers can: be 2655 submitted 2656 ** Protected-capable device queues, to which unprotected command buffers 2657 or protected command buffers can: be submitted 2658 * Queue submissions 2659 ** Unprotected queue submissions, through which unprotected command 2660 buffers can: be submitted 2661 ** Protected queue submissions, through which protected command buffers 2662 can: be submitted 2663 * Queue operations 2664 ** Unprotected queue operations 2665 2666 *** Any read from or write to protected memory during unprotected queue 2667 operations results in undefined behavior but is subject to the 2668 inviolable rules below. 2669 2670 ** Protected queue operations 2671 2672 *** Any write to unprotected memory during protected queue operations 2673 results in undefined behavior but is subject to the inviolable rules 2674 below. 2675 *** Except for framebuffer-space pipeline stages, compute shader stage, 2676 and transfer stage, any read from or write to protected memory during 2677 protected queue operations results in undefined behavior but is 2678 subject to the inviolable rules below. 2679 *** Any queries during protected queue operations results in undefined 2680 behavior but is subject to the inviolable rules below. 2681 2682[[memory-protected-memory-undefined]] 2683==== Protected memory inviolable rules 2684 2685Implementations must: ensure that correct usage or incorrect usage by an 2686application does not affect the integrity of the memory protection system. 2687 2688The implementation must: guarantee that: 2689 2690 * Protected device memory must: not be visible to the host. 2691 * Values written to unprotected device memory must: not be a function of 2692 data from protected memory. 2693 2694Incorrect usage by an application of the memory protection system results in 2695undefined behavior which may: include process termination or device loss. 2696endif::VK_VERSION_1_1[] 2697 2698ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] 2699[[memory-external-handle-types]] 2700=== External Memory Handle Types 2701 2702[[memory-external-android-hardware-buffer]] 2703==== Android Hardware Buffer 2704 2705Android's NDK defines code:AHardwareBuffer objects, which represent device 2706memory that is shareable across processes and that can: be accessed by a 2707variety of media APIs and the hardware used to implement them. 2708These Android hardware buffer objects may: be imported into 2709slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. 2710 2711Android hardware buffer objects are reference-counted using Android NDK 2712functions outside of the scope of this specification. 2713A slink:VkDeviceMemory imported from an Android hardware buffer or that can: 2714be exported to an Android hardware buffer must: acquire a reference to its 2715code:AHardwareBuffer object, and must: release this reference when the 2716device memory is freed. 2717During the host execution of a Vulkan command that has an Android hardware 2718buffer as a parameter (including indirect parameters via pname:pNext 2719chains), the application must: not decrement the Android hardware buffer's 2720reference count to zero. 2721 2722Android hardware buffers can: be mapped and unmapped for CPU access using 2723the NDK functions. 2724These lock and unlock APIs are considered to acquire and release ownership 2725of the Android hardware buffer, and applications must: follow the rules 2726described in <<resources-external-sharing,External Resource Sharing>> to 2727transfer ownership between the Vulkan instance and these native APIs. 2728 2729Android hardware buffers can: be shared with external APIs and Vulkan 2730instances on the same device, and also with foreign devices. 2731When transferring ownership of the Android hardware buffer, the external and 2732foreign special queue families described in 2733<<synchronization-queue-transfers>> are not identical. 2734All APIs which produce or consume Android hardware buffers are considered to 2735use foreign devices, except OpenGL ES contexts and Vulkan logical devices 2736that have matching device and driver UUIDs. 2737Implementations may: treat a transfer to or from the foreign queue family as 2738if it were a transfer to or from the external queue family when the Android 2739hardware buffer's usage only permits it to be used on the same physical 2740device. 2741 2742[[memory-external-android-hardware-buffer-optimal-usages]] 2743===== Android Hardware Buffer Optimal Usages ===== 2744 2745Vulkan buffer and image usage flags do not correspond exactly to Android 2746hardware buffer usage flags. 2747When allocating Android hardware buffers with non-Vulkan APIs, if any 2748code:AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the 2749allocator must: allocate the memory in such a way that it supports Vulkan 2750usages and creation flags in the 2751<<memory-external-android-hardware-buffer-usage, usage equivalence table>> 2752which do not have Android hardware buffer equivalents. 2753 2754The slink:VkAndroidHardwareBufferUsageANDROID structure can: be attached to 2755the pname:pNext chain of a slink:VkImageFormatProperties2 instance passed to 2756flink:vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android 2757hardware buffer usage flags for specific Vulkan resource creation 2758parameters. 2759Some usage flags returned by these commands are required: based on the input 2760parameters, but additional vendor-specific usage flags 2761(code:AHARDWAREBUFFER_USAGE_VENDOR_*) may: also be returned. 2762Any Android hardware buffer allocated with these vendor-specific usage flags 2763and imported to Vulkan must: only be bound to resources created with 2764parameters that are a subset of the parameters used to obtain the Android 2765hardware buffer usage, since the memory may: have been allocated in a way 2766incompatible with other parameters. 2767If an Android hardware buffer is successfully allocated with additional 2768non-vendor-specific usage flags in addition to the recommended usage, it 2769must: support being used in the same ways as an Android hardware buffer 2770allocated with only the recommended usage, and also in ways indicated by the 2771additional usage. 2772 2773[[memory-external-android-hardware-buffer-external-formats]] 2774===== Android Hardware Buffer External Formats ===== 2775 2776Android hardware buffers may: represent images using implementation-specific 2777formats, layouts, color models, etc., which do not have Vulkan equivalents. 2778Such _external formats_ are commonly used by external image sources such as 2779video decoders or cameras. 2780Vulkan can: import Android hardware buffers that have external formats, but 2781since the image contents are in an undiscoverable and possibly proprietary 2782representation, images with external formats must: only be used as sampled 2783images, must: only be sampled with a sampler that has Y'C~B~C~R~ conversion 2784enabled, and must: have optimal tiling. 2785 2786Images that will be backed by an Android hardware buffer can: use an 2787external format by setting slink:VkImageCreateInfo::pname:format to 2788ename:VK_FORMAT_UNDEFINED and including an instance of 2789slink:VkExternalFormatANDROID in the pname:pNext chain. 2790Images can: be created with an external format even if the Android hardware 2791buffer has a format which has an 2792<<memory-external-android-hardware-buffer-formats,equivalent Vulkan format>> 2793to enable consistent handling of images from sources that might use either 2794category of format. 2795However, all images created with an external format are subject to the valid 2796usage requirements associated with external formats, even if the Android 2797hardware buffer's format has a Vulkan equivalent. 2798The external format of an Android hardware buffer can: be obtained by 2799passing an instance of slink:VkAndroidHardwareBufferFormatPropertiesANDROID 2800to flink:vkGetAndroidHardwareBufferPropertiesANDROID. 2801 2802[[memory-external-android-hardware-buffer-image-resources]] 2803===== Android Hardware Buffer Image Resources 2804 2805Android hardware buffers have intrinsic width, height, format, and usage 2806properties, so Vulkan images bound to memory imported from an Android 2807hardware buffer must: use dedicated allocations: 2808sname:VkMemoryDedicatedRequirements::pname:requiresDedicatedAllocation must: 2809be ename:VK_TRUE for images created with 2810sname:VkExternalMemoryImageCreateInfo::pname:handleTypes that includes 2811ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. 2812When creating an image that will be bound to an imported Android hardware 2813buffer, the image creation parameters must: be equivalent to the 2814code:AHardwareBuffer properties as described by the valid usage of 2815slink:VkMemoryAllocateInfo. 2816Similarly, device memory allocated for a dedicated image must: not be 2817exported to an Android hardware buffer until it has been bound to that 2818image, and the implementation must: return an Android hardware buffer with 2819properties derived from the image: 2820 2821 * The code:width and code:height members of code:AHardwareBuffer_desc 2822 must: be the same as the pname:width and pname:height members of 2823 slink:VkImageCreateInfo::pname:extent, respectively. 2824 * The code:layers member of code:AHardwareBuffer_desc must: be the same as 2825 the pname:arrayLayers member of slink:VkImageCreateInfo. 2826 * The code:format member of code:AHardwareBuffer_desc must: be equivalent 2827 to slink:VkImageCreateInfo::pname:format as defined by 2828 <<memory-external-android-hardware-buffer-formats,AHardwareBuffer Format 2829 Equivalence>>. 2830 * The code:usage member of code:AHardwareBuffer_desc must: include bits 2831 corresponding to bits included in slink:VkImageCreateInfo::pname:usage 2832 and slink:VkImageCreateInfo::pname:flags where such a correspondence 2833 exists according to 2834 <<memory-external-android-hardware-buffer-usage,AHardwareBuffer Usage 2835 Equivalence>>. 2836 It may: also include additional usage bits, including vendor-specific 2837 usages. 2838 Presence of vendor usage bits may: make the Android hardware buffer only 2839 usable in ways indicated by the image creation parameters, even when 2840 used outside Vulkan, in a similar way that allocating the Android 2841 hardware buffer with usage returned in 2842 slink:VkAndroidHardwareBufferUsageANDROID. 2843 2844Implementations may: support fewer combinations of image creation parameters 2845for images with Android hardware buffer external handle type than for 2846non-external images. 2847Support for a given set of parameters can: be determined by passing 2848slink:VkExternalImageFormatProperties to 2849flink:vkGetPhysicalDeviceImageFormatProperties2 with pname:handleType set to 2850ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID. 2851Any Android hardware buffer successfully allocated outside Vulkan with usage 2852that includes code:AHARDWAREBUFFER_USAGE_GPU_* must: be supported when using 2853equivalent Vulkan image parameters. 2854If a given choice of image parameters are supported for import, they can: 2855also be used to create an image and memory that will be exported to an 2856Android hardware buffer. 2857 2858[[memory-external-android-hardware-buffer-formats]] 2859.AHardwareBuffer Format Equivalence 2860[width="100%",options="header"] 2861|==== 2862| AHardwareBuffer Format | Vulkan Format 2863| code:AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM | ename:VK_FORMAT_R8G8B8A8_UNORM 2864| code:AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM | ename:VK_FORMAT_R8G8B8A8_UNORM 2865| code:AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM | ename:VK_FORMAT_R8G8B8_UNORM 2866| code:AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM | ename:VK_FORMAT_R5G6B5_UNORM_PACK16 2867| code:AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT | ename:VK_FORMAT_R16G16B16A16_SFLOAT 2868| code:AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM | ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32 2869| code:AHARDWAREBUFFER_FORMAT_D16_UNORM | ename:VK_FORMAT_D16_UNORM 2870| code:AHARDWAREBUFFER_FORMAT_D24_UNORM | ename:VK_FORMAT_X8_D24_UNORM_PACK32 2871| code:AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT | ename:VK_FORMAT_D24_UNORM_S8_UINT 2872| code:AHARDWAREBUFFER_FORMAT_D32_FLOAT | ename:VK_FORMAT_D32_SFLOAT 2873| code:AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT | ename:VK_FORMAT_D32_SFLOAT_S8_UINT 2874| code:AHARDWAREBUFFER_FORMAT_S8_UINT | ename:VK_FORMAT_S8_UINT 2875|==== 2876 2877[[memory-external-android-hardware-buffer-usage]] 2878.AHardwareBuffer Usage Equivalence 2879[width="100%",options="header"] 2880|==== 2881| AHardwareBuffer Usage | Vulkan Usage or Creation Flag 2882| None | ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT 2883| None | ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT 2884| code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | ename:VK_IMAGE_USAGE_SAMPLED_BIT 2885| code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 2886| code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT | ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2887| code:AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP | ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT 2888| code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE | None ^2^ 2889ifdef::VK_VERSION_1_1[] 2890| code:AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT | ename:VK_IMAGE_CREATE_PROTECTED_BIT 2891endif::VK_VERSION_1_1[] 2892| None | ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 2893| None | ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT 2894|==== 2895 28962:: 2897 The code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE flag does not 2898 correspond to a Vulkan image usage or creation flag. 2899 Instead, its presence indicates that the Android hardware buffer 2900 contains a complete set of mip levels 2901 (sname:VkImageCreateInfo::pname:mipLevels is 2902 [eq]#{lceil}log~2~(max(code:width, code:height)){rceil} {plus} 1#), and 2903 its absence indicates that the Android hardware buffer contains only a 2904 single mip level. 2905 2906ifdef::VK_KHR_image_format_list[] 2907[NOTE] 2908.Note 2909==== 2910When using ename:VK_IMAGE_USAGE_MUTABLE_FORMAT_BIT with Android hardware 2911buffer images, applications should: use slink:VkImageFormatListCreateInfoKHR 2912to inform the implementation which view formats will be used with the image. 2913For some common sets of format, this allows some implementations to provide 2914significantly better performance when accessing the image via Vulkan. 2915==== 2916endif::VK_KHR_image_format_list[] 2917 2918[[memory-external-android-hardware-buffer-buffer-resources]] 2919===== Android Hardware Buffer Buffer Resources 2920 2921Android hardware buffers with a format of code:AHARDWAREBUFFER_FORMAT_BLOB 2922and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can: be 2923used as the backing store for slink:VkBuffer objects. 2924Such Android hardware buffers have a size in bytes specified by their 2925code:width; code:height and code:layers are both `1`. 2926 2927Unlike images, buffer resources backed by Android hardware buffers do not 2928require dedicated allocations. 2929 2930Exported code:AHardwareBuffer objects that do not have dedicated images 2931must: have a format of code:AHARDWAREBUFFER_FORMAT_BLOB, usage must: include 2932code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, code:width must: equal the 2933device memory allocation size, and code:height and code:layers must: be `1`. 2934 2935endif::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] 2936 2937ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2938 2939[[memory-peer-memory-features]] 2940=== Peer Memory Features 2941 2942[open,refpage='vkGetDeviceGroupPeerMemoryFeatures',desc='Query supported peer memory features of a device',type='protos'] 2943-- 2944 2945_Peer memory_ is memory that is allocated for a given physical device and 2946then bound to a resource and accessed by a different physical device, in a 2947logical device that represents multiple physical devices. 2948Some ways of reading and writing peer memory may: not be supported by a 2949device. 2950 2951To determine how peer memory can: be accessed, call: 2952 2953ifdef::VK_VERSION_1_1[] 2954include::../api/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[] 2955endif::VK_VERSION_1_1[] 2956 2957ifdef::VK_VERSION_1_1+VK_KHR_device_group[or the equivalent command] 2958 2959ifdef::VK_KHR_device_group[] 2960include::../api/protos/vkGetDeviceGroupPeerMemoryFeaturesKHR.txt[] 2961endif::VK_KHR_device_group[] 2962 2963 * pname:device is the logical device that owns the memory. 2964 * pname:heapIndex is the index of the memory heap from which the memory is 2965 allocated. 2966 * pname:localDeviceIndex is the device index of the physical device that 2967 performs the memory access. 2968 * pname:remoteDeviceIndex is the device index of the physical device that 2969 the memory is allocated for. 2970 * pname:pPeerMemoryFeatures is a pointer to a bitmask of 2971 elink:VkPeerMemoryFeatureFlagBits indicating which types of memory 2972 accesses are supported for the combination of heap, local, and remote 2973 devices. 2974 2975.Valid Usage 2976**** 2977 * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-heapIndex-00691]] 2978 pname:heapIndex must: be less than pname:memoryHeapCount 2979 * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00692]] 2980 pname:localDeviceIndex must: be a valid device index 2981 * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-remoteDeviceIndex-00693]] 2982 pname:remoteDeviceIndex must: be a valid device index 2983 * [[VUID-vkGetDeviceGroupPeerMemoryFeatures-localDeviceIndex-00694]] 2984 pname:localDeviceIndex must: not equal remoteDeviceIndex 2985**** 2986 2987include::../validity/protos/vkGetDeviceGroupPeerMemoryFeatures.txt[] 2988 2989-- 2990 2991[open,refpage='VkPeerMemoryFeatureFlagBits',desc='Bitmask specifying supported peer memory features',type='enums'] 2992-- 2993 2994Bits which may: be set in the value returned for 2995flink:vkGetDeviceGroupPeerMemoryFeatures::pname:pPeerMemoryFeatures, 2996indicating the supported peer memory features, are: 2997 2998include::../api/enums/VkPeerMemoryFeatureFlagBits.txt[] 2999 3000ifdef::VK_KHR_device_group[] 3001or the equivalent 3002 3003include::../api/enums/VkPeerMemoryFeatureFlagBitsKHR.txt[] 3004endif::VK_KHR_device_group[] 3005 3006 * ename:VK_PEER_MEMORY_FEATURE_COPY_SRC_BIT specifies that the memory can: 3007 be accessed as the source of a ftext:vkCmdCopyBuffer, 3008 ftext:vkCmdCopyImage, ftext:vkCmdCopyBufferToImage, or 3009 ftext:vkCmdCopyImageToBuffer command. 3010 * ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT specifies that the memory can: 3011 be accessed as the destination of a ftext:vkCmdCopyBuffer, 3012 ftext:vkCmdCopyImage, ftext:vkCmdCopyBufferToImage, or 3013 ftext:vkCmdCopyImageToBuffer command. 3014 * ename:VK_PEER_MEMORY_FEATURE_GENERIC_SRC_BIT specifies that the memory 3015 can: be read as any memory access type. 3016 * ename:VK_PEER_MEMORY_FEATURE_GENERIC_DST_BIT specifies that the memory 3017 can: be written as any memory access type. 3018 Shader atomics are considered to be writes. 3019 3020[NOTE] 3021.Note 3022==== 3023The peer memory features of a memory heap also apply to any accesses that 3024may: be performed during <<synchronization-image-layout-transitions, image 3025layout transitions>>. 3026==== 3027 3028ename:VK_PEER_MEMORY_FEATURE_COPY_DST_BIT must: be supported for all host 3029local heaps and for at least one device local heap. 3030 3031If a device does not support a peer memory feature, it is still valid to use 3032a resource that includes both local and peer memory bindings with the 3033corresponding access type as long as only the local bindings are actually 3034accessed. 3035For example, an application doing split-frame rendering would use 3036framebuffer attachments that include both local and peer memory bindings, 3037but would scissor the rendering to only update local memory. 3038 3039-- 3040 3041[open,refpage='VkPeerMemoryFeatureFlags',desc='Bitmask of VkPeerMemoryFeatureFlagBits',type='enums'] 3042-- 3043include::../api/flags/VkPeerMemoryFeatureFlags.txt[] 3044 3045ifdef::VK_KHR_device_group[] 3046or the equivalent 3047 3048include::../api/flags/VkPeerMemoryFeatureFlagsKHR.txt[] 3049endif::VK_KHR_device_group[] 3050 3051sname:VkPeerMemoryFeatureFlags is a bitmask type for setting a mask of zero 3052or more slink:VkPeerMemoryFeatureFlagBits. 3053-- 3054 3055endif::VK_VERSION_1_1,VK_KHR_device_group[] 3056