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