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