1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[resources]] 6= Resource Creation 7 8Vulkan supports two primary resource types: _buffers_ and _images_. 9Resources are views of memory with associated formatting and dimensionality. 10Buffers are essentially unformatted arrays of bytes whereas images contain 11format information, can: be multidimensional and may: have associated 12metadata. 13 14 15[[resources-buffers]] 16== Buffers 17 18[open,refpage='VkBuffer',desc='Opaque handle to a buffer object',type='handles'] 19-- 20Buffers represent linear arrays of data which are used for various purposes 21by binding them to a graphics or compute pipeline via descriptor sets or via 22certain commands, or by directly specifying them as parameters to certain 23commands. 24 25Buffers are represented by sname:VkBuffer handles: 26 27include::{generated}/api/handles/VkBuffer.txt[] 28-- 29 30[open,refpage='vkCreateBuffer',desc='Create a new buffer object',type='protos'] 31-- 32To create buffers, call: 33 34include::{generated}/api/protos/vkCreateBuffer.txt[] 35 36 * pname:device is the logical device that creates the buffer object. 37 * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure 38 containing parameters affecting creation of the buffer. 39 * pname:pAllocator controls host memory allocation as described in the 40 <<memory-allocation, Memory Allocation>> chapter. 41 * pname:pBuffer is a pointer to a slink:VkBuffer handle in which the 42 resulting buffer object is returned. 43 44.Valid Usage 45**** 46 * [[VUID-vkCreateBuffer-flags-00911]] 47 If the pname:flags member of pname:pCreateInfo includes 48 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, creating this sname:VkBuffer 49 must: not cause the total required sparse memory for all currently valid 50 sparse resources on the device to exceed 51 sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 52ifdef::VK_FUCHSIA_buffer_collection[] 53 * [[VUID-vkCreateBuffer-pNext-06387]] 54 If using the slink:VkBuffer for an import operation from a 55 slink:VkBufferCollectionFUCHSIA where a 56 slink:VkBufferCollectionBufferCreateInfoFUCHSIA has been chained to 57 pname:pNext, pname:pCreateInfo must: match the 58 slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo used when setting 59 the constraints on the buffer collection with 60 flink:vkSetBufferCollectionBufferConstraintsFUCHSIA 61endif::VK_FUCHSIA_buffer_collection[] 62**** 63 64include::{generated}/validity/protos/vkCreateBuffer.txt[] 65-- 66 67[open,refpage='VkBufferCreateInfo',desc='Structure specifying the parameters of a newly created buffer object',type='structs'] 68-- 69The sname:VkBufferCreateInfo structure is defined as: 70 71include::{generated}/api/structs/VkBufferCreateInfo.txt[] 72 73 * pname:sType is the type of this structure. 74 * pname:pNext is `NULL` or a pointer to a structure extending this 75 structure. 76 * pname:flags is a bitmask of elink:VkBufferCreateFlagBits specifying 77 additional parameters of the buffer. 78 * pname:size is the size in bytes of the buffer to be created. 79 * pname:usage is a bitmask of elink:VkBufferUsageFlagBits specifying 80 allowed usages of the buffer. 81 * pname:sharingMode is a elink:VkSharingMode value specifying the sharing 82 mode of the buffer when it will be accessed by multiple queue families. 83 * pname:queueFamilyIndexCount is the number of entries in the 84 pname:pQueueFamilyIndices array. 85 * pname:pQueueFamilyIndices is a pointer to an array of queue families 86 that will access this buffer. 87 It is ignored if pname:sharingMode is not 88 ename:VK_SHARING_MODE_CONCURRENT. 89 90.Valid Usage 91**** 92 * [[VUID-VkBufferCreateInfo-size-00912]] 93 pname:size must: be greater than `0` 94 * [[VUID-VkBufferCreateInfo-sharingMode-00913]] 95 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 96 pname:pQueueFamilyIndices must: be a valid pointer to an array of 97 pname:queueFamilyIndexCount code:uint32_t values 98 * [[VUID-VkBufferCreateInfo-sharingMode-00914]] 99 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 100 pname:queueFamilyIndexCount must: be greater than `1` 101ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 102 * [[VUID-VkBufferCreateInfo-sharingMode-01391]] 103 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 104 of pname:pQueueFamilyIndices must: be unique and must: be less than 105 pname:pQueueFamilyPropertyCount returned by 106 flink:vkGetPhysicalDeviceQueueFamilyProperties for the 107 pname:physicalDevice that was used to create pname:device 108endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 109ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 110 * [[VUID-VkBufferCreateInfo-sharingMode-01419]] 111 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 112 of pname:pQueueFamilyIndices must: be unique and must: be less than 113 pname:pQueueFamilyPropertyCount returned by either 114 flink:vkGetPhysicalDeviceQueueFamilyProperties or 115 flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the 116 pname:physicalDevice that was used to create pname:device 117endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 118 * [[VUID-VkBufferCreateInfo-flags-00915]] 119 If the <<features-sparseBinding,sparse bindings>> feature is not 120 enabled, pname:flags must: not contain 121 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT 122 * [[VUID-VkBufferCreateInfo-flags-00916]] 123 If the <<features-sparseResidencyBuffer,sparse buffer residency>> 124 feature is not enabled, pname:flags must: not contain 125 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT 126 * [[VUID-VkBufferCreateInfo-flags-00917]] 127 If the <<features-sparseResidencyAliased,sparse aliased residency>> 128 feature is not enabled, pname:flags must: not contain 129 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT 130 * [[VUID-VkBufferCreateInfo-flags-00918]] 131 If pname:flags contains ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or 132 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT, it must: also contain 133 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT 134ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 135 * [[VUID-VkBufferCreateInfo-pNext-00920]] 136 If the pname:pNext chain includes a 137 slink:VkExternalMemoryBufferCreateInfo structure, its pname:handleTypes 138 member must: only contain bits that are also in 139 slink:VkExternalBufferProperties::pname:externalMemoryProperties.compatibleHandleTypes, 140 as returned by flink:vkGetPhysicalDeviceExternalBufferProperties with 141 pname:pExternalBufferInfo->handleType equal to any one of the handle 142 types specified in 143 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes 144endif::VK_VERSION_1_1,VK_KHR_external_memory[] 145ifdef::VK_VERSION_1_1[] 146 * [[VUID-VkBufferCreateInfo-flags-01887]] 147 If the protected memory feature is not enabled, pname:flags must: not 148 contain ename:VK_BUFFER_CREATE_PROTECTED_BIT 149 * [[VUID-VkBufferCreateInfo-None-01888]] 150 If any of the bits ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 151 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or 152 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set, 153 ename:VK_BUFFER_CREATE_PROTECTED_BIT must: not also be set 154endif::VK_VERSION_1_1[] 155ifdef::VK_NV_dedicated_allocation[] 156 * [[VUID-VkBufferCreateInfo-pNext-01571]] 157 If the pname:pNext chain includes a 158 slink:VkDedicatedAllocationBufferCreateInfoNV structure, and the 159 pname:dedicatedAllocation member of the chained structure is 160 ename:VK_TRUE, then pname:flags must: not include 161 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 162 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or 163 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT 164endif::VK_NV_dedicated_allocation[] 165ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 166ifdef::VK_EXT_buffer_device_address[] 167 * [[VUID-VkBufferCreateInfo-deviceAddress-02604]] 168 If slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress is not 169 zero, pname:flags must: include 170 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT 171endif::VK_EXT_buffer_device_address[] 172ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 173 * [[VUID-VkBufferCreateInfo-opaqueCaptureAddress-03337]] 174 If 175 slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 176 is not zero, pname:flags must: include 177 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT 178endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 179 * [[VUID-VkBufferCreateInfo-flags-03338]] 180 If pname:flags includes 181 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the 182 <<features-bufferDeviceAddressCaptureReplay,bufferDeviceAddressCaptureReplay>> 183 or 184 <<features-bufferDeviceAddressCaptureReplayEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddressCaptureReplay>> 185 feature must: be enabled 186endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 187ifdef::VK_KHR_video_decode_queue[] 188 * [[VUID-VkBufferCreateInfo-usage-04813]] 189 If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR, 190 ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the pname:pNext 191 chain must: include a valid slink:VkVideoProfilesKHR structure which 192 includes at least one slink:VkVideoProfileKHR with a decode 193 codec-operation 194endif::VK_KHR_video_decode_queue[] 195ifdef::VK_KHR_video_encode_queue[] 196 * [[VUID-VkBufferCreateInfo-usage-04814]] 197 If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, 198 ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, then the pname:pNext 199 chain must: include a valid slink:VkVideoProfilesKHR structure which 200 includes at least one slink:VkVideoProfileKHR with a encode 201 codec-operation 202endif::VK_KHR_video_encode_queue[] 203ifdef::VK_KHR_maintenance4[] 204 * [[VUID-VkBufferCreateInfo-size-06409]] 205 pname:size must: be less than or equal to 206 slink:VkPhysicalDeviceMaintenance4PropertiesKHR::pname:maxBufferSize 207endif::VK_KHR_maintenance4[] 208**** 209 210include::{generated}/validity/structs/VkBufferCreateInfo.txt[] 211-- 212 213[open,refpage='VkBufferUsageFlagBits',desc='Bitmask specifying allowed usage of a buffer',type='enums'] 214-- 215Bits which can: be set in slink:VkBufferCreateInfo::pname:usage, specifying 216usage behavior of a buffer, are: 217 218include::{generated}/api/enums/VkBufferUsageFlagBits.txt[] 219 220 * ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT specifies that the buffer can: be 221 used as the source of a _transfer command_ (see the definition of 222 <<synchronization-pipeline-stages-transfer, 223 ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). 224 * ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT specifies that the buffer can: be 225 used as the destination of a transfer command. 226 * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT specifies that the buffer 227 can: be used to create a sname:VkBufferView suitable for occupying a 228 sname:VkDescriptorSet slot of type 229 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. 230 * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT specifies that the buffer 231 can: be used to create a sname:VkBufferView suitable for occupying a 232 sname:VkDescriptorSet slot of type 233 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. 234 * ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT specifies that the buffer can: 235 be used in a sname:VkDescriptorBufferInfo suitable for occupying a 236 sname:VkDescriptorSet slot either of type 237 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 238 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. 239 * ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT specifies that the buffer can: 240 be used in a sname:VkDescriptorBufferInfo suitable for occupying a 241 sname:VkDescriptorSet slot either of type 242 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 243 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. 244 * ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT specifies that the buffer is 245 suitable for passing as the pname:buffer parameter to 246 flink:vkCmdBindIndexBuffer. 247 * ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT specifies that the buffer is 248 suitable for passing as an element of the pname:pBuffers array to 249 flink:vkCmdBindVertexBuffers. 250 * ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is 251 suitable for passing as the pname:buffer parameter to 252 flink:vkCmdDrawIndirect, flink:vkCmdDrawIndexedIndirect, 253ifdef::VK_NV_mesh_shader[] 254 flink:vkCmdDrawMeshTasksIndirectNV, 255 flink:vkCmdDrawMeshTasksIndirectCountNV, 256endif::VK_NV_mesh_shader[] 257 or flink:vkCmdDispatchIndirect. 258ifdef::VK_NV_device_generated_commands[] 259 It is also suitable for passing as the pname:buffer member of 260 sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or 261 pname:sequencesIndexBuffer or pname:preprocessedBuffer member of 262 sname:VkGeneratedCommandsInfoNV 263endif::VK_NV_device_generated_commands[] 264ifdef::VK_EXT_conditional_rendering[] 265 * ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the 266 buffer is suitable for passing as the pname:buffer parameter to 267 flink:vkCmdBeginConditionalRenderingEXT. 268endif::VK_EXT_conditional_rendering[] 269ifdef::VK_EXT_transform_feedback[] 270 * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that 271 the buffer is suitable for using for binding as a transform feedback 272 buffer with flink:vkCmdBindTransformFeedbackBuffersEXT. 273 * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT 274 specifies that the buffer is suitable for using as a counter buffer with 275 flink:vkCmdBeginTransformFeedbackEXT and 276 flink:vkCmdEndTransformFeedbackEXT. 277endif::VK_EXT_transform_feedback[] 278ifdef::VK_NV_ray_tracing[] 279 * ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV specifies that the buffer is 280 suitable for use in flink:vkCmdTraceRaysNV. 281endif::VK_NV_ray_tracing[] 282ifdef::VK_KHR_ray_tracing_pipeline[] 283 * ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR specifies that the 284 buffer is suitable for use as a <<shader-binding-table,Shader Binding 285 Table>>. 286endif::VK_KHR_ray_tracing_pipeline[] 287ifdef::VK_KHR_acceleration_structure[] 288 * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR 289 specifies that the buffer is suitable for use as a read-only input to an 290 <<acceleration-structure-building,acceleration structure build>>. 291 * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies 292 that the buffer is suitable for storage space for a 293 slink:VkAccelerationStructureKHR. 294endif::VK_KHR_acceleration_structure[] 295ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 296 * ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT specifies that the 297 buffer can: be used to retrieve a buffer device address via 298 flink:vkGetBufferDeviceAddress and use that address to access the 299 buffer's memory from a shader. 300endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 301ifdef::VK_KHR_video_decode_queue[] 302 * ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer 303 can: be used as the source bitstream buffer in a 304 <<video-decode-operations, video decode operation>>. 305 * ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that the buffer 306 can: be used as the destination status buffer in a 307 <<video-decode-operations, video decode operation>>. 308endif::VK_KHR_video_decode_queue[] 309ifdef::VK_KHR_video_encode_queue[] 310 * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer 311 can: be used as the destination bitstream buffer in a 312 <<video-encode-operations, video encode operation>>. 313 * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer 314 can: be used as the destination status buffer in a 315 <<video-encode-operations, video encode operation>>. 316endif::VK_KHR_video_encode_queue[] 317-- 318 319[open,refpage='VkBufferUsageFlags',desc='Bitmask of VkBufferUsageFlagBits',type='flags'] 320-- 321include::{generated}/api/flags/VkBufferUsageFlags.txt[] 322 323tname:VkBufferUsageFlags is a bitmask type for setting a mask of zero or 324more elink:VkBufferUsageFlagBits. 325-- 326 327[open,refpage='VkBufferCreateFlagBits',desc='Bitmask specifying additional parameters of a buffer',type='enums'] 328-- 329Bits which can: be set in slink:VkBufferCreateInfo::pname:flags, specifying 330additional parameters of a buffer, are: 331 332include::{generated}/api/enums/VkBufferCreateFlagBits.txt[] 333 334 * ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will 335 be backed using sparse memory binding. 336 * ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer 337 can: be partially backed using sparse memory binding. 338 Buffers created with this flag must: also be created with the 339 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. 340 * ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will 341 be backed using sparse memory binding with memory ranges that might also 342 simultaneously be backing another buffer (or another portion of the same 343 buffer). 344 Buffers created with this flag must: also be created with the 345 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. 346ifdef::VK_VERSION_1_1[] 347 * ename:VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a 348 protected buffer. 349endif::VK_VERSION_1_1[] 350ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 351 * ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that 352 the buffer's address can: be saved and reused on a subsequent run (e.g. 353 for trace capture and replay), see 354 slink:VkBufferOpaqueCaptureAddressCreateInfo for more detail. 355endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 356 357See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and 358<<features,Physical Device Features>> for details of the sparse memory 359features supported on a device. 360-- 361 362[open,refpage='VkBufferCreateFlags',desc='Bitmask of VkBufferCreateFlagBits',type='flags'] 363-- 364include::{generated}/api/flags/VkBufferCreateFlags.txt[] 365 366tname:VkBufferCreateFlags is a bitmask type for setting a mask of zero or 367more elink:VkBufferCreateFlagBits. 368-- 369 370ifdef::VK_NV_dedicated_allocation[] 371[open,refpage='VkDedicatedAllocationBufferCreateInfoNV',desc='Specify that a buffer is bound to a dedicated memory resource',type='structs'] 372-- 373If the pname:pNext chain includes a 374sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure 375includes an enable controlling whether the buffer will have a dedicated 376memory allocation bound to it. 377 378The sname:VkDedicatedAllocationBufferCreateInfoNV structure is defined as: 379 380include::{generated}/api/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] 381 382 * pname:sType is the type of this structure. 383 * pname:pNext is `NULL` or a pointer to a structure extending this 384 structure. 385 * pname:dedicatedAllocation specifies whether the buffer will have a 386 dedicated allocation bound to it. 387 388include::{generated}/validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] 389-- 390endif::VK_NV_dedicated_allocation[] 391 392ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 393[open,refpage='VkExternalMemoryBufferCreateInfo',desc='Specify that a buffer may be backed by external memory',type='structs'] 394-- 395To define a set of external memory handle types that may: be used as backing 396store for a buffer, add a slink:VkExternalMemoryBufferCreateInfo structure 397to the pname:pNext chain of the slink:VkBufferCreateInfo structure. 398The sname:VkExternalMemoryBufferCreateInfo structure is defined as: 399 400include::{generated}/api/structs/VkExternalMemoryBufferCreateInfo.txt[] 401 402ifdef::VK_KHR_external_memory[] 403or the equivalent 404 405include::{generated}/api/structs/VkExternalMemoryBufferCreateInfoKHR.txt[] 406endif::VK_KHR_external_memory[] 407 408[NOTE] 409.Note 410==== 411A sname:VkExternalMemoryBufferCreateInfo structure with a non-zero 412pname:handleTypes field must be included in the creation parameters for a 413buffer that will be bound to memory that is either exported or imported. 414==== 415 416 * pname:sType is the type of this structure. 417 * pname:pNext is `NULL` or a pointer to a structure extending this 418 structure. 419 * pname:handleTypes is zero, or a bitmask of 420 elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external 421 memory handle types. 422 423include::{generated}/validity/structs/VkExternalMemoryBufferCreateInfo.txt[] 424-- 425endif::VK_VERSION_1_1,VK_KHR_external_memory[] 426 427ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 428[open,refpage='VkBufferOpaqueCaptureAddressCreateInfo',desc='Request a specific address for a buffer',type='structs',alias='VkBufferOpaqueCaptureAddressCreateInfoKHR'] 429-- 430To request a specific device address for a buffer, add a 431slink:VkBufferOpaqueCaptureAddressCreateInfo structure to the pname:pNext 432chain of the slink:VkBufferCreateInfo structure. 433The sname:VkBufferOpaqueCaptureAddressCreateInfo structure is defined as: 434 435include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfo.txt[] 436 437ifdef::VK_KHR_buffer_device_address[] 438or the equivalent 439 440include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfoKHR.txt[] 441endif::VK_KHR_buffer_device_address[] 442 443 * pname:sType is the type of this structure. 444 * pname:pNext is `NULL` or a pointer to a structure extending this 445 structure. 446 * pname:opaqueCaptureAddress is the opaque capture address requested for 447 the buffer. 448 449If pname:opaqueCaptureAddress is zero, no specific address is requested. 450 451If pname:opaqueCaptureAddress is not zero, then it should: be an address 452retrieved from flink:vkGetBufferOpaqueCaptureAddress for an identically 453created buffer on the same implementation. 454 455If this structure is not present, it is as if pname:opaqueCaptureAddress is 456zero. 457 458Apps should: avoid creating buffers with app-provided addresses and 459implementation-provided addresses in the same process, to reduce the 460likelihood of ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors. 461 462[NOTE] 463.Note 464==== 465The expected usage for this is that a trace capture/replay tool will add the 466ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers 467that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and during capture 468will save the queried opaque device addresses in the trace. 469During replay, the buffers will be created specifying the original address 470so any address values stored in the trace data will remain valid. 471 472Implementations are expected to separate such buffers in the GPU address 473space so normal allocations will avoid using these addresses. 474Apps/tools should avoid mixing app-provided and implementation-provided 475addresses for buffers created with 476ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address 477space allocation conflicts. 478==== 479 480include::{generated}/validity/structs/VkBufferOpaqueCaptureAddressCreateInfo.txt[] 481-- 482endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 483 484ifdef::VK_EXT_buffer_device_address[] 485[open,refpage='VkBufferDeviceAddressCreateInfoEXT',desc='Request a specific address for a buffer',type='structs'] 486-- 487ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 488Alternatively, to 489endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 490ifndef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 491To 492endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 493request a specific device address for a buffer, add a 494slink:VkBufferDeviceAddressCreateInfoEXT structure to the pname:pNext chain 495of the slink:VkBufferCreateInfo structure. 496The sname:VkBufferDeviceAddressCreateInfoEXT structure is defined as: 497 498include::{generated}/api/structs/VkBufferDeviceAddressCreateInfoEXT.txt[] 499 500 * pname:sType is the type of this structure. 501 * pname:pNext is `NULL` or a pointer to a structure extending this 502 structure. 503 * pname:deviceAddress is the device address requested for the buffer. 504 505If pname:deviceAddress is zero, no specific address is requested. 506 507If pname:deviceAddress is not zero, then it must: be an address retrieved 508from an identically created buffer on the same implementation. 509The buffer must: also be bound to an identically created 510sname:VkDeviceMemory object. 511 512If this structure is not present, it is as if pname:deviceAddress is zero. 513 514Apps should: avoid creating buffers with app-provided addresses and 515implementation-provided addresses in the same process, to reduce the 516likelihood of ename:VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors. 517 518include::{generated}/validity/structs/VkBufferDeviceAddressCreateInfoEXT.txt[] 519-- 520endif::VK_EXT_buffer_device_address[] 521 522 523ifdef::VK_FUCHSIA_buffer_collection[] 524[open,refpage='VkBufferCollectionBufferCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkBuffer',type='structs'] 525-- 526The sname:VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as: 527 528include::{generated}/api/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.txt[] 529 530 * pname:sType is the type of this structure 531 * pname:pNext is `NULL` or a pointer to a structure extending this 532 structure 533 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 534 * pname:index is the index of the buffer in the buffer collection from 535 which the memory will be imported 536 537.Valid Usage 538**** 539 * [[VUID-VkBufferCollectionBufferCreateInfoFUCHSIA-index-06388]] 540 pname:index must: be less than 541 slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount 542**** 543 544include::{generated}/validity/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.txt[] 545-- 546endif::VK_FUCHSIA_buffer_collection[] 547 548[open,refpage='vkDestroyBuffer',desc='Destroy a buffer object',type='protos'] 549-- 550To destroy a buffer, call: 551 552include::{generated}/api/protos/vkDestroyBuffer.txt[] 553 554 * pname:device is the logical device that destroys the buffer. 555 * pname:buffer is the buffer to destroy. 556 * pname:pAllocator controls host memory allocation as described in the 557 <<memory-allocation, Memory Allocation>> chapter. 558 559.Valid Usage 560**** 561 * [[VUID-vkDestroyBuffer-buffer-00922]] 562 All submitted commands that refer to pname:buffer, either directly or 563 via a sname:VkBufferView, must: have completed execution 564 * [[VUID-vkDestroyBuffer-buffer-00923]] 565 If sname:VkAllocationCallbacks were provided when pname:buffer was 566 created, a compatible set of callbacks must: be provided here 567 * [[VUID-vkDestroyBuffer-buffer-00924]] 568 If no sname:VkAllocationCallbacks were provided when pname:buffer was 569 created, pname:pAllocator must: be `NULL` 570**** 571 572include::{generated}/validity/protos/vkDestroyBuffer.txt[] 573-- 574 575 576[[resources-buffer-views]] 577== Buffer Views 578 579[open,refpage='VkBufferView',desc='Opaque handle to a buffer view object',type='handles'] 580-- 581A _buffer view_ represents a contiguous range of a buffer and a specific 582format to be used to interpret the data. 583Buffer views are used to enable shaders to access buffer contents 584interpreted as formatted data. 585In order to create a valid buffer view, the buffer must: have been created 586with at least one of the following usage flags: 587 588 * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT 589 * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT 590 591Buffer views are represented by sname:VkBufferView handles: 592 593include::{generated}/api/handles/VkBufferView.txt[] 594-- 595 596[open,refpage='vkCreateBufferView',desc='Create a new buffer view object',type='protos'] 597-- 598To create a buffer view, call: 599 600include::{generated}/api/protos/vkCreateBufferView.txt[] 601 602 * pname:device is the logical device that creates the buffer view. 603 * pname:pCreateInfo is a pointer to a slink:VkBufferViewCreateInfo 604 structure containing parameters to be used to create the buffer view. 605 * pname:pAllocator controls host memory allocation as described in the 606 <<memory-allocation, Memory Allocation>> chapter. 607 * pname:pView is a pointer to a slink:VkBufferView handle in which the 608 resulting buffer view object is returned. 609 610include::{generated}/validity/protos/vkCreateBufferView.txt[] 611-- 612 613[open,refpage='VkBufferViewCreateInfo',desc='Structure specifying parameters of a newly created buffer view',type='structs'] 614-- 615The sname:VkBufferViewCreateInfo structure is defined as: 616 617include::{generated}/api/structs/VkBufferViewCreateInfo.txt[] 618 619 * pname:sType is the type of this structure. 620 * pname:pNext is `NULL` or a pointer to a structure extending this 621 structure. 622 * pname:flags is reserved for future use. 623 * pname:buffer is a slink:VkBuffer on which the view will be created. 624 * pname:format is a elink:VkFormat describing the format of the data 625 elements in the buffer. 626 * pname:offset is an offset in bytes from the base address of the buffer. 627 Accesses to the buffer view from shaders use addressing that is relative 628 to this starting offset. 629 * pname:range is a size in bytes of the buffer view. 630 If pname:range is equal to ename:VK_WHOLE_SIZE, the range from 631 pname:offset to the end of the buffer is used. 632 If ename:VK_WHOLE_SIZE is used and the remaining size of the buffer is 633 not a multiple of the <<texel-block-size, texel block size>> of 634 pname:format, the nearest smaller multiple is used. 635 636.Valid Usage 637**** 638 * [[VUID-VkBufferViewCreateInfo-offset-00925]] 639 pname:offset must: be less than the size of pname:buffer 640ifndef::VK_EXT_texel_buffer_alignment[] 641 * [[VUID-VkBufferViewCreateInfo-offset-00926]] 642 pname:offset must: be a multiple of 643 sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment 644endif::VK_EXT_texel_buffer_alignment[] 645 * [[VUID-VkBufferViewCreateInfo-range-00928]] 646 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 647 greater than `0` 648 * [[VUID-VkBufferViewCreateInfo-range-00929]] 649 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 650 an integer multiple of the texel block size of pname:format 651 * [[VUID-VkBufferViewCreateInfo-range-00930]] 652 If pname:range is not equal to ename:VK_WHOLE_SIZE, the number of texel 653 buffer elements given by [eq]#({lfloor}pname:range / (texel block 654 size){rfloor} {times} (texels per block))# where texel block size and 655 texels per block are as defined in the <<formats-compatibility, 656 Compatible Formats>> table for pname:format, must: be less than or equal 657 to sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements 658 * [[VUID-VkBufferViewCreateInfo-offset-00931]] 659 If pname:range is not equal to ename:VK_WHOLE_SIZE, the sum of 660 pname:offset and pname:range must: be less than or equal to the size of 661 pname:buffer 662 * [[VUID-VkBufferViewCreateInfo-range-04059]] 663 If pname:range is equal to ename:VK_WHOLE_SIZE, the number of texel 664 buffer elements given by [eq]#({lfloor}(size - pname:offset) / (texel 665 block size){rfloor} {times} (texels per block))# where size is the size 666 of pname:buffer, and texel block size and texels per block are as 667 defined in the <<formats-compatibility, Compatible Formats>> table for 668 pname:format, must: be less than or equal to 669 sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements 670 * [[VUID-VkBufferViewCreateInfo-buffer-00932]] 671 pname:buffer must: have been created with a pname:usage value containing 672 at least one of ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or 673 ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT 674 * [[VUID-VkBufferViewCreateInfo-buffer-00933]] 675 If pname:buffer was created with pname:usage containing 676 ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:format must: be 677 supported for uniform texel buffers, as specified by the 678 ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT flag in 679 sname:VkFormatProperties::pname:bufferFeatures returned by 680 flink:vkGetPhysicalDeviceFormatProperties 681 * [[VUID-VkBufferViewCreateInfo-buffer-00934]] 682 If pname:buffer was created with pname:usage containing 683 ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:format must: be 684 supported for storage texel buffers, as specified by the 685 ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT flag in 686 sname:VkFormatProperties::pname:bufferFeatures returned by 687 flink:vkGetPhysicalDeviceFormatProperties 688 * [[VUID-VkBufferViewCreateInfo-buffer-00935]] 689 If pname:buffer is non-sparse then it must: be bound completely and 690 contiguously to a single sname:VkDeviceMemory object 691ifdef::VK_EXT_texel_buffer_alignment[] 692 * [[VUID-VkBufferViewCreateInfo-offset-02749]] 693 If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is 694 not enabled, pname:offset must: be a multiple of 695 sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment 696 * [[VUID-VkBufferViewCreateInfo-buffer-02750]] 697 If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is 698 enabled and if pname:buffer was created with pname:usage containing 699 ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:offset must: be a 700 multiple of the lesser of 701 slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:storageTexelBufferOffsetAlignmentBytes 702 or, if 703 slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:storageTexelBufferOffsetSingleTexelAlignment 704 is ename:VK_TRUE, the size of a texel of the requested pname:format. 705 If the size of a texel is a multiple of three bytes, then the size of a 706 single component of pname:format is used instead 707 * [[VUID-VkBufferViewCreateInfo-buffer-02751]] 708 If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is 709 enabled and if pname:buffer was created with pname:usage containing 710 ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:offset must: be a 711 multiple of the lesser of 712 slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:uniformTexelBufferOffsetAlignmentBytes 713 or, if 714 slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:uniformTexelBufferOffsetSingleTexelAlignment 715 is ename:VK_TRUE, the size of a texel of the requested pname:format. 716 If the size of a texel is a multiple of three bytes, then the size of a 717 single component of pname:format is used instead 718endif::VK_EXT_texel_buffer_alignment[] 719**** 720 721include::{generated}/validity/structs/VkBufferViewCreateInfo.txt[] 722-- 723 724[open,refpage='VkBufferViewCreateFlags',desc='Reserved for future use',type='flags'] 725-- 726include::{generated}/api/flags/VkBufferViewCreateFlags.txt[] 727 728tname:VkBufferViewCreateFlags is a bitmask type for setting a mask, but is 729currently reserved for future use. 730-- 731 732[open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos'] 733-- 734To destroy a buffer view, call: 735 736include::{generated}/api/protos/vkDestroyBufferView.txt[] 737 738 * pname:device is the logical device that destroys the buffer view. 739 * pname:bufferView is the buffer view to destroy. 740 * pname:pAllocator controls host memory allocation as described in the 741 <<memory-allocation, Memory Allocation>> chapter. 742 743.Valid Usage 744**** 745 * [[VUID-vkDestroyBufferView-bufferView-00936]] 746 All submitted commands that refer to pname:bufferView must: have 747 completed execution 748 * [[VUID-vkDestroyBufferView-bufferView-00937]] 749 If sname:VkAllocationCallbacks were provided when pname:bufferView was 750 created, a compatible set of callbacks must: be provided here 751 * [[VUID-vkDestroyBufferView-bufferView-00938]] 752 If no sname:VkAllocationCallbacks were provided when pname:bufferView 753 was created, pname:pAllocator must: be `NULL` 754**** 755 756include::{generated}/validity/protos/vkDestroyBufferView.txt[] 757-- 758 759 760[[resources-images]] 761== Images 762 763[open,refpage='VkImage',desc='Opaque handle to an image object',type='handles'] 764-- 765Images represent multidimensional - up to 3 - arrays of data which can: be 766used for various purposes (e.g. attachments, textures), by binding them to a 767graphics or compute pipeline via descriptor sets, or by directly specifying 768them as parameters to certain commands. 769 770Images are represented by sname:VkImage handles: 771 772include::{generated}/api/handles/VkImage.txt[] 773-- 774 775[open,refpage='vkCreateImage',desc='Create a new image object',type='protos'] 776-- 777To create images, call: 778 779include::{generated}/api/protos/vkCreateImage.txt[] 780 781 * pname:device is the logical device that creates the image. 782 * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure 783 containing parameters to be used to create the image. 784 * pname:pAllocator controls host memory allocation as described in the 785 <<memory-allocation, Memory Allocation>> chapter. 786 * pname:pImage is a pointer to a slink:VkImage handle in which the 787 resulting image object is returned. 788 789.Valid Usage 790**** 791 * [[VUID-vkCreateImage-flags-00939]] 792 If the pname:flags member of pname:pCreateInfo includes 793 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, creating this sname:VkImage 794 must: not cause the total required sparse memory for all currently valid 795 sparse resources on the device to exceed 796 sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 797ifdef::VK_FUCHSIA_buffer_collection[] 798 * [[VUID-vkCreateImage-pNext-06389]] 799 If a slink:VkBufferCollectionImageCreateInfoFUCHSIA has been chained to 800 pname:pNext, pname:pCreateInfo must: match the 801 <<sysmem-chosen-create-infos,Sysmem chosen sname:VkImageCreateInfo>> 802 excepting members slink:VkImageCreateInfo::pname:extent and 803 slink:VkImageCreateInfo::pname:usage in the match criteria 804endif::VK_FUCHSIA_buffer_collection[] 805**** 806 807include::{generated}/validity/protos/vkCreateImage.txt[] 808-- 809 810[open,refpage='VkImageCreateInfo',desc='Structure specifying the parameters of a newly created image object',type='structs'] 811-- 812The sname:VkImageCreateInfo structure is defined as: 813 814include::{generated}/api/structs/VkImageCreateInfo.txt[] 815 816 * pname:sType is the type of this structure. 817 * pname:pNext is `NULL` or a pointer to a structure extending this 818 structure. 819 * pname:flags is a bitmask of elink:VkImageCreateFlagBits describing 820 additional parameters of the image. 821 * pname:imageType is a elink:VkImageType value specifying the basic 822 dimensionality of the image. 823 Layers in array textures do not count as a dimension for the purposes of 824 the image type. 825 * pname:format is a elink:VkFormat describing the format and type of the 826 texel blocks that will be contained in the image. 827 * pname:extent is a slink:VkExtent3D describing the number of data 828 elements in each dimension of the base level. 829 * pname:mipLevels describes the number of levels of detail available for 830 minified sampling of the image. 831 * pname:arrayLayers is the number of layers in the image. 832 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 833 number of <<primsrast-multisampling,samples per texel>>. 834 * pname:tiling is a elink:VkImageTiling value specifying the tiling 835 arrangement of the texel blocks in memory. 836 * pname:usage is a bitmask of elink:VkImageUsageFlagBits describing the 837 intended usage of the image. 838 * pname:sharingMode is a elink:VkSharingMode value specifying the sharing 839 mode of the image when it will be accessed by multiple queue families. 840 * pname:queueFamilyIndexCount is the number of entries in the 841 pname:pQueueFamilyIndices array. 842 * pname:pQueueFamilyIndices is a pointer to an array of queue families 843 that will access this image. 844 It is ignored if pname:sharingMode is not 845 ename:VK_SHARING_MODE_CONCURRENT. 846 * pname:initialLayout is a elink:VkImageLayout value specifying the 847 initial elink:VkImageLayout of all image subresources of the image. 848 See <<resources-image-layouts,Image Layouts>>. 849 850Images created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR have 851further restrictions on their limits and capabilities compared to images 852created with pname:tiling equal to ename:VK_IMAGE_TILING_OPTIMAL. 853Creation of images with tiling ename:VK_IMAGE_TILING_LINEAR may: not be 854supported unless other parameters meet all of the constraints: 855 856 * pname:imageType is ename:VK_IMAGE_TYPE_2D 857 * pname:format is not a depth/stencil format 858 * pname:mipLevels is 1 859 * pname:arrayLayers is 1 860 * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT 861 * pname:usage only includes ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or 862 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT 863 864ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 865Images created with one of the <<formats-requiring-sampler-ycbcr-conversion, 866formats that require a sampler Y'C~B~C~R~ conversion>>, have further 867restrictions on their limits and capabilities compared to images created 868with other formats. 869Creation of images with a format requiring 870<<formats-requiring-sampler-ycbcr-conversion, {YCbCr} conversion>> may: not 871be supported unless other parameters meet all of the constraints: 872 873 * pname:imageType is ename:VK_IMAGE_TYPE_2D 874 * pname:mipLevels is 1 875 * pname:arrayLayers is 1 876 * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT 877endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 878 879Implementations may: support additional limits and capabilities beyond those 880listed above. 881 882To determine the set of valid pname:usage bits for a given format, call 883flink:vkGetPhysicalDeviceFormatProperties. 884 885If the size of the resultant image would exceed pname:maxResourceSize, then 886flink:vkCreateImage must: fail and return 887ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 888This failure may: occur even when all image creation parameters satisfy 889their valid usage requirements. 890 891ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 892[NOTE] 893.Note 894==== 895For images created without ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a 896pname:usage bit is valid if it is supported for the format the image is 897created with. 898 899For images created with ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a 900pname:usage bit is valid if it is supported for at least one of the formats 901a sname:VkImageView created from the image can: have (see 902<<resources-image-views,Image Views>> for more detail). 903==== 904endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 905 906[[resources-image-creation-limits]] 907.Image Creation Limits 908**** 909Valid values for some image creation parameters are limited by a numerical 910upper bound or by inclusion in a bitset. 911For example, slink:VkImageCreateInfo::pname:arrayLayers is limited by 912pname:imageCreateMaxArrayLayers, defined below; and 913slink:VkImageCreateInfo::pname:samples is limited by 914pname:imageCreateSampleCounts, also defined below. 915 916Several limiting values are defined below, as well as assisting values from 917which the limiting values are derived. 918The limiting values are referenced by the relevant valid usage statements of 919slink:VkImageCreateInfo. 920 921ifdef::VK_EXT_image_drm_format_modifier[] 922 * Let `uint64_t imageCreateDrmFormatModifiers[]` be the set of 923 <<glossary-drm-format-modifier,Linux DRM format modifiers>> that the 924 resultant image may: have. 925 ** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 926 then pname:imageCreateDrmFormatModifiers is empty. 927 ** If slink:VkImageCreateInfo::pname:pNext contains 928 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then 929 pname:imageCreateDrmFormatModifiers contains exactly one modifier, 930 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. 931 ** If slink:VkImageCreateInfo::pname:pNext contains 932 slink:VkImageDrmFormatModifierListCreateInfoEXT, then 933 pname:imageCreateDrmFormatModifiers contains the entire array 934 slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. 935endif::VK_EXT_image_drm_format_modifier[] 936 937 * Let `VkBool32 imageCreateMaybeLinear` indicate if the resultant image 938 may be <<glossary-linear-resource,linear>>. 939ifndef::VK_EXT_image_drm_format_modifier[] 940 (The definition below is trivial because certain extensions are disabled 941 in this build of the specification). 942endif::VK_EXT_image_drm_format_modifier[] 943 ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then 944 pname:imageCreateMaybeLinear is ename:VK_TRUE. 945 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, then 946 pname:imageCreateMaybeLinear is ename:VK_FALSE. 947ifdef::VK_EXT_image_drm_format_modifier[] 948 ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 949 pname:imageCreateMaybeLinear is ename:VK_TRUE if and only if 950 pname:imageCreateDrmFormatModifiers contains 951 etext:DRM_FORMAT_MOD_LINEAR. 952endif::VK_EXT_image_drm_format_modifier[] 953 954 * Let `VkFormatFeatureFlags imageCreateFormatFeatures` be the set of valid 955 _format features_ available during image creation. 956 ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then 957 pname:imageCreateFormatFeatures is the value of 958 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 959 flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format 960 equal to slink:VkImageCreateInfo::pname:format. 961 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, 962ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 963 and if the pname:pNext chain includes no slink:VkExternalFormatANDROID 964 structure with non-zero pname:externalFormat, 965endif::VK_ANDROID_external_memory_android_hardware_buffer[] 966 then pname:imageCreateFormatFeatures is the value of 967 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 968 flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format 969 equal to slink:VkImageCreateInfo::pname:format. 970ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 971 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and if the 972 pname:pNext chain includes a slink:VkExternalFormatANDROID structure 973 with non-zero pname:externalFormat, then 974 pname:imageCreateFormatFeatures is the value of 975 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 976 obtained by flink:vkGetAndroidHardwareBufferPropertiesANDROID with a 977 matching pname:externalFormat value. 978endif::VK_ANDROID_external_memory_android_hardware_buffer[] 979ifdef::VK_FUCHSIA_buffer_collection[] 980 ** If the pname:pNext chain includes a 981 slink:VkBufferCollectionImageCreateInfoFUCHSIA structure, then 982 pname:imageCreateFormatFeatures is the value of 983 slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found 984 by calling flink:vkGetBufferCollectionPropertiesFUCHSIA with a 985 parameter pname:collection equal to 986 slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection 987endif::VK_FUCHSIA_buffer_collection[] 988ifdef::VK_EXT_image_drm_format_modifier[] 989 ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 990 the value of pname:imageCreateFormatFeatures is found by calling 991 flink:vkGetPhysicalDeviceFormatProperties2 with 992 slink:VkImageFormatProperties::pname:format equal to 993 slink:VkImageCreateInfo::pname:format and with 994 slink:VkDrmFormatModifierPropertiesListEXT chained into 995 slink:VkImageFormatProperties2; by collecting all members of the 996 returned array 997 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 998 whose pname:drmFormatModifier belongs to 999 pname:imageCreateDrmFormatModifiers; and by taking the bitwise 1000 intersection, over the collected array members, of 1001 pname:drmFormatModifierTilingFeatures. 1002 (The resultant pname:imageCreateFormatFeatures may: be empty). 1003endif::VK_EXT_image_drm_format_modifier[] 1004 1005ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1006 * Let `VkImageFormatProperties2 imageCreateImageFormatPropertiesList[]` be 1007ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1008 defined as follows. 1009 ** If slink:VkImageCreateInfo::pname:pNext contains no 1010 slink:VkExternalFormatANDROID structure with non-zero 1011 pname:externalFormat, then pname:imageCreateImageFormatPropertiesList 1012 is 1013endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1014 the list of structures obtained by calling 1015 flink:vkGetPhysicalDeviceImageFormatProperties2, possibly multiple 1016 times, as follows: 1017 *** The parameters slink:VkPhysicalDeviceImageFormatInfo2::pname:format, 1018 pname:imageType, pname:tiling, pname:usage, and pname:flags must: be 1019 equal to those in slink:VkImageCreateInfo. 1020 *** If slink:VkImageCreateInfo::pname:pNext contains a 1021 slink:VkExternalMemoryImageCreateInfo structure whose 1022 pname:handleTypes is not `0`, then 1023 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a 1024 slink:VkPhysicalDeviceExternalImageFormatInfo structure whose 1025 pname:handleType is not `0`; and 1026 flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for 1027 each handle type in 1028 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes, successively 1029 setting 1030 slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType on 1031 each call. 1032 *** If slink:VkImageCreateInfo::pname:pNext contains no 1033 slink:VkExternalMemoryImageCreateInfo structure, or contains a 1034 structure whose pname:handleTypes is `0`, then 1035 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: either 1036 contain no slink:VkPhysicalDeviceExternalImageFormatInfo structure, or 1037 contain a structure whose pname:handleType is `0`. 1038ifdef::VK_EXT_image_drm_format_modifier[] 1039 *** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 1040 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a 1041 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure where 1042 pname:sharingMode is equal to 1043 slink:VkImageCreateInfo::pname:sharingMode; and, if pname:sharingMode 1044 is ename:VK_SHARING_MODE_CONCURRENT, then pname:queueFamilyIndexCount 1045 and pname:pQueueFamilyIndices must: be equal to those in 1046 slink:VkImageCreateInfo; and, if pname:flags contains 1047 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the 1048 slink:VkImageFormatListCreateInfo structure included in the 1049 pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2 must: be 1050 equivalent to the one included in the pname:pNext chain of 1051 slink:VkImageCreateInfo; and 1052 flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for 1053 each modifier in pname:imageCreateDrmFormatModifiers, successively 1054 setting 1055 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT::pname:drmFormatModifier 1056 on each call. 1057 *** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 1058 then slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain 1059 no slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure. 1060endif::VK_EXT_image_drm_format_modifier[] 1061 *** If any call to flink:vkGetPhysicalDeviceImageFormatProperties2 returns 1062 an error, then pname:imageCreateImageFormatPropertiesList is defined 1063 to be the empty list. 1064ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1065 ** If slink:VkImageCreateInfo::pname:pNext contains a 1066 slink:VkExternalFormatANDROID structure with non-zero 1067 pname:externalFormat, then pname:imageCreateImageFormatPropertiesList 1068 contains a single element where: 1069 *** sname:VkImageFormatProperties::pname:maxMipLevels is 1070 [eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height, 1071 pname:extent.depth)){rfloor} {plus} 1#. 1072 *** sname:VkImageFormatProperties::pname:maxArrayLayers is 1073 slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. 1074 *** Each component of sname:VkImageFormatProperties::pname:maxExtent is 1075 slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D. 1076 *** sname:VkImageFormatProperties::pname:sampleCounts contains exactly 1077 ename:VK_SAMPLE_COUNT_1_BIT. 1078endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1079endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1080 1081 * Let `uint32_t imageCreateMaxMipLevels` be 1082ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1083 the value of slink:VkImageFormatProperties::pname:maxMipLevels found by 1084 calling flink:vkGetPhysicalDeviceImageFormatProperties with parameters 1085 pname:format, pname:imageType, pname:tiling, pname:usage, and 1086 pname:flags equal to those in slink:VkImageCreateInfo. 1087 If flink:vkGetPhysicalDeviceFormatProperties returns an error, then the 1088 value of pname:imageCreateMaxMipLevels is undefined:. 1089endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1090ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1091 the minimum value of slink:VkImageFormatProperties::pname:maxMipLevels 1092 in pname:imageCreateImageFormatPropertiesList. 1093 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1094 empty. 1095endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1096 1097 * Let `uint32_t imageCreateMaxArrayLayers` be 1098ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1099 defined analogously to pname:imageCreateMaxMipLevels. 1100endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1101ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1102 the minimum value of slink:VkImageFormatProperties::pname:maxArrayLayers 1103 in pname:imageCreateImageFormatPropertiesList. 1104 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1105 empty. 1106endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1107 1108 * Let `VkExtent3D imageCreateMaxExtent` be 1109ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1110 defined analogously to pname:imageCreateMaxMipLevels. 1111endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1112ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1113 the component-wise minimum over all 1114 slink:VkImageFormatProperties::pname:maxExtent values in 1115 pname:imageCreateImageFormatPropertiesList. 1116 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1117 empty. 1118endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1119 1120 * Let `VkSampleCountFlags imageCreateSampleCounts` be 1121ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1122 defined analogously to pname:imageCreateMaxMipLevels. 1123endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1124ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1125 the intersection of each 1126 slink:VkImageFormatProperties::pname:sampleCounts in 1127 pname:imageCreateImageFormatPropertiesList. 1128 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1129 empty. 1130endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1131**** 1132 1133.Valid Usage 1134**** 1135 * [[VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251]] 1136 Each of the following values (as described in 1137 <<resources-image-creation-limits,Image Creation Limits>>) must: not be 1138 undefined: : pname:imageCreateMaxMipLevels, 1139 pname:imageCreateMaxArrayLayers, pname:imageCreateMaxExtent, and 1140 pname:imageCreateSampleCounts 1141 * [[VUID-VkImageCreateInfo-sharingMode-00941]] 1142 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 1143 pname:pQueueFamilyIndices must: be a valid pointer to an array of 1144 pname:queueFamilyIndexCount code:uint32_t values 1145 * [[VUID-VkImageCreateInfo-sharingMode-00942]] 1146 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 1147 pname:queueFamilyIndexCount must: be greater than `1` 1148ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1149 * [[VUID-VkImageCreateInfo-sharingMode-01392]] 1150 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 1151 of pname:pQueueFamilyIndices must: be unique and must: be less than 1152 pname:pQueueFamilyPropertyCount returned by 1153 flink:vkGetPhysicalDeviceQueueFamilyProperties for the 1154 pname:physicalDevice that was used to create pname:device 1155endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1156ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1157 * [[VUID-VkImageCreateInfo-sharingMode-01420]] 1158 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 1159 of pname:pQueueFamilyIndices must: be unique and must: be less than 1160 pname:pQueueFamilyPropertyCount returned by either 1161 flink:vkGetPhysicalDeviceQueueFamilyProperties or 1162 flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the 1163 pname:physicalDevice that was used to create pname:device 1164endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1165ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 1166 * [[VUID-VkImageCreateInfo-format-00943]] 1167 pname:format must: not be ename:VK_FORMAT_UNDEFINED 1168endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1169ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1170 * [[VUID-VkImageCreateInfo-pNext-01974]] 1171 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 1172 structure, and its pname:externalFormat member is non-zero the 1173 pname:format must: be ename:VK_FORMAT_UNDEFINED 1174 * [[VUID-VkImageCreateInfo-pNext-01975]] 1175 If the pname:pNext chain does not include a 1176 slink:VkExternalFormatANDROID structure, or does and its 1177 pname:externalFormat member is `0`, the pname:format must: not be 1178 ename:VK_FORMAT_UNDEFINED 1179endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1180 * [[VUID-VkImageCreateInfo-extent-00944]] 1181 pname:extent.width must: be greater than `0` 1182 * [[VUID-VkImageCreateInfo-extent-00945]] 1183 pname:extent.height must: be greater than `0` 1184 * [[VUID-VkImageCreateInfo-extent-00946]] 1185 pname:extent.depth must: be greater than `0` 1186 * [[VUID-VkImageCreateInfo-mipLevels-00947]] 1187 pname:mipLevels must: be greater than `0` 1188 * [[VUID-VkImageCreateInfo-arrayLayers-00948]] 1189 pname:arrayLayers must: be greater than `0` 1190 * [[VUID-VkImageCreateInfo-flags-00949]] 1191 If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, 1192 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 1193ifdef::VK_EXT_fragment_density_map[] 1194 * [[VUID-VkImageCreateInfo-flags-02557]] 1195 If pname:flags contains 1196 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:imageType must: 1197 be ename:VK_IMAGE_TYPE_2D 1198endif::VK_EXT_fragment_density_map[] 1199ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1200 * [[VUID-VkImageCreateInfo-flags-00950]] 1201 If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, 1202 pname:imageType must: be ename:VK_IMAGE_TYPE_3D 1203endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1204 * [[VUID-VkImageCreateInfo-extent-02252]] 1205 pname:extent.width must: be less than or equal to 1206 pname:imageCreateMaxExtent.width (as defined in 1207 <<resources-image-creation-limits,Image Creation Limits>>) 1208 * [[VUID-VkImageCreateInfo-extent-02253]] 1209 pname:extent.height must: be less than or equal to 1210 pname:imageCreateMaxExtent.height (as defined in 1211 <<resources-image-creation-limits,Image Creation Limits>>) 1212 * [[VUID-VkImageCreateInfo-extent-02254]] 1213 pname:extent.depth must: be less than or equal to 1214 pname:imageCreateMaxExtent.depth (as defined in 1215 <<resources-image-creation-limits,Image Creation Limits>>) 1216 * [[VUID-VkImageCreateInfo-imageType-00954]] 1217 If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains 1218 ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and 1219 pname:extent.height must: be equal and pname:arrayLayers must: be 1220 greater than or equal to 6 1221 * [[VUID-VkImageCreateInfo-imageType-00956]] 1222 If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height 1223 and pname:extent.depth must: be `1` 1224 * [[VUID-VkImageCreateInfo-imageType-00957]] 1225 If pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.depth must: 1226 be `1` 1227 * [[VUID-VkImageCreateInfo-mipLevels-00958]] 1228 pname:mipLevels must: be less than or equal to the number of levels in 1229 the complete mipmap chain based on [eq]#pname:extent.width#, 1230 [eq]#pname:extent.height#, and [eq]#pname:extent.depth# 1231 * [[VUID-VkImageCreateInfo-mipLevels-02255]] 1232 pname:mipLevels must: be less than or equal to 1233 pname:imageCreateMaxMipLevels (as defined in 1234 <<resources-image-creation-limits,Image Creation Limits>>) 1235 * [[VUID-VkImageCreateInfo-arrayLayers-02256]] 1236 pname:arrayLayers must: be less than or equal to 1237 pname:imageCreateMaxArrayLayers (as defined in 1238 <<resources-image-creation-limits,Image Creation Limits>>) 1239 * [[VUID-VkImageCreateInfo-imageType-00961]] 1240 If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:arrayLayers must: be 1241 `1` 1242 * [[VUID-VkImageCreateInfo-samples-02257]] 1243 If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, then 1244 pname:imageType must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not 1245 contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:mipLevels must: 1246 be equal to `1`, and pname:imageCreateMaybeLinear (as defined in 1247 <<resources-image-creation-limits,Image Creation Limits>>) must: be 1248 ename:VK_FALSE, 1249ifdef::VK_EXT_fragment_density_map[] 1250 * [[VUID-VkImageCreateInfo-samples-02558]] 1251 If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, pname:usage must: 1252 not contain ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 1253endif::VK_EXT_fragment_density_map[] 1254 * [[VUID-VkImageCreateInfo-usage-00963]] 1255 If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, 1256 then bits other than ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1257 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and 1258 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must: not be set 1259 * [[VUID-VkImageCreateInfo-usage-00964]] 1260 If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1261 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, 1262 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or 1263 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be 1264 less than or equal to 1265 sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth 1266 * [[VUID-VkImageCreateInfo-usage-00965]] 1267 If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1268 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, 1269 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or 1270 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be 1271 less than or equal to 1272 sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight 1273ifdef::VK_EXT_fragment_density_map[] 1274 * [[VUID-VkImageCreateInfo-usage-02559]] 1275 If pname:usage includes 1276 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.width 1277 must: be less than or equal to 1278 latexmath:[\left\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\right\rceil] 1279 * [[VUID-VkImageCreateInfo-usage-02560]] 1280 If pname:usage includes 1281 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.height 1282 must: be less than or equal to 1283 latexmath:[\left\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\right\rceil] 1284endif::VK_EXT_fragment_density_map[] 1285 * [[VUID-VkImageCreateInfo-usage-00966]] 1286 If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, 1287 pname:usage must: also contain at least one of 1288 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1289 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or 1290 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 1291 * [[VUID-VkImageCreateInfo-samples-02258]] 1292 pname:samples must: be a bit value that is set in 1293 pname:imageCreateSampleCounts (as defined in 1294 <<resources-image-creation-limits,Image Creation Limits>>) 1295 * [[VUID-VkImageCreateInfo-usage-00968]] 1296 If the <<features-shaderStorageImageMultisample,multisampled storage 1297 images>> feature is not enabled, and pname:usage contains 1298 ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples must: be 1299 ename:VK_SAMPLE_COUNT_1_BIT 1300 * [[VUID-VkImageCreateInfo-flags-00969]] 1301 If the <<features-sparseBinding,sparse bindings>> feature is not 1302 enabled, pname:flags must: not contain 1303 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 1304 * [[VUID-VkImageCreateInfo-flags-01924]] 1305 If the <<features-sparseResidencyAliased,sparse aliased residency>> 1306 feature is not enabled, pname:flags must: not contain 1307 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 1308 * [[VUID-VkImageCreateInfo-tiling-04121]] 1309 If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:flags must: not 1310 contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1311 * [[VUID-VkImageCreateInfo-imageType-00970]] 1312 If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:flags must: not 1313 contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1314 * [[VUID-VkImageCreateInfo-imageType-00971]] 1315 If the <<features-sparseResidencyImage2D,sparse residency for 2D 1316 images>> feature is not enabled, and pname:imageType is 1317 ename:VK_IMAGE_TYPE_2D, pname:flags must: not contain 1318 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1319 * [[VUID-VkImageCreateInfo-imageType-00972]] 1320 If the <<features-sparseResidencyImage3D,sparse residency for 3D 1321 images>> feature is not enabled, and pname:imageType is 1322 ename:VK_IMAGE_TYPE_3D, pname:flags must: not contain 1323 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1324 * [[VUID-VkImageCreateInfo-imageType-00973]] 1325 If the <<features-sparseResidency2Samples,sparse residency for images 1326 with 2 samples>> feature is not enabled, pname:imageType is 1327 ename:VK_IMAGE_TYPE_2D, and pname:samples is 1328 ename:VK_SAMPLE_COUNT_2_BIT, pname:flags must: not contain 1329 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1330 * [[VUID-VkImageCreateInfo-imageType-00974]] 1331 If the <<features-sparseResidency4Samples,sparse residency for images 1332 with 4 samples>> feature is not enabled, pname:imageType is 1333 ename:VK_IMAGE_TYPE_2D, and pname:samples is 1334 ename:VK_SAMPLE_COUNT_4_BIT, pname:flags must: not contain 1335 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1336 * [[VUID-VkImageCreateInfo-imageType-00975]] 1337 If the <<features-sparseResidency8Samples,sparse residency for images 1338 with 8 samples>> feature is not enabled, pname:imageType is 1339 ename:VK_IMAGE_TYPE_2D, and pname:samples is 1340 ename:VK_SAMPLE_COUNT_8_BIT, pname:flags must: not contain 1341 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1342 * [[VUID-VkImageCreateInfo-imageType-00976]] 1343 If the <<features-sparseResidency16Samples,sparse residency for images 1344 with 16 samples>> feature is not enabled, pname:imageType is 1345 ename:VK_IMAGE_TYPE_2D, and pname:samples is 1346 ename:VK_SAMPLE_COUNT_16_BIT, pname:flags must: not contain 1347 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1348 * [[VUID-VkImageCreateInfo-flags-00987]] 1349 If pname:flags contains ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or 1350 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must: also contain 1351 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 1352 * [[VUID-VkImageCreateInfo-None-01925]] 1353 If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1354 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 1355 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, 1356 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must: not also be set 1357ifdef::VK_VERSION_1_1[] 1358 * [[VUID-VkImageCreateInfo-flags-01890]] 1359 If the protected memory feature is not enabled, pname:flags must: not 1360 contain ename:VK_IMAGE_CREATE_PROTECTED_BIT 1361 * [[VUID-VkImageCreateInfo-None-01891]] 1362 If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1363 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 1364 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, 1365 ename:VK_IMAGE_CREATE_PROTECTED_BIT must: not also be set 1366endif::VK_VERSION_1_1[] 1367ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1368ifdef::VK_NV_external_memory[] 1369 * [[VUID-VkImageCreateInfo-pNext-00988]] 1370 If the pname:pNext chain includes a 1371 slink:VkExternalMemoryImageCreateInfoNV structure, it must: not contain 1372 a slink:VkExternalMemoryImageCreateInfo structure 1373endif::VK_NV_external_memory[] 1374 * [[VUID-VkImageCreateInfo-pNext-00990]] 1375 If the pname:pNext chain includes a 1376 slink:VkExternalMemoryImageCreateInfo structure, its pname:handleTypes 1377 member must: only contain bits that are also in 1378 slink:VkExternalImageFormatProperties::pname:externalMemoryProperties.compatibleHandleTypes, 1379 as returned by flink:vkGetPhysicalDeviceImageFormatProperties2 with 1380 pname:format, pname:imageType, pname:tiling, pname:usage, and 1381 pname:flags equal to those in this structure, and with a 1382 slink:VkPhysicalDeviceExternalImageFormatInfo structure included in the 1383 pname:pNext chain, with a pname:handleType equal to any one of the 1384 handle types specified in 1385 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes 1386endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1387ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[] 1388 * [[VUID-VkImageCreateInfo-pNext-00991]] 1389 If the pname:pNext chain includes a 1390 slink:VkExternalMemoryImageCreateInfoNV structure, its pname:handleTypes 1391 member must: only contain bits that are also in 1392 slink:VkExternalImageFormatPropertiesNV::pname:externalMemoryProperties.compatibleHandleTypes, 1393 as returned by flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV 1394 with pname:format, pname:imageType, pname:tiling, pname:usage, and 1395 pname:flags equal to those in this structure, and with 1396 pname:externalHandleType equal to any one of the handle types specified 1397 in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes 1398endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[] 1399ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1400 * [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]] 1401 If the logical device was created with 1402 slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to 1403 1, pname:flags must: not contain 1404 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT 1405 * [[VUID-VkImageCreateInfo-flags-02259]] 1406 If pname:flags contains 1407 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then 1408 pname:mipLevels must: be one, pname:arrayLayers must: be one, 1409 pname:imageType must: be ename:VK_IMAGE_TYPE_2D. 1410 and pname:imageCreateMaybeLinear (as defined in 1411 <<resources-image-creation-limits,Image Creation Limits>>) must: be 1412 ename:VK_FALSE 1413endif::VK_VERSION_1_1,VK_KHR_device_group[] 1414ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1415 * [[VUID-VkImageCreateInfo-flags-01572]] 1416 If pname:flags contains 1417 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:format 1418 must: be a <<compressed_image_formats,compressed image format>> 1419 * [[VUID-VkImageCreateInfo-flags-01573]] 1420 If pname:flags contains 1421 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:flags 1422 must: also contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 1423endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1424 * [[VUID-VkImageCreateInfo-initialLayout-00993]] 1425 pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or 1426 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 1427ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 1428 * [[VUID-VkImageCreateInfo-pNext-01443]] 1429 If the pname:pNext chain includes a 1430 slink:VkExternalMemoryImageCreateInfo or 1431 sname:VkExternalMemoryImageCreateInfoNV structure whose 1432 pname:handleTypes member is not `0`, pname:initialLayout must: be 1433 ename:VK_IMAGE_LAYOUT_UNDEFINED 1434endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 1435ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 1436 * [[VUID-VkImageCreateInfo-format-06410]] 1437 If the image pname:format is one of the 1438 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 1439 sampler Y'C~B~C~R~ conversion>>, pname:mipLevels must: be 1 1440 * [[VUID-VkImageCreateInfo-format-06411]] 1441 If the image pname:format is one of the 1442 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 1443 sampler Y'C~B~C~R~ conversion>>, pname:samples must: be 1444 ename:VK_SAMPLE_COUNT_1_BIT 1445 * [[VUID-VkImageCreateInfo-format-06412]] 1446 If the image pname:format is one of the 1447 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 1448 sampler Y'C~B~C~R~ conversion>>, pname:imageType must: be 1449 ename:VK_IMAGE_TYPE_2D 1450ifdef::VK_EXT_ycbcr_image_arrays[] 1451 * [[VUID-VkImageCreateInfo-format-06413]] 1452 If the image pname:format is one of the 1453 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 1454 sampler Y'C~B~C~R~ conversion>>, and the pname:ycbcrImageArrays feature 1455 is not enabled, pname:arrayLayers must: be 1 1456endif::VK_EXT_ycbcr_image_arrays[] 1457ifndef::VK_EXT_ycbcr_image_arrays[] 1458 * [[VUID-VkImageCreateInfo-format-06414]] 1459 If the image pname:format is one of the 1460 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 1461 sampler Y'C~B~C~R~ conversion>>, pname:arrayLayers must: be 1 1462endif::VK_EXT_ycbcr_image_arrays[] 1463 * [[VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260]] 1464 If pname:format is a _multi-planar_ format, and if 1465 pname:imageCreateFormatFeatures (as defined in 1466 <<resources-image-creation-limits,Image Creation Limits>>) does not 1467 contain ename:VK_FORMAT_FEATURE_DISJOINT_BIT, then pname:flags must: not 1468 contain ename:VK_IMAGE_CREATE_DISJOINT_BIT 1469 * [[VUID-VkImageCreateInfo-format-01577]] 1470 If pname:format is not a _multi-planar_ format, and pname:flags does not 1471 include ename:VK_IMAGE_CREATE_ALIAS_BIT, pname:flags must: not contain 1472 ename:VK_IMAGE_CREATE_DISJOINT_BIT 1473 * [[VUID-VkImageCreateInfo-format-04712]] 1474 If pname:format has a code:_422 or code:_420 suffix, pname:width must: 1475 be a multiple of 2 1476 * [[VUID-VkImageCreateInfo-format-04713]] 1477 If pname:format has a code:_420 suffix, pname:height must: be a multiple 1478 of 2 1479endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 1480ifdef::VK_EXT_image_drm_format_modifier[] 1481 * [[VUID-VkImageCreateInfo-tiling-02261]] 1482 If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 1483 the pname:pNext chain must: include exactly one of 1484 slink:VkImageDrmFormatModifierListCreateInfoEXT or 1485 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structures 1486 * [[VUID-VkImageCreateInfo-pNext-02262]] 1487 If the pname:pNext chain includes a 1488 slink:VkImageDrmFormatModifierListCreateInfoEXT or 1489 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then 1490 pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 1491 * [[VUID-VkImageCreateInfo-tiling-02353]] 1492 If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and 1493 pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the 1494 pname:pNext chain must: include a slink:VkImageFormatListCreateInfo 1495 structure with non-zero pname:viewFormatCount 1496endif::VK_EXT_image_drm_format_modifier[] 1497ifdef::VK_EXT_sample_locations[] 1498 * [[VUID-VkImageCreateInfo-flags-01533]] 1499 If pname:flags contains 1500 ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 1501 pname:format must: be a depth or depth/stencil format 1502endif::VK_EXT_sample_locations[] 1503ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1504 * [[VUID-VkImageCreateInfo-pNext-02393]] 1505 If the pname:pNext chain includes a 1506 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 1507 member includes 1508 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, 1509 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 1510 * [[VUID-VkImageCreateInfo-pNext-02394]] 1511 If the pname:pNext chain includes a 1512 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 1513 member includes 1514 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, 1515 pname:mipLevels must: either be `1` or equal to the number of levels in 1516 the complete mipmap chain based on [eq]#pname:extent.width#, 1517 [eq]#pname:extent.height#, and [eq]#pname:extent.depth# 1518 * [[VUID-VkImageCreateInfo-pNext-02396]] 1519 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 1520 structure whose pname:externalFormat member is not `0`, pname:flags 1521 must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 1522 * [[VUID-VkImageCreateInfo-pNext-02397]] 1523 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 1524 structure whose pname:externalFormat member is not `0`, pname:usage 1525 must: not include any usages except ename:VK_IMAGE_USAGE_SAMPLED_BIT 1526 * [[VUID-VkImageCreateInfo-pNext-02398]] 1527 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 1528 structure whose pname:externalFormat member is not `0`, pname:tiling 1529 must: be ename:VK_IMAGE_TILING_OPTIMAL 1530endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1531ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 1532 * [[VUID-VkImageCreateInfo-format-02795]] 1533 If pname:format is a depth-stencil format, pname:usage includes 1534 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext 1535 chain includes a slink:VkImageStencilUsageCreateInfo structure, then its 1536 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 1537 also include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 1538 * [[VUID-VkImageCreateInfo-format-02796]] 1539 If pname:format is a depth-stencil format, pname:usage does not include 1540 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext 1541 chain includes a slink:VkImageStencilUsageCreateInfo structure, then its 1542 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 1543 also not include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 1544 * [[VUID-VkImageCreateInfo-format-02797]] 1545 If pname:format is a depth-stencil format, pname:usage includes 1546 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain 1547 includes a slink:VkImageStencilUsageCreateInfo structure, then its 1548 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 1549 also include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 1550 * [[VUID-VkImageCreateInfo-format-02798]] 1551 If pname:format is a depth-stencil format, pname:usage does not include 1552 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain 1553 includes a slink:VkImageStencilUsageCreateInfo structure, then its 1554 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 1555 also not include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 1556 * [[VUID-VkImageCreateInfo-Format-02536]] 1557 If pname:Format is a depth-stencil format and the pname:pNext chain 1558 includes a slink:VkImageStencilUsageCreateInfo structure with its 1559 pname:stencilUsage member including 1560 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be 1561 less than or equal to 1562 sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth 1563 * [[VUID-VkImageCreateInfo-format-02537]] 1564 If pname:format is a depth-stencil format and the pname:pNext chain 1565 includes a slink:VkImageStencilUsageCreateInfo structure with its 1566 pname:stencilUsage member including 1567 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be 1568 less than or equal to 1569 sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight 1570 * [[VUID-VkImageCreateInfo-format-02538]] 1571 If the <<features-shaderStorageImageMultisample,multisampled storage 1572 images>> feature is not enabled, pname:format is a depth-stencil format 1573 and the pname:pNext chain includes a slink:VkImageStencilUsageCreateInfo 1574 structure with its pname:stencilUsage including 1575 ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples must: be 1576 ename:VK_SAMPLE_COUNT_1_BIT 1577endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 1578ifdef::VK_NV_corner_sampled_image[] 1579 * [[VUID-VkImageCreateInfo-flags-02050]] 1580 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, 1581 pname:imageType must: be ename:VK_IMAGE_TYPE_2D or 1582 ename:VK_IMAGE_TYPE_3D 1583 * [[VUID-VkImageCreateInfo-flags-02051]] 1584 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, it 1585 must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT and the 1586 pname:format must: not be a depth/stencil format 1587 * [[VUID-VkImageCreateInfo-flags-02052]] 1588 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and 1589 pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.width and 1590 pname:extent.height must: be greater than `1` 1591 * [[VUID-VkImageCreateInfo-flags-02053]] 1592 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and 1593 pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width, 1594 pname:extent.height, and pname:extent.depth must: be greater than `1` 1595endif::VK_NV_corner_sampled_image[] 1596ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1597 * [[VUID-VkImageCreateInfo-imageType-02082]] 1598 If pname:usage includes 1599 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 1600 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 1601 * [[VUID-VkImageCreateInfo-samples-02083]] 1602 If pname:usage includes 1603 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 1604 pname:samples must: be ename:VK_SAMPLE_COUNT_1_BIT 1605endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1606ifdef::VK_NV_shading_rate_image[] 1607 * [[VUID-VkImageCreateInfo-tiling-02084]] 1608 If pname:usage includes ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, 1609 pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL 1610endif::VK_NV_shading_rate_image[] 1611ifdef::VK_EXT_fragment_density_map[] 1612 * [[VUID-VkImageCreateInfo-flags-02565]] 1613 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 1614 pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL 1615 * [[VUID-VkImageCreateInfo-flags-02566]] 1616 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 1617 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 1618 * [[VUID-VkImageCreateInfo-flags-02567]] 1619 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 1620 pname:flags must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT 1621 * [[VUID-VkImageCreateInfo-flags-02568]] 1622 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 1623 pname:mipLevels must: be `1` 1624endif::VK_EXT_fragment_density_map[] 1625ifdef::VK_HUAWEI_invocation_mask[] 1626 * [[VUID-VkImageCreateInfo-usage-04992]] 1627 If pname:usage includes ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, 1628 pname:tiling must: be ename:VK_IMAGE_TILING_LINEAR 1629endif::VK_HUAWEI_invocation_mask[] 1630ifdef::VK_KHR_portability_subset[] 1631 * [[VUID-VkImageCreateInfo-imageView2DOn3DImage-04459]] 1632 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 1633 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageView2DOn3DImage 1634 is ename:VK_FALSE, pname:flags must: not contain 1635 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT 1636 * [[VUID-VkImageCreateInfo-multisampleArrayImage-04460]] 1637 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 1638 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:multisampleArrayImage 1639 is ename:VK_FALSE, and pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, 1640 then pname:arrayLayers must: be `1` 1641endif::VK_KHR_portability_subset[] 1642ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 1643 * [[VUID-VkImageCreateInfo-pNext-04737]] 1644 If a slink:VkImageFormatListCreateInfo structure was included in the 1645 pname:pNext chain and 1646 slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero, 1647 then all of the formats in 1648 slink:VkImageFormatListCreateInfo::pname:pViewFormats must: be 1649 compatible with the pname:format as described in the 1650 <<formats-compatibility,compatibility table>> 1651 * [[VUID-VkImageCreateInfo-flags-04738]] 1652 If pname:flags does not contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 1653 and the pname:pNext chain includes a slink:VkImageFormatListCreateInfo 1654 structure, then slink:VkImageFormatListCreateInfo::pname:viewFormatCount 1655 must: be `0` or `1` 1656endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 1657ifdef::VK_KHR_video_decode_queue[] 1658 * [[VUID-VkImageCreateInfo-usage-04815]] 1659 If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, 1660 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, 1661 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:pNext 1662 chain must: include a valid slink:VkVideoProfilesKHR structure which 1663 includes at least one slink:VkVideoProfileKHR with a decode 1664 codec-operation 1665endif::VK_KHR_video_decode_queue[] 1666ifdef::VK_KHR_video_encode_queue[] 1667 * [[VUID-VkImageCreateInfo-usage-04816]] 1668 If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 1669 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, 1670 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:pNext 1671 chain must: include a valid slink:VkVideoProfilesKHR structure which 1672 includes at least one slink:VkVideoProfileKHR with a encode 1673 codec-operation 1674endif::VK_KHR_video_encode_queue[] 1675ifdef::VK_FUCHSIA_buffer_collection[] 1676 * [[VUID-VkImageCreateInfo-pNext-06390]] 1677 If the slink:VkImage is to be used to import memory from a 1678 slink:VkBufferCollectionFUCHSIA, a 1679 slink:VkBufferCollectionImageCreateInfoFUCHSIA structure must: be 1680 chained to pname:pNext. 1681endif::VK_FUCHSIA_buffer_collection[] 1682**** 1683 1684include::{generated}/validity/structs/VkImageCreateInfo.txt[] 1685-- 1686 1687ifdef::VK_FUCHSIA_buffer_collection[] 1688[open,refpage='VkBufferCollectionImageCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkImage',type='structs'] 1689-- 1690The sname:VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as: 1691 1692include::{generated}/api/structs/VkBufferCollectionImageCreateInfoFUCHSIA.txt[] 1693 1694 * pname:sType is the type of this structure 1695 * pname:pNext is `NULL` or a pointer to a structure extending this 1696 structure 1697 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 1698 * pname:index is the index of the buffer in the buffer collection from 1699 which the memory will be imported 1700 1701.Valid Usage 1702**** 1703 * [[VUID-VkBufferCollectionImageCreateInfoFUCHSIA-index-06391]] 1704 pname:index must: be less than 1705 slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount 1706**** 1707 1708include::{generated}/validity/structs/VkBufferCollectionImageCreateInfoFUCHSIA.txt[] 1709-- 1710endif::VK_FUCHSIA_buffer_collection[] 1711 1712ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 1713[open,refpage='VkImageStencilUsageCreateInfo',desc='Specify separate usage flags for the stencil aspect of a depth-stencil image',type='structs',alias='VkImageStencilUsageCreateInfoEXT'] 1714-- 1715The sname:VkImageStencilUsageCreateInfo structure is defined as: 1716 1717include::{generated}/api/structs/VkImageStencilUsageCreateInfo.txt[] 1718 1719ifdef::VK_EXT_separate_stencil_usage[] 1720or the equivalent 1721 1722include::{generated}/api/structs/VkImageStencilUsageCreateInfoEXT.txt[] 1723endif::VK_EXT_separate_stencil_usage[] 1724 1725 * pname:sType is the type of this structure. 1726 * pname:pNext is `NULL` or a pointer to a structure extending this 1727 structure. 1728 * pname:stencilUsage is a bitmask of elink:VkImageUsageFlagBits describing 1729 the intended usage of the stencil aspect of the image. 1730 1731If the pname:pNext chain of slink:VkImageCreateInfo includes a 1732sname:VkImageStencilUsageCreateInfo structure, then that structure includes 1733the usage flags specific to the stencil aspect of the image for an image 1734with a depth-stencil format. 1735 1736This structure specifies image usages which only apply to the stencil aspect 1737of a depth/stencil format image. 1738When this structure is included in the pname:pNext chain of 1739slink:VkImageCreateInfo, the stencil aspect of the image must: only be used 1740as specified by pname:stencilUsage. 1741When this structure is not included in the pname:pNext chain of 1742slink:VkImageCreateInfo, the stencil aspect of an image must: only be used 1743as specified by slink:VkImageCreateInfo::pname:usage. 1744Use of other aspects of an image are unaffected by this structure. 1745 1746This structure can: also be included in the pname:pNext chain of 1747slink:VkPhysicalDeviceImageFormatInfo2 to query additional capabilities 1748specific to image creation parameter combinations including a separate set 1749of usage flags for the stencil aspect of the image using 1750flink:vkGetPhysicalDeviceImageFormatProperties2. 1751When this structure is not included in the pname:pNext chain of 1752sname:VkPhysicalDeviceImageFormatInfo2 then the implicit value of 1753pname:stencilUsage matches that of 1754sname:VkPhysicalDeviceImageFormatInfo2::pname:usage. 1755 1756.Valid Usage 1757**** 1758 * [[VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539]] 1759 If pname:stencilUsage includes 1760 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, it must: not include bits 1761 other than ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT or 1762 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 1763**** 1764 1765include::{generated}/validity/structs/VkImageStencilUsageCreateInfo.txt[] 1766-- 1767endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 1768 1769ifdef::VK_NV_dedicated_allocation[] 1770[open,refpage='VkDedicatedAllocationImageCreateInfoNV',desc='Specify that an image is bound to a dedicated memory resource',type='structs'] 1771-- 1772If the pname:pNext chain includes a 1773sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure 1774includes an enable controlling whether the image will have a dedicated 1775memory allocation bound to it. 1776 1777The sname:VkDedicatedAllocationImageCreateInfoNV structure is defined as: 1778 1779include::{generated}/api/structs/VkDedicatedAllocationImageCreateInfoNV.txt[] 1780 1781 * pname:sType is the type of this structure. 1782 * pname:pNext is `NULL` or a pointer to a structure extending this 1783 structure. 1784 * pname:dedicatedAllocation specifies whether the image will have a 1785 dedicated allocation bound to it. 1786 1787[NOTE] 1788.Note 1789==== 1790Using a dedicated allocation for color and depth/stencil attachments or 1791other large images may: improve performance on some devices. 1792==== 1793 1794.Valid Usage 1795**** 1796 * [[VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994]] 1797 If pname:dedicatedAllocation is ename:VK_TRUE, 1798 slink:VkImageCreateInfo::pname:flags must: not include 1799 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1800 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 1801 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 1802**** 1803 1804include::{generated}/validity/structs/VkDedicatedAllocationImageCreateInfoNV.txt[] 1805-- 1806endif::VK_NV_dedicated_allocation[] 1807 1808ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1809[open,refpage='VkExternalMemoryImageCreateInfo',desc='Specify that an image may be backed by external memory',type='structs'] 1810-- 1811To define a set of external memory handle types that may: be used as backing 1812store for an image, add a slink:VkExternalMemoryImageCreateInfo structure to 1813the pname:pNext chain of the slink:VkImageCreateInfo structure. 1814The sname:VkExternalMemoryImageCreateInfo structure is defined as: 1815 1816include::{generated}/api/structs/VkExternalMemoryImageCreateInfo.txt[] 1817 1818ifdef::VK_KHR_external_memory[] 1819or the equivalent 1820 1821include::{generated}/api/structs/VkExternalMemoryImageCreateInfoKHR.txt[] 1822endif::VK_KHR_external_memory[] 1823 1824[NOTE] 1825.Note 1826==== 1827A sname:VkExternalMemoryImageCreateInfo structure with a non-zero 1828pname:handleTypes field must be included in the creation parameters for an 1829image that will be bound to memory that is either exported or imported. 1830==== 1831 1832 * pname:sType is the type of this structure. 1833 * pname:pNext is `NULL` or a pointer to a structure extending this 1834 structure. 1835 * pname:handleTypes is zero, or a bitmask of 1836 elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external 1837 memory handle types. 1838 1839include::{generated}/validity/structs/VkExternalMemoryImageCreateInfo.txt[] 1840-- 1841endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1842 1843ifdef::VK_NV_external_memory[] 1844[open,refpage='VkExternalMemoryImageCreateInfoNV',desc='Specify that an image may be backed by external memory',type='structs'] 1845-- 1846If the pname:pNext chain includes a sname:VkExternalMemoryImageCreateInfoNV 1847structure, then that structure defines a set of external memory handle types 1848that may: be used as backing store for the image. 1849 1850The sname:VkExternalMemoryImageCreateInfoNV structure is defined as: 1851 1852include::{generated}/api/structs/VkExternalMemoryImageCreateInfoNV.txt[] 1853 1854 * pname:sType is the type of this structure. 1855 * pname:pNext is `NULL` or a pointer to a structure extending this 1856 structure. 1857 * pname:handleTypes is zero, or a bitmask of 1858 elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more 1859 external memory handle types. 1860 1861include::{generated}/validity/structs/VkExternalMemoryImageCreateInfoNV.txt[] 1862-- 1863endif::VK_NV_external_memory[] 1864 1865ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1866[open,refpage='VkExternalFormatANDROID',desc='Structure containing an Android hardware buffer external format',type='structs'] 1867-- 1868To create an image with an 1869<<memory-external-android-hardware-buffer-external-formats,external 1870format>>, add a sname:VkExternalFormatANDROID structure in the pname:pNext 1871chain of slink:VkImageCreateInfo. 1872sname:VkExternalFormatANDROID is defined as: 1873 1874include::{generated}/api/structs/VkExternalFormatANDROID.txt[] 1875 1876 * pname:sType is the type of this structure. 1877 * pname:pNext is `NULL` or a pointer to a structure extending this 1878 structure. 1879 * pname:externalFormat is an implementation-defined identifier for the 1880 external format 1881 1882If pname:externalFormat is zero, the effect is as if the 1883sname:VkExternalFormatANDROID structure was not present. 1884Otherwise, the pname:image will have the specified external format. 1885 1886.Valid Usage 1887**** 1888 * [[VUID-VkExternalFormatANDROID-externalFormat-01894]] 1889 pname:externalFormat must: be `0` or a value returned in the 1890 pname:externalFormat member of 1891 slink:VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call 1892 to flink:vkGetAndroidHardwareBufferPropertiesANDROID 1893**** 1894 1895include::{generated}/validity/structs/VkExternalFormatANDROID.txt[] 1896-- 1897endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1898 1899ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1900ifdef::VK_KHR_swapchain[] 1901[open,refpage='VkImageSwapchainCreateInfoKHR',desc='Specify that an image will be bound to swapchain memory',type='structs'] 1902-- 1903If the pname:pNext chain of slink:VkImageCreateInfo includes a 1904sname:VkImageSwapchainCreateInfoKHR structure, then that structure includes 1905a swapchain handle indicating that the image will be bound to memory from 1906that swapchain. 1907 1908The sname:VkImageSwapchainCreateInfoKHR structure is defined as: 1909 1910include::{generated}/api/structs/VkImageSwapchainCreateInfoKHR.txt[] 1911 1912 * pname:sType is the type of this structure. 1913 * pname:pNext is `NULL` or a pointer to a structure extending this 1914 structure. 1915 * pname:swapchain is dlink:VK_NULL_HANDLE or a handle of a swapchain that 1916 the image will be bound to. 1917 1918.Valid Usage 1919**** 1920 * [[VUID-VkImageSwapchainCreateInfoKHR-swapchain-00995]] 1921 If pname:swapchain is not dlink:VK_NULL_HANDLE, the fields of 1922 slink:VkImageCreateInfo must: match the 1923 <<swapchain-wsi-image-create-info, implied image creation parameters>> 1924 of the swapchain 1925**** 1926 1927include::{generated}/validity/structs/VkImageSwapchainCreateInfoKHR.txt[] 1928-- 1929endif::VK_KHR_swapchain[] 1930endif::VK_VERSION_1_1,VK_KHR_device_group[] 1931 1932ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 1933[open,refpage='VkImageFormatListCreateInfo',desc='Specify that an image can: be used with a particular set of formats',type='structs',alias='VkImageFormatListCreateInfoKHR'] 1934-- 1935If the pname:pNext chain of slink:VkImageCreateInfo includes a 1936sname:VkImageFormatListCreateInfo structure, then that structure contains a 1937list of all formats that can: be used when creating views of this image. 1938 1939The sname:VkImageFormatListCreateInfo structure is defined as: 1940 1941include::{generated}/api/structs/VkImageFormatListCreateInfo.txt[] 1942 1943ifdef::VK_KHR_image_format_list[] 1944or the equivalent 1945 1946include::{generated}/api/structs/VkImageFormatListCreateInfoKHR.txt[] 1947endif::VK_KHR_image_format_list[] 1948 1949 * pname:sType is the type of this structure. 1950 * pname:pNext is `NULL` or a pointer to a structure extending this 1951 structure. 1952 * pname:viewFormatCount is the number of entries in the pname:pViewFormats 1953 array. 1954 * pname:pViewFormats is a pointer to an array of elink:VkFormat values 1955 specifying all formats which can: be used when creating views of this 1956 image. 1957 1958If pname:viewFormatCount is zero, pname:pViewFormats is ignored and the 1959image is created as if the sname:VkImageFormatListCreateInfo structure were 1960not included in the pname:pNext chain of slink:VkImageCreateInfo. 1961 1962include::{generated}/validity/structs/VkImageFormatListCreateInfo.txt[] 1963-- 1964endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 1965 1966ifdef::VK_EXT_image_drm_format_modifier[] 1967[open,refpage='VkImageDrmFormatModifierListCreateInfoEXT',desc='Specify that an image must be created with a DRM format modifier from the provided list',type='structs'] 1968-- 1969If the pname:pNext chain of slink:VkImageCreateInfo includes a 1970slink:VkImageDrmFormatModifierListCreateInfoEXT structure, then the image 1971will be created with one of the <<glossary-drm-format-modifier,Linux DRM 1972format modifiers>> listed in the structure. 1973The choice of modifier is implementation-dependent. 1974 1975The slink:VkImageDrmFormatModifierListCreateInfoEXT structure is defined as: 1976 1977include::{generated}/api/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] 1978 1979 * pname:sType is the type of this structure. 1980 * pname:pNext is `NULL` or a pointer to a structure extending this 1981 structure. 1982 * pname:drmFormatModifierCount is the length of the 1983 pname:pDrmFormatModifiers array. 1984 * pname:pDrmFormatModifiers is a pointer to an array of _Linux DRM format 1985 modifiers_. 1986 1987.Valid Usage 1988**** 1989 * [[VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-02263]] 1990 Each _modifier_ in pname:pDrmFormatModifiers must: be compatible with 1991 the parameters in slink:VkImageCreateInfo and its pname:pNext chain, as 1992 determined by querying slink:VkPhysicalDeviceImageFormatInfo2 extended 1993 with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 1994**** 1995 1996include::{generated}/validity/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] 1997-- 1998 1999[open,refpage='VkImageDrmFormatModifierExplicitCreateInfoEXT',desc='Specify that an image be created with the provided DRM format modifier and explicit memory layout',type='structs'] 2000-- 2001If the pname:pNext chain of slink:VkImageCreateInfo includes a 2002slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the 2003image will be created with the <<glossary-drm-format-modifier,Linux DRM 2004format modifier>> and memory layout defined by the structure. 2005 2006The slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined 2007as: 2008 2009include::{generated}/api/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] 2010 2011 * pname:sType is the type of this structure. 2012 * pname:pNext is `NULL` or a pointer to a structure extending this 2013 structure. 2014 * pname:drmFormatModifier is the _Linux DRM format modifier_ with which 2015 the image will be created. 2016 * pname:drmFormatModifierPlaneCount is the number of _memory planes_ in 2017 the image (as reported by slink:VkDrmFormatModifierPropertiesEXT) as 2018 well as the length of the pname:pPlaneLayouts array. 2019 * pname:pPlaneLayouts is a pointer to an array of 2020 slink:VkSubresourceLayout structures describing the image's _memory 2021 planes_. 2022 2023The etext:i^th^ member of pname:pPlaneLayouts describes the layout of the 2024image's etext:i^th^ _memory plane_ (that is, 2025`VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`). 2026In each element of pname:pPlaneLayouts, the implementation must: ignore 2027pname:size. 2028The implementation calculates the size of each plane, which the application 2029can: query with flink:vkGetImageSubresourceLayout. 2030 2031When creating an image with 2032slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application's 2033responsibility to satisfy all valid usage requirements. 2034However, the implementation must: validate that the provided 2035pname:pPlaneLayouts, when combined with the provided pname:drmFormatModifier 2036and other creation parameters in slink:VkImageCreateInfo and its pname:pNext 2037chain, produce a valid image. 2038(This validation is necessarily implementation-dependent and outside the 2039scope of Vulkan, and therefore not described by valid usage requirements). 2040If this validation fails, then flink:vkCreateImage returns 2041ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. 2042 2043.Valid Usage 2044**** 2045 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifier-02264]] 2046 pname:drmFormatModifier must: be compatible with the parameters in 2047 slink:VkImageCreateInfo and its pname:pNext chain, as determined by 2048 querying slink:VkPhysicalDeviceImageFormatInfo2 extended with 2049 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 2050 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-02265]] 2051 pname:drmFormatModifierPlaneCount must: be equal to the 2052 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 2053 associated with slink:VkImageCreateInfo::pname:format and 2054 pname:drmFormatModifier, as found by querying 2055 slink:VkDrmFormatModifierPropertiesListEXT 2056 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-size-02267]] 2057 For each element of pname:pPlaneLayouts, pname:size must: be 0 2058 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-arrayPitch-02268]] 2059 For each element of pname:pPlaneLayouts, pname:arrayPitch must: be 0 if 2060 slink:VkImageCreateInfo::pname:arrayLayers is 1 2061 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-depthPitch-02269]] 2062 For each element of pname:pPlaneLayouts, pname:depthPitch must: be 0 if 2063 slink:VkImageCreateInfo::pname:extent.depth is 1 2064**** 2065 2066include::{generated}/validity/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] 2067-- 2068endif::VK_EXT_image_drm_format_modifier[] 2069 2070[open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums'] 2071-- 2072Bits which can: be set in 2073ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2074slink:VkImageViewUsageCreateInfo::pname:usage, or 2075endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2076ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2077slink:VkImageStencilUsageCreateInfo::pname:stencilUsage, or 2078endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2079slink:VkImageCreateInfo::pname:usage, specifying intended usage of an image, 2080are: 2081 2082include::{generated}/api/enums/VkImageUsageFlagBits.txt[] 2083 2084 * ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can: be 2085 used as the source of a transfer command. 2086 * ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can: be 2087 used as the destination of a transfer command. 2088 * ename:VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can: be used 2089 to create a sname:VkImageView suitable for occupying a 2090 sname:VkDescriptorSet slot either of type 2091 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 2092 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a 2093 shader. 2094 * ename:VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can: be used 2095 to create a sname:VkImageView suitable for occupying a 2096 sname:VkDescriptorSet slot of type 2097 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. 2098 * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can: 2099 be used to create a sname:VkImageView suitable for use as a color or 2100 resolve attachment in a sname:VkFramebuffer. 2101 * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the 2102 image can: be used to create a sname:VkImageView suitable for use as a 2103 depth/stencil 2104ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 2105 or depth/stencil resolve 2106endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 2107 attachment in a sname:VkFramebuffer. 2108 * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that 2109 implementations may: support using <<memory, memory allocations>> with 2110 the ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT to back an image with 2111 this usage. 2112 This bit can: be set for any image that can: be used to create a 2113 sname:VkImageView suitable for use as a color, resolve, depth/stencil, 2114 or input attachment. 2115 * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can: 2116 be used to create a sname:VkImageView suitable for occupying 2117 sname:VkDescriptorSet slot of type 2118 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an 2119 input attachment; and be used as an input attachment in a framebuffer. 2120ifdef::VK_EXT_fragment_density_map[] 2121 * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT specifies that the 2122 image can: be used to create a sname:VkImageView suitable for use as a 2123 <<fragmentdensitymapops, fragment density map image>>. 2124endif::VK_EXT_fragment_density_map[] 2125ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 2126 * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies 2127 that the image can: be used to create a sname:VkImageView suitable for 2128 use as a 2129ifdef::VK_KHR_fragment_shading_rate[] 2130 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 2131 attachment>> 2132endif::VK_KHR_fragment_shading_rate[] 2133ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] 2134ifdef::VK_NV_shading_rate_image[] 2135 <<primsrast-shading-rate-image, shading rate image>> 2136endif::VK_NV_shading_rate_image[] 2137endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 2138ifdef::VK_KHR_video_decode_queue[] 2139 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that 2140 <<video-decode-operations, video decode operations>> can use the image 2141 as a <<reference-picture,reference picture>>, or a source of 2142 postprocessing, or transfer operation. 2143 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR specifies that 2144 <<video-decode-operations, video decode operations>> can use the image 2145 as a <<video-picture-resources,DPB Video Picture Resource>>, 2146 representing a <<reference-picture,reference picture>>. 2147 This flag must: be combined with 2148 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR and 2149 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR. 2150 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR is required for DPB image 2151 resources because these resources will be associated with 2152 <<reference-picture,reference pictures>> after acting as targets for 2153 video decode operations. 2154 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR is required for DPB image 2155 resources because the <<reference-picture,reference pictures>> 2156 associated with them act as information sources for subsequent decode 2157 operations. 2158endif::VK_KHR_video_decode_queue[] 2159ifdef::VK_KHR_video_encode_queue[] 2160 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR specifies that the image 2161 can be used as an <<input-encode-picture,input picture>> for 2162 <<video-encode-operations, video encode operations>>. 2163 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR specifies that 2164 <<video-encode-operations, video encode operations>> can use the image 2165 to hold a <<video-picture-resources,reconstructed picture>>, and to act 2166 as a <<reference-picture,reference picture>>. 2167 This flag must: be combined with 2168 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR and 2169 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR. 2170 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR is required for a DPB 2171 image resource because the reconstructed picture resulting from an 2172 encode operation will be written to it. 2173 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR is required for DPB image 2174 resources because it can be used as a <<reference-picture,reconstructed 2175 reference picture>> source for the encode operation. 2176endif::VK_KHR_video_encode_queue[] 2177-- 2178 2179[open,refpage='VkImageUsageFlags',desc='Bitmask of VkImageUsageFlagBits',type='flags'] 2180-- 2181include::{generated}/api/flags/VkImageUsageFlags.txt[] 2182 2183tname:VkImageUsageFlags is a bitmask type for setting a mask of zero or more 2184elink:VkImageUsageFlagBits. 2185 2186[[valid-imageview-imageusage]] 2187When creating a sname:VkImageView one of the following 2188elink:VkImageUsageFlagBits must: be set: 2189 2190 * ename:VK_IMAGE_USAGE_SAMPLED_BIT 2191 * ename:VK_IMAGE_USAGE_STORAGE_BIT 2192 * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2193 * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 2194 * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 2195 * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 2196ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 2197 * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 2198endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 2199ifdef::VK_EXT_fragment_density_map[] 2200 * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 2201endif::VK_EXT_fragment_density_map[] 2202-- 2203 2204[open,refpage='VkImageCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] 2205-- 2206Bits which can: be set in slink:VkImageCreateInfo::pname:flags, specifying 2207additional parameters of an image, are: 2208 2209include::{generated}/api/enums/VkImageCreateFlagBits.txt[] 2210 2211 * ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will 2212 be backed using sparse memory binding. 2213 * ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can: 2214 be partially backed using sparse memory binding. 2215 Images created with this flag must: also be created with the 2216 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. 2217 * ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will 2218 be backed using sparse memory binding with memory ranges that might also 2219 simultaneously be backing another image (or another portion of the same 2220 image). 2221 Images created with this flag must: also be created with the 2222 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. 2223 * ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can: 2224 be used to create a sname:VkImageView with a different format from the 2225 image. 2226ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2227 For <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> formats, 2228 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a 2229 sname:VkImageView can be created of a _plane_ of the image. 2230endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2231 * ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can: 2232 be used to create a sname:VkImageView of type 2233 ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY. 2234ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2235 * ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image 2236 can: be used to create a sname:VkImageView of type 2237 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY. 2238endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2239ifdef::VK_VERSION_1_1[] 2240 * ename:VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a 2241 protected image. 2242endif::VK_VERSION_1_1[] 2243ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2244 * ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the 2245 image can: be used with a non-zero value of the 2246 pname:splitInstanceBindRegionCount member of a 2247 slink:VkBindImageMemoryDeviceGroupInfo structure passed into 2248 flink:vkBindImageMemory2. 2249 This flag also has the effect of making the image use the standard 2250 sparse image block dimensions. 2251endif::VK_VERSION_1_1,VK_KHR_device_group[] 2252ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2253 * ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the 2254 image having a compressed format can: be used to create a 2255 sname:VkImageView with an uncompressed format where each texel in the 2256 image view corresponds to a compressed texel block of the image. 2257 * ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can: 2258 be created with usage flags that are not supported for the format the 2259 image is created with but are supported for at least one format a 2260 sname:VkImageView created from the image can: have. 2261endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2262ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2263 * ename:VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a 2264 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> must: 2265 have each plane separately bound to memory, rather than having a single 2266 memory binding for the whole image; the presence of this bit 2267 distinguishes a _disjoint image_ from an image without this bit set. 2268endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2269ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 2270 * ename:VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with 2271 the same creation parameters and aliased to the same memory can: 2272 interpret the contents of the memory consistently with each other, 2273 subject to the rules described in the <<resources-memory-aliasing,Memory 2274 Aliasing>> section. 2275ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2276 This flag further specifies that each plane of a _disjoint_ image can: 2277 share an in-memory non-linear representation with single-plane images, 2278 and that a single-plane image can: share an in-memory non-linear 2279 representation with a plane of a multi-planar disjoint image, according 2280 to the rules in <<formats-compatible-planes>>. 2281endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2282ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 2283 If the pname:pNext chain includes a 2284ifdef::VK_VERSION_1_1,VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfo] 2285// Jon: logic needs to incorporate VK_VERSION_1_1 2286ifdef::VK_KHR_external_memory+VK_NV_external_memory[or] 2287ifdef::VK_NV_external_memory[slink:VkExternalMemoryImageCreateInfoNV] 2288 structure whose pname:handleTypes member is not `0`, it is as if 2289 ename:VK_IMAGE_CREATE_ALIAS_BIT is set. 2290endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 2291endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 2292ifdef::VK_EXT_sample_locations[] 2293 * ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 2294 specifies that an image with a depth or depth/stencil format can: be 2295 used with custom sample locations when used as a depth/stencil 2296 attachment. 2297endif::VK_EXT_sample_locations[] 2298ifdef::VK_NV_corner_sampled_image[] 2299 * ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV specifies that the image is 2300 a <<resources-images-corner-sampled,corner-sampled image>>. 2301endif::VK_NV_corner_sampled_image[] 2302ifdef::VK_EXT_fragment_density_map[] 2303 * ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT specifies that an image can: be 2304 in a subsampled format which may: be more optimal when written as an 2305 attachment by a render pass that has a fragment density map attachment. 2306 Accessing a subsampled image has additional considerations: 2307 ** Image data read as an image sampler will have undefined: values if the 2308 sampler was not created with pname:flags containing 2309 ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or was not sampled through 2310 the use of a combined image sampler with an immutable sampler in 2311 sname:VkDescriptorSetLayoutBinding. 2312 ** Image data read with an input attachment will have undefined: values if 2313 the contents were not written as an attachment in an earlier subpass of 2314 the same render pass. 2315ifdef::VK_EXT_fragment_density_map2[] 2316 ** Image data read as an image sampler in the fragment shader will be 2317 additionally be read by the device during 2318 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT if 2319 <<limits-subsampledCoarseReconstructionEarlyAccess,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledCoarseReconstructionEarlyAccess>> 2320 is ename:VK_TRUE and the sampler was created with pname:flags 2321 containing 2322 ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT. 2323 ** Image data read with load operations are resampled to the fragment 2324 density of the render pass if 2325 <<limits-subsampledLoads,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledLoads>> 2326 is ename:VK_TRUE. 2327 Otherwise, values of image data are undefined:. 2328endif::VK_EXT_fragment_density_map2[] 2329ifndef::VK_EXT_fragment_density_map2[] 2330 ** Image data read with load operations may: be resampled to the fragment 2331 density of the render pass. 2332endif::VK_EXT_fragment_density_map2[] 2333 ** Image contents outside of the render area take on undefined: values if 2334 the image is stored as a render pass attachment. 2335endif::VK_EXT_fragment_density_map[] 2336 2337See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and 2338<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more 2339details. 2340-- 2341 2342[open,refpage='VkImageCreateFlags',desc='Bitmask of VkImageCreateFlagBits',type='flags'] 2343-- 2344include::{generated}/api/flags/VkImageCreateFlags.txt[] 2345 2346tname:VkImageCreateFlags is a bitmask type for setting a mask of zero or 2347more elink:VkImageCreateFlagBits. 2348-- 2349 2350[open,refpage='VkImageType',desc='Specifies the type of an image object',type='enums'] 2351-- 2352Possible values of slink:VkImageCreateInfo::pname:imageType, specifying the 2353basic dimensionality of an image, are: 2354 2355include::{generated}/api/enums/VkImageType.txt[] 2356 2357 * ename:VK_IMAGE_TYPE_1D specifies a one-dimensional image. 2358 * ename:VK_IMAGE_TYPE_2D specifies a two-dimensional image. 2359 * ename:VK_IMAGE_TYPE_3D specifies a three-dimensional image. 2360-- 2361 2362[open,refpage='VkImageTiling',desc='Specifies the tiling arrangement of data in an image',type='enums'] 2363-- 2364Possible values of slink:VkImageCreateInfo::pname:tiling, specifying the 2365tiling arrangement of texel blocks in an image, are: 2366 2367include::{generated}/api/enums/VkImageTiling.txt[] 2368 2369 * ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid 2370 out in an implementation-dependent arrangement, for more efficient 2371 memory access). 2372 * ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid 2373 out in memory in row-major order, possibly with some padding on each 2374 row). 2375ifdef::VK_EXT_image_drm_format_modifier[] 2376 * ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT indicates that the image's 2377 tiling is defined by a <<glossary-drm-format-modifier,Linux DRM format 2378 modifier>>. 2379 The modifier is specified at image creation with 2380 slink:VkImageDrmFormatModifierListCreateInfoEXT or 2381 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, and can: be queried 2382 with flink:vkGetImageDrmFormatModifierPropertiesEXT. 2383endif::VK_EXT_image_drm_format_modifier[] 2384-- 2385 2386[open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos'] 2387-- 2388To query the memory layout of an image subresource, call: 2389 2390include::{generated}/api/protos/vkGetImageSubresourceLayout.txt[] 2391 2392 * pname:device is the logical device that owns the image. 2393 * pname:image is the image whose layout is being queried. 2394 * pname:pSubresource is a pointer to a slink:VkImageSubresource structure 2395 selecting a specific image for the image subresource. 2396 * pname:pLayout is a pointer to a slink:VkSubresourceLayout structure in 2397 which the layout is returned. 2398 2399ifndef::VK_EXT_image_drm_format_modifier[] 2400The image must: be <<glossary-linear-resource,linear>>. 2401The 2402endif::VK_EXT_image_drm_format_modifier[] 2403ifdef::VK_EXT_image_drm_format_modifier[] 2404If the image is <<glossary-linear-resource,linear>>, then the 2405endif::VK_EXT_image_drm_format_modifier[] 2406returned layout is valid for <<memory-device-hostaccess, host access>>. 2407 2408ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2409If the image's 2410ifdef::VK_EXT_image_drm_format_modifier[] 2411tiling is ename:VK_IMAGE_TILING_LINEAR and its 2412endif::VK_EXT_image_drm_format_modifier[] 2413format is a <<formats-requiring-sampler-ycbcr-conversion,multi-planar 2414format>>, then fname:vkGetImageSubresourceLayout describes one 2415ifdef::VK_EXT_image_drm_format_modifier[_format plane_] 2416ifndef::VK_EXT_image_drm_format_modifier[plane] 2417of the image. 2418endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2419ifdef::VK_EXT_image_drm_format_modifier[] 2420If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 2421fname:vkGetImageSubresourceLayout describes one _memory plane_ of the image. 2422If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and 2423the image is <<glossary-linear-resource,non-linear>>, then the returned 2424layout has an implementation-dependent meaning; the vendor of the image's 2425<<glossary-drm-format-modifier,DRM format modifier>> may: provide 2426documentation that explains how to interpret the returned layout. 2427endif::VK_EXT_image_drm_format_modifier[] 2428 2429fname:vkGetImageSubresourceLayout is invariant for the lifetime of a single 2430image. 2431ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2432However, the subresource layout of images in Android hardware buffer 2433external memory is not known until the image has been bound to memory, so 2434applications must: not call flink:vkGetImageSubresourceLayout for such an 2435image before it has been bound. 2436endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2437 2438.Valid Usage 2439**** 2440ifndef::VK_EXT_image_drm_format_modifier[] 2441 * [[VUID-vkGetImageSubresourceLayout-image-00996]] 2442 pname:image must: have been created with pname:tiling equal to 2443 ename:VK_IMAGE_TILING_LINEAR 2444endif::VK_EXT_image_drm_format_modifier[] 2445ifdef::VK_EXT_image_drm_format_modifier[] 2446 * [[VUID-vkGetImageSubresourceLayout-image-02270]] 2447 pname:image must: have been created with pname:tiling equal to 2448 ename:VK_IMAGE_TILING_LINEAR or 2449 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 2450endif::VK_EXT_image_drm_format_modifier[] 2451 * [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]] 2452 The pname:aspectMask member of pname:pSubresource must: only have a 2453 single bit set 2454 * [[VUID-vkGetImageSubresourceLayout-mipLevel-01716]] 2455 The pname:mipLevel member of pname:pSubresource must: be less than the 2456 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 2457 was created 2458 * [[VUID-vkGetImageSubresourceLayout-arrayLayer-01717]] 2459 The pname:arrayLayer member of pname:pSubresource must: be less than the 2460 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 2461 was created 2462 * [[VUID-vkGetImageSubresourceLayout-format-04461]] 2463 If pname:format is a color format, the pname:aspectMask member of 2464 pname:pSubresource must: be ename:VK_IMAGE_ASPECT_COLOR_BIT 2465 * [[VUID-vkGetImageSubresourceLayout-format-04462]] 2466 If pname:format has a depth component, the pname:aspectMask member of 2467 pname:pSubresource must: contain ename:VK_IMAGE_ASPECT_DEPTH_BIT 2468 * [[VUID-vkGetImageSubresourceLayout-format-04463]] 2469 If pname:format has a stencil component, the pname:aspectMask member of 2470 pname:pSubresource must: contain ename:VK_IMAGE_ASPECT_STENCIL_BIT 2471 * [[VUID-vkGetImageSubresourceLayout-format-04464]] 2472 If pname:format does not contain a stencil or depth component, the 2473 pname:aspectMask member of pname:pSubresource must: not contain 2474 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT 2475ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2476 * [[VUID-vkGetImageSubresourceLayout-format-01581]] 2477 If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR 2478 and its pname:format is a 2479 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with 2480 two planes, the pname:aspectMask member of pname:pSubresource must: be 2481 ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT 2482 * [[VUID-vkGetImageSubresourceLayout-format-01582]] 2483 If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR 2484 and its pname:format is a 2485 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with 2486 three planes, the pname:aspectMask member of pname:pSubresource must: be 2487 ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or 2488 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 2489endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2490ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2491 * [[VUID-vkGetImageSubresourceLayout-image-01895]] 2492 If pname:image was created with the 2493 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 2494 external memory handle type, then pname:image must: be bound to memory 2495endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2496ifdef::VK_EXT_image_drm_format_modifier[] 2497 * [[VUID-vkGetImageSubresourceLayout-tiling-02271]] 2498 If the pname:tiling of the pname:image is 2499 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pname:aspectMask 2500 member of pname:pSubresource must: be 2501 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` and the index _i_ must: 2502 be less than the 2503 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 2504 associated with the image's pname:format and 2505 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier 2506endif::VK_EXT_image_drm_format_modifier[] 2507**** 2508 2509include::{generated}/validity/protos/vkGetImageSubresourceLayout.txt[] 2510-- 2511 2512[open,refpage='VkImageSubresource',desc='Structure specifying an image subresource',type='structs'] 2513-- 2514The sname:VkImageSubresource structure is defined as: 2515 2516include::{generated}/api/structs/VkImageSubresource.txt[] 2517 2518 * pname:aspectMask is a tlink:VkImageAspectFlags value selecting the image 2519 _aspect_. 2520 * pname:mipLevel selects the mipmap level. 2521 * pname:arrayLayer selects the array layer. 2522 2523include::{generated}/validity/structs/VkImageSubresource.txt[] 2524-- 2525 2526[open,refpage='VkSubresourceLayout',desc='Structure specifying subresource layout',type='structs'] 2527-- 2528Information about the layout of the image subresource is returned in a 2529sname:VkSubresourceLayout structure: 2530 2531include::{generated}/api/structs/VkSubresourceLayout.txt[] 2532 2533 * pname:offset is the byte offset from the start of the image 2534ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2535 or the plane 2536endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2537 where the image subresource begins. 2538 * pname:size is the size in bytes of the image subresource. 2539 pname:size includes any extra memory that is required based on 2540 pname:rowPitch. 2541 * pname:rowPitch describes the number of bytes between each row of texels 2542 in an image. 2543 * pname:arrayPitch describes the number of bytes between each array layer 2544 of an image. 2545 * pname:depthPitch describes the number of bytes between each slice of 3D 2546 image. 2547 2548If the image is <<glossary-linear-resource,linear>>, then pname:rowPitch, 2549pname:arrayPitch and pname:depthPitch describe the layout of the image 2550subresource in linear memory. 2551For uncompressed formats, pname:rowPitch is the number of bytes between 2552texels with the same x coordinate in adjacent rows (y coordinates differ by 2553one). 2554pname:arrayPitch is the number of bytes between texels with the same x and y 2555coordinate in adjacent array layers of the image (array layer values differ 2556by one). 2557pname:depthPitch is the number of bytes between texels with the same x and y 2558coordinate in adjacent slices of a 3D image (z coordinates differ by one). 2559Expressed as an addressing formula, the starting byte of a texel in the 2560image subresource has address: 2561 2562[source,c] 2563~~~~ 2564// (x,y,z,layer) are in texel coordinates 2565address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset 2566~~~~ 2567 2568For compressed formats, the pname:rowPitch is the number of bytes between 2569compressed texel blocks in adjacent rows. 2570pname:arrayPitch is the number of bytes between compressed texel blocks in 2571adjacent array layers. 2572pname:depthPitch is the number of bytes between compressed texel blocks in 2573adjacent slices of a 3D image. 2574 2575[source,c] 2576~~~~ 2577// (x,y,z,layer) are in compressed texel block coordinates 2578address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset; 2579~~~~ 2580 2581The value of pname:arrayPitch is undefined: for images that were not created 2582as arrays. 2583pname:depthPitch is defined only for 3D images. 2584 2585If the image has a 2586ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2587_single-plane_ 2588endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2589color format 2590ifdef::VK_EXT_image_drm_format_modifier[] 2591and its tiling is ename:VK_IMAGE_TILING_LINEAR 2592endif::VK_EXT_image_drm_format_modifier[] 2593, then the pname:aspectMask member of sname:VkImageSubresource must: be 2594ename:VK_IMAGE_ASPECT_COLOR_BIT. 2595 2596If the image has a depth/stencil format 2597ifdef::VK_EXT_image_drm_format_modifier[] 2598and its tiling is ename:VK_IMAGE_TILING_LINEAR 2599endif::VK_EXT_image_drm_format_modifier[] 2600, then pname:aspectMask must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or 2601ename:VK_IMAGE_ASPECT_STENCIL_BIT. 2602On implementations that store depth and stencil aspects separately, querying 2603each of these image subresource layouts will return a different pname:offset 2604and pname:size representing the region of memory used for that aspect. 2605On implementations that store depth and stencil aspects interleaved, the 2606same pname:offset and pname:size are returned and represent the interleaved 2607memory allocation. 2608 2609ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2610If the image has a <<formats-requiring-sampler-ycbcr-conversion,multi-planar 2611format>> 2612ifdef::VK_EXT_image_drm_format_modifier[] 2613and its tiling is ename:VK_IMAGE_TILING_LINEAR 2614endif::VK_EXT_image_drm_format_modifier[] 2615, then the pname:aspectMask member of sname:VkImageSubresource must: be 2616ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 2617(for 3-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 2618Querying each of these image subresource layouts will return a different 2619pname:offset and pname:size representing the region of memory used for that 2620plane. 2621If the image is _disjoint_, then the pname:offset is relative to the base 2622address of the plane. 2623If the image is _non-disjoint_, then the pname:offset is relative to the 2624base address of the image. 2625endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2626 2627ifdef::VK_EXT_image_drm_format_modifier[] 2628If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 2629the pname:aspectMask member of sname:VkImageSubresource must: be one of 2630`VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`, where the maximum allowed 2631plane index _i_ is defined by the 2632slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 2633associated with the image's slink:VkImageCreateInfo::pname:format and 2634<<glossary-drm-format-modifier,modifier>>. 2635The memory range used by the subresource is described by pname:offset and 2636pname:size. 2637If the image is _disjoint_, then the pname:offset is relative to the base 2638address of the _memory plane_. 2639If the image is _non-disjoint_, then the pname:offset is relative to the 2640base address of the image. 2641If the image is <<glossary-linear-resource,non-linear>>, then 2642pname:rowPitch, pname:arrayPitch, and pname:depthPitch have an 2643implementation-dependent meaning. 2644endif::VK_EXT_image_drm_format_modifier[] 2645 2646include::{generated}/validity/structs/VkSubresourceLayout.txt[] 2647-- 2648 2649ifdef::VK_EXT_image_drm_format_modifier[] 2650[open,refpage='vkGetImageDrmFormatModifierPropertiesEXT',desc='Returns an image\'s DRM format modifier',type='protos'] 2651-- 2652If an image was created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 2653then the image has a <<glossary-drm-format-modifier,Linux DRM format 2654modifier>>. 2655To query the _modifier_, call: 2656 2657include::{generated}/api/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] 2658 2659 * pname:device is the logical device that owns the image. 2660 * pname:image is the queried image. 2661 * pname:pProperties is a pointer to a 2662 slink:VkImageDrmFormatModifierPropertiesEXT structure in which 2663 properties of the image's _DRM format modifier_ are returned. 2664 2665.Valid Usage 2666**** 2667 * [[VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-02272]] 2668 pname:image must: have been created with 2669 <<VkImageCreateInfo,pname:tiling>> equal to 2670 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 2671**** 2672 2673include::{generated}/validity/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] 2674-- 2675 2676[open,refpage='VkImageDrmFormatModifierPropertiesEXT',desc='Properties of an image\'s Linux DRM format modifier',type='structs'] 2677-- 2678The slink:VkImageDrmFormatModifierPropertiesEXT structure is defined as: 2679 2680include::{generated}/api/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] 2681 2682 * pname:sType is the type of this structure. 2683 * pname:pNext is `NULL` or a pointer to a structure extending this 2684 structure. 2685 * pname:drmFormatModifier returns the image's 2686 <<glossary-drm-format-modifier,Linux DRM format modifier>>. 2687 2688If the pname:image was created with 2689slink:VkImageDrmFormatModifierListCreateInfoEXT, then the returned 2690pname:drmFormatModifier must: belong to the list of modifiers provided at 2691time of image creation in 2692slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. 2693If the pname:image was created with 2694slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned 2695pname:drmFormatModifier must: be the modifier provided at time of image 2696creation in 2697slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. 2698 2699include::{generated}/validity/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] 2700-- 2701endif::VK_EXT_image_drm_format_modifier[] 2702 2703[open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos'] 2704-- 2705To destroy an image, call: 2706 2707include::{generated}/api/protos/vkDestroyImage.txt[] 2708 2709 * pname:device is the logical device that destroys the image. 2710 * pname:image is the image to destroy. 2711 * pname:pAllocator controls host memory allocation as described in the 2712 <<memory-allocation, Memory Allocation>> chapter. 2713 2714.Valid Usage 2715**** 2716 * [[VUID-vkDestroyImage-image-01000]] 2717 All submitted commands that refer to pname:image, either directly or via 2718 a sname:VkImageView, must: have completed execution 2719 * [[VUID-vkDestroyImage-image-01001]] 2720 If sname:VkAllocationCallbacks were provided when pname:image was 2721 created, a compatible set of callbacks must: be provided here 2722 * [[VUID-vkDestroyImage-image-01002]] 2723 If no sname:VkAllocationCallbacks were provided when pname:image was 2724 created, pname:pAllocator must: be `NULL` 2725ifdef::VK_KHR_swapchain[] 2726 * [[VUID-vkDestroyImage-image-04882]] 2727 pname:image must: not have been acquired from 2728 flink:vkGetSwapchainImagesKHR 2729endif::VK_KHR_swapchain[] 2730**** 2731 2732include::{generated}/validity/protos/vkDestroyImage.txt[] 2733-- 2734 2735 2736[[resources-image-format-features]] 2737=== Image Format Features 2738 2739Valid uses of a slink:VkImage may: depend on the image's _format features_, 2740defined below. 2741Such constraints are documented in the affected valid usage statement. 2742 2743 * If the image was created with ename:VK_IMAGE_TILING_LINEAR, then its set 2744 of _format features_ is the value of 2745 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 2746 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 2747 slink:VkImageCreateInfo::pname:format. 2748 * If the image was created with ename:VK_IMAGE_TILING_OPTIMAL, 2749ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2750 but without an 2751 <<memory-external-android-hardware-buffer-external-formats,Android 2752 hardware buffer external format>>, 2753endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2754ifdef::VK_FUCHSIA_buffer_collection[] 2755ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 2756 but without an 2757endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2758ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2759 or an 2760endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2761 slink:VkBufferCollectionImageCreateInfoFUCHSIA, 2762endif::VK_FUCHSIA_buffer_collection[] 2763 then its set of _format features_ is the value of 2764 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 2765 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 2766 slink:VkImageCreateInfo::pname:format. 2767ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2768 * If the image was created with an 2769 <<memory-external-android-hardware-buffer-external-formats,Android 2770 hardware buffer external format>>, then its set of _format features_ is 2771 the value of 2772 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 2773 found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on 2774 the Android hardware buffer that was imported to the 2775 slink:VkDeviceMemory to which the image is bound. 2776endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2777ifdef::VK_EXT_image_drm_format_modifier[] 2778 * If the image was created with 2779 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: 2780 ** The image's DRM format modifier is the value of 2781 slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier 2782 found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. 2783 ** Let 2784 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 2785 be the array found by calling 2786 flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as 2787 slink:VkImageCreateInfo::pname:format. 2788 ** Let `VkDrmFormatModifierPropertiesEXT prop` be an array element whose 2789 pname:drmFormatModifier member is the value of the image's DRM format 2790 modifier. 2791 ** Then the image set of _format features_ is the value of taking the 2792 bitwise intersection over the collected 2793 `prop`::pname:drmFormatModifierTilingFeatures. 2794endif::VK_EXT_image_drm_format_modifier[] 2795 2796 2797ifdef::VK_NV_corner_sampled_image[] 2798[[resources-images-corner-sampled]] 2799=== Corner-Sampled Images 2800 2801A _corner-sampled image_ is an image where unnormalized texel coordinates 2802are centered on integer values rather than half-integer values. 2803 2804A corner-sampled image has a number of differences compared to conventional 2805texture image: 2806 2807 * Texels are centered on integer coordinates. 2808 See <<textures-unnormalized-to-integer, Unnormalized Texel Coordinate 2809 Operations>> 2810 * Normalized coordinates are scaled using [eq]#coord {times} (dim - 1)# 2811 rather than [eq]#coord {times} dim#, where dim is the size of one 2812 dimension of the image. 2813 See <<textures-normalized-to-unnormalized, normalized texel coordinate 2814 transform>>. 2815 * Partial derivatives are scaled using [eq]#coord {times} (dim - 1)# 2816 rather than [eq]#coord {times} dim#. 2817 See <<textures-scale-factor,Scale Factor Operation>>. 2818 * Calculation of the next higher lod size goes according to 2819 [eq]#{lceil}dim / 2{rceil}# rather than [eq]#{lfloor}dim / 2{rfloor}#. 2820 See <<resources-image-miplevel-sizing,Image Miplevel Sizing>>. 2821 * The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. 2822 See <<resources-image-miplevel-sizing,Image Miplevel Sizing>>. 2823 2824Corner-sampling is only supported for 2D and 3D images. 2825When sampling a corner-sampled image, the sampler addressing mode must: be 2826ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. 2827Corner-sampled images are not supported as cube maps or depth/stencil 2828images. 2829endif::VK_NV_corner_sampled_image[] 2830 2831 2832[[resources-image-miplevel-sizing]] 2833=== Image Miplevel Sizing 2834 2835A _complete mipmap chain_ is the full set of miplevels, from the largest 2836miplevel provided, down to the _minimum miplevel size_. 2837 2838 2839==== Conventional Images 2840 2841For conventional images, the dimensions of each successive miplevel, 2842[eq]#n+1#, are: 2843 2844 {empty}:: [eq]#pname:width~n+1~ = max({lfloor}pname:width~n~/2{rfloor}, 2845 1)# 2846 {empty}:: [eq]#pname:height~n+1~ = max({lfloor}pname:height~n~/2{rfloor}, 2847 1)# 2848 {empty}:: [eq]#pname:depth~n+1~ = max({lfloor}pname:depth~n~/2{rfloor}, 2849 1)# 2850 2851where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# 2852are the dimensions of the next larger miplevel, [eq]#n#. 2853 2854The minimum miplevel size is: 2855 2856 * 1 for one-dimensional images, 2857 * 1x1 for two-dimensional images, and 2858 * 1x1x1 for three-dimensional images. 2859 2860The number of levels in a complete mipmap chain is: 2861 2862 {empty}:: [eq]#{lfloor}log~2~(max(pname:width~0~, pname:height~0~, 2863 pname:depth~0~)){rfloor} {plus} 1# 2864 2865where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# 2866are the dimensions of the largest (most detailed) miplevel, `0`. 2867 2868 2869ifdef::VK_NV_corner_sampled_image[] 2870==== Corner-Sampled Images 2871 2872For corner-sampled images, the dimensions of each successive miplevel, 2873[eq]#n+1#, are: 2874 2875 {empty}:: [eq]#pname:width~n+1~ = max({lceil}pname:width~n~/2{rceil}, 2)# 2876 {empty}:: [eq]#pname:height~n+1~ = max({lceil}pname:height~n~/2{rceil}, 2877 2)# 2878 {empty}:: [eq]#pname:depth~n+1~ = max({lceil}pname:depth~n~/2{rceil}, 2)# 2879 2880where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# 2881are the dimensions of the next larger miplevel, [eq]#n#. 2882 2883The minimum miplevel size is: 2884 2885 * 2x2 for two-dimensional images, and 2886 * 2x2x2 for three-dimensional images. 2887 2888The number of levels in a complete mipmap chain is: 2889 2890 {empty}:: [eq]#{lceil}log~2~(max(pname:width~0~, pname:height~0~, 2891 pname:depth~0~)){rceil}# 2892 2893where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# 2894are the dimensions of the largest (most detailed) miplevel, `0`. 2895endif::VK_NV_corner_sampled_image[] 2896 2897 2898[[resources-image-layouts]] 2899== Image Layouts 2900 2901Images are stored in implementation-dependent opaque layouts in memory. 2902Each layout has limitations on what kinds of operations are supported for 2903image subresources using the layout. 2904At any given time, the data representing an image subresource in memory 2905exists in a particular layout which is determined by the most recent layout 2906transition that was performed on that image subresource. 2907Applications have control over which layout each image subresource uses, and 2908can: transition an image subresource from one layout to another. 2909Transitions can: happen with an image memory barrier, included as part of a 2910flink:vkCmdPipelineBarrier or a flink:vkCmdWaitEvents command buffer command 2911(see <<synchronization-image-memory-barriers>>), or as part of a subpass 2912dependency within a render pass (see sname:VkSubpassDependency). 2913 2914Image layout is per-image subresource. 2915Separate image subresources of the same image can: be in different layouts 2916at the same time, with the exception that depth and stencil aspects of a 2917given image subresource can: only be in different layouts if the 2918<<features-separateDepthStencilLayouts, pname:separateDepthStencilLayouts>> 2919feature is enabled. 2920 2921[NOTE] 2922.Note 2923==== 2924Each layout may: offer optimal performance for a specific usage of image 2925memory. 2926For example, an image with a layout of 2927ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL may: provide optimal 2928performance for use as a color attachment, but be unsupported for use in 2929transfer commands. 2930Applications can: transition an image subresource from one layout to another 2931in order to achieve optimal performance when the image subresource is used 2932for multiple kinds of operations. 2933After initialization, applications need not use any layout other than the 2934general layout, though this may: produce suboptimal performance on some 2935implementations. 2936==== 2937 2938Upon creation, all image subresources of an image are initially in the same 2939layout, where that layout is selected by the 2940sname:VkImageCreateInfo::pname:initialLayout member. 2941The pname:initialLayout must: be either ename:VK_IMAGE_LAYOUT_UNDEFINED or 2942ename:VK_IMAGE_LAYOUT_PREINITIALIZED. 2943If it is ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can: be 2944preinitialized by the host while using this layout, and the transition away 2945from this layout will preserve that data. 2946If it is ename:VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are 2947considered to be undefined:, and the transition away from this layout is not 2948guaranteed to preserve that data. 2949For either of these initial layouts, any image subresources must: be 2950transitioned to another layout before they are accessed by the device. 2951 2952Host access to image memory is only well-defined for 2953<<glossary-linear-resource,linear>> images and for image subresources of 2954those images which are currently in either the 2955ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL 2956layout. 2957Calling flink:vkGetImageSubresourceLayout for a linear image returns a 2958subresource layout mapping that is valid for either of those image layouts. 2959 2960[open,refpage='VkImageLayout',desc='Layout of image and image subresources',type='enums'] 2961-- 2962The set of image layouts consists of: 2963 2964include::{generated}/api/enums/VkImageLayout.txt[] 2965 2966The type(s) of device access supported by each layout are: 2967 2968 * ename:VK_IMAGE_LAYOUT_UNDEFINED specifies that the layout is unknown. 2969 Image memory cannot: be transitioned into this layout. 2970 This layout can: be used as the pname:initialLayout member of 2971 slink:VkImageCreateInfo. 2972 This layout can: be used in place of the current image layout in a 2973 layout transition, but doing so will cause the contents of the image's 2974 memory to be undefined:. 2975 * ename:VK_IMAGE_LAYOUT_PREINITIALIZED specifies that an image's memory is 2976 in a defined layout and can: be populated by data, but that it has not 2977 yet been initialized by the driver. 2978 Image memory cannot: be transitioned into this layout. 2979 This layout can: be used as the pname:initialLayout member of 2980 slink:VkImageCreateInfo. 2981 This layout is intended to be used as the initial layout for an image 2982 whose contents are written by the host, and hence the data can: be 2983 written to memory immediately, without first executing a layout 2984 transition. 2985 Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with 2986 <<glossary-linear-resource,linear>> images because there is not a 2987 standard layout defined for ename:VK_IMAGE_TILING_OPTIMAL images. 2988 * ename:VK_IMAGE_LAYOUT_GENERAL supports all types of device access. 2989ifdef::VK_KHR_synchronization2[] 2990 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR specifies a layout that 2991 must: only be used with attachment accesses in the graphics pipeline. 2992 * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR specifies a layout allowing 2993 read only access as an attachment, or in shaders as a sampled image, 2994 combined image/sampler, or input attachment. 2995endif::VK_KHR_synchronization2[] 2996 * ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must: only be used as a 2997 color or resolve attachment in a sname:VkFramebuffer. 2998 This layout is valid only for image subresources of images created with 2999 the ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled. 3000 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL specifies a 3001 layout for both the depth and stencil aspects of a depth/stencil format 3002 image allowing read and write access as a depth/stencil attachment. 3003ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3004 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and 3005 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. 3006endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3007 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL specifies a layout 3008 for both the depth and stencil aspects of a depth/stencil format image 3009 allowing read only access as a depth/stencil attachment or in shaders as 3010 a sampled image, combined image/sampler, or input attachment. 3011ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3012 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and 3013 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. 3014endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3015ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3016 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 3017 specifies a layout for depth/stencil format images allowing read and 3018 write access to the stencil aspect as a stencil attachment, and read 3019 only access to the depth aspect as a depth attachment or in shaders as a 3020 sampled image, combined image/sampler, or input attachment. 3021ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3022 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and 3023 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. 3024endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3025 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 3026 specifies a layout for depth/stencil format images allowing read and 3027 write access to the depth aspect as a depth attachment, and read only 3028 access to the stencil aspect as a stencil attachment or in shaders as a 3029 sampled image, combined image/sampler, or input attachment. 3030ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3031 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and 3032 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. 3033endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3034endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3035ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3036 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL specifies a layout for 3037 the depth aspect of a depth/stencil format image allowing read and write 3038 access as a depth attachment. 3039 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL specifies a layout for the 3040 depth aspect of a depth/stencil format image allowing read-only access 3041 as a depth attachment or in shaders as a sampled image, combined 3042 image/sampler, or input attachment. 3043 * ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for 3044 the stencil aspect of a depth/stencil format image allowing read and 3045 write access as a stencil attachment. 3046 * ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for 3047 the stencil aspect of a depth/stencil format image allowing read-only 3048 access as a stencil attachment or in shaders as a sampled image, 3049 combined image/sampler, or input attachment. 3050endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 3051 * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL specifies a layout 3052 allowing read-only access in a shader as a sampled image, combined 3053 image/sampler, or input attachment. 3054 This layout is valid only for image subresources of images created with 3055 the ename:VK_IMAGE_USAGE_SAMPLED_BIT or 3056 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bits enabled. 3057 * ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must: only be used as a 3058 source image of a transfer command (see the definition of 3059 <<synchronization-pipeline-stages-transfer, 3060 ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). 3061 This layout is valid only for image subresources of images created with 3062 the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled. 3063 * ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must: only be used as a 3064 destination image of a transfer command. 3065 This layout is valid only for image subresources of images created with 3066 the ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled. 3067ifdef::VK_KHR_swapchain[] 3068 * ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must: only be used for presenting 3069 a presentable image for display. 3070 A swapchain's image must: be transitioned to this layout before calling 3071 flink:vkQueuePresentKHR, and must: be transitioned away from this layout 3072 after calling flink:vkAcquireNextImageKHR. 3073ifdef::VK_KHR_shared_presentable_image[] 3074 * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared 3075 presentable images, and must: be used for any usage the image supports. 3076endif::VK_KHR_shared_presentable_image[] 3077endif::VK_KHR_swapchain[] 3078ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3079 * ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR must: 3080 only be used as a 3081ifdef::VK_KHR_fragment_shading_rate[] 3082 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 3083 attachment>> 3084endif::VK_KHR_fragment_shading_rate[] 3085ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[or] 3086ifdef::VK_NV_shading_rate_image[] 3087 <<primsrast-shading-rate-image, shading rate image>>. 3088endif::VK_NV_shading_rate_image[] 3089 This layout is valid only for image subresources of images created with 3090 the ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage 3091 bit enabled. 3092endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3093ifdef::VK_EXT_fragment_density_map[] 3094 * ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT must: only be 3095 used as a fragment density map attachment in a sname:VkRenderPass. 3096 This layout is valid only for image subresources of images created with 3097 the ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT usage bit enabled. 3098endif::VK_EXT_fragment_density_map[] 3099ifdef::VK_KHR_video_decode_queue[] 3100 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR must: only be used as a 3101 decode output image of a <<video-decode-operations, video decode 3102 operation>>. 3103 This layout is valid only for image subresources of images created with 3104 the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage bit enabled. 3105 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR must: only be used as a 3106 decode source image of a <<video-decode-operations, video decode 3107 operation>>. 3108 This layout is valid only for image subresources of images created with 3109 the ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR usage bit enabled. 3110 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR must: only be used as a 3111 decode source or destination image of a <<video-decode-operations, video 3112 decode operation>>. 3113 This layout is valid only for image subresources of images created with 3114 the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage bit enabled. 3115endif::VK_KHR_video_decode_queue[] 3116ifdef::VK_KHR_video_encode_queue[] 3117 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR must: only be used as a 3118 encode output image of a <<video-encode-operations, video encode 3119 operation>>. 3120 This layout is valid only for image subresources of images created with 3121 the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR usage bit enabled. 3122 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR must: only be used as a 3123 encode source image of a <<video-encode-operations, video encode 3124 operation>>. 3125 This layout is valid only for image subresources of images created with 3126 the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage bit enabled. 3127 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR must: only be used as a 3128 encode source or destination image of a <<video-encode-operations, video 3129 encode operation>>. 3130 This layout is valid only for image subresources of images created with 3131 the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage bit enabled. 3132endif::VK_KHR_video_encode_queue[] 3133 3134The layout of each image subresource is not a state of the image subresource 3135itself, but is rather a property of how the data in memory is organized, and 3136thus for each mechanism of accessing an image in the API the application 3137must: specify a parameter or structure member that indicates which image 3138layout the image subresource(s) are considered to be in when the image will 3139be accessed. 3140For transfer commands, this is a parameter to the command (see <<clears>> 3141and <<copies>>). 3142For use as a framebuffer attachment, this is a member in the substructures 3143of the slink:VkRenderPassCreateInfo (see <<renderpass,Render Pass>>). 3144For use in a descriptor set, this is a member in the 3145sname:VkDescriptorImageInfo structure (see <<descriptorsets-updates>>). 3146-- 3147 3148 3149[[resources-image-layouts-matching-rule]] 3150=== Image Layout Matching Rules 3151 3152At the time that any command buffer command accessing an image executes on 3153any queue, the layouts of the image subresources that are accessed must: all 3154match exactly the layout specified via the API controlling those accesses 3155ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3156, except in case of accesses to an image with a depth/stencil format 3157performed through descriptors referring to only a single aspect of the 3158image, where the following relaxed matching rules apply: 3159 3160 * Descriptors referring just to the depth aspect of a depth/stencil image 3161 only need to match in the image layout of the depth aspect, thus 3162 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and 3163 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL are 3164 considered to match. 3165 * Descriptors referring just to the stencil aspect of a depth/stencil 3166 image only need to match in the image layout of the stencil aspect, thus 3167 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and 3168 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL are 3169 considered to match 3170endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3171. 3172 3173When performing a layout transition on an image subresource, the old layout 3174value must: either equal the current layout of the image subresource (at the 3175time the transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED 3176(implying that the contents of the image subresource need not be preserved). 3177The new layout used in a transition must: not be 3178ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED. 3179 3180ifdef::VK_EXT_sample_locations[] 3181 3182The image layout of each image subresource of a depth/stencil image created 3183with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is 3184dependent on the last sample locations used to render to the image 3185subresource as a depth/stencil attachment, thus applications must: provide 3186the same sample locations that were last used to render to the given image 3187subresource whenever a layout transition of the image subresource happens, 3188otherwise the contents of the depth aspect of the image subresource become 3189undefined:. 3190 3191In addition, depth reads from a depth/stencil attachment referring to an 3192image subresource range of a depth/stencil image created with 3193ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using 3194different sample locations than what have been last used to perform depth 3195writes to the image subresources of the same image subresource range return 3196undefined: values. 3197 3198Similarly, depth writes to a depth/stencil attachment referring to an image 3199subresource range of a depth/stencil image created with 3200ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using 3201different sample locations than what have been last used to perform depth 3202writes to the image subresources of the same image subresource range make 3203the contents of the depth aspect of those image subresources undefined:. 3204 3205endif::VK_EXT_sample_locations[] 3206 3207 3208[[resources-image-views]] 3209== Image Views 3210 3211[open,refpage='VkImageView',desc='Opaque handle to an image view object',type='handles'] 3212-- 3213Image objects are not directly accessed by pipeline shaders for reading or 3214writing image data. 3215Instead, _image views_ representing contiguous ranges of the image 3216subresources and containing additional metadata are used for that purpose. 3217Views must: be created on images of compatible types, and must: represent a 3218valid subset of image subresources. 3219 3220Image views are represented by sname:VkImageView handles: 3221 3222include::{generated}/api/handles/VkImageView.txt[] 3223-- 3224 3225[open,refpage='VK_REMAINING_ARRAY_LAYERS',desc='Sentinel for all remaining array layers',type='consts'] 3226-- 3227ename:VK_REMAINING_ARRAY_LAYERS is a special constant value used for image 3228views to indicate that all remaining array layers in an image after the base 3229layer should be included in the view. 3230 3231include::{generated}/api/enums/VK_REMAINING_ARRAY_LAYERS.txt[] 3232-- 3233 3234[open,refpage='VK_REMAINING_MIP_LEVELS',desc='Sentinel for all remaining mipmap levels',type='consts'] 3235-- 3236ename:VK_REMAINING_MIP_LEVELS is a special constant value used for image 3237views to indicate that all remaining mipmap levels in an image after the 3238base level should be included in the view. 3239 3240include::{generated}/api/enums/VK_REMAINING_MIP_LEVELS.txt[] 3241-- 3242 3243[open,refpage='VkImageViewType',desc='Image view types',type='enums'] 3244-- 3245The types of image views that can: be created are: 3246 3247include::{generated}/api/enums/VkImageViewType.txt[] 3248-- 3249 3250[open,refpage='vkCreateImageView',desc='Create an image view from an existing image',type='protos'] 3251-- 3252To create an image view, call: 3253 3254include::{generated}/api/protos/vkCreateImageView.txt[] 3255 3256 * pname:device is the logical device that creates the image view. 3257 * pname:pCreateInfo is a pointer to a sname:VkImageViewCreateInfo 3258 structure containing parameters to be used to create the image view. 3259 * pname:pAllocator controls host memory allocation as described in the 3260 <<memory-allocation, Memory Allocation>> chapter. 3261 * pname:pView is a pointer to a slink:VkImageView handle in which the 3262 resulting image view object is returned. 3263 3264include::{generated}/validity/protos/vkCreateImageView.txt[] 3265-- 3266 3267[open,refpage='VkImageViewCreateInfo',desc='Structure specifying parameters of a newly created image view',type='structs'] 3268-- 3269The sname:VkImageViewCreateInfo structure is defined as: 3270 3271include::{generated}/api/structs/VkImageViewCreateInfo.txt[] 3272 3273 * pname:sType is the type of this structure. 3274 * pname:pNext is `NULL` or a pointer to a structure extending this 3275 structure. 3276 * pname:flags is a bitmask of elink:VkImageViewCreateFlagBits describing 3277 additional parameters of the image view. 3278 * pname:image is a slink:VkImage on which the view will be created. 3279 * pname:viewType is a elink:VkImageViewType value specifying the type of 3280 the image view. 3281 * pname:format is a elink:VkFormat describing the format and type used to 3282 interpret texel blocks in the image. 3283 * pname:components is a slink:VkComponentMapping structure specifying a 3284 remapping of color components (or of depth or stencil components after 3285 they have been converted into color components). 3286 * pname:subresourceRange is a slink:VkImageSubresourceRange structure 3287 selecting the set of mipmap levels and array layers to be accessible to 3288 the view. 3289 3290[[resources-image-inherited-usage]] 3291Some of the pname:image creation parameters are inherited by the view. 3292In particular, image view creation inherits the implicit parameter 3293pname:usage specifying the allowed usages of the image view that, by 3294default, takes the value of the corresponding pname:usage parameter 3295specified in slink:VkImageCreateInfo at image creation time. 3296ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3297The implicit pname:usage can: be overriden by adding a 3298slink:VkImageViewUsageCreateInfo structure to the pname:pNext chain, but the 3299view usage must: be a subset of the image usage. 3300endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3301ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3302If pname:image has a depth-stencil format and was created with a 3303slink:VkImageStencilUsageCreateInfo structure included in the pname:pNext 3304chain of slink:VkImageCreateInfo, the usage is calculated based on the 3305pname:subresource.aspectMask provided: 3306 3307 * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_STENCIL_BIT, the 3308 implicit pname:usage is equal to 3309 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. 3310 * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_DEPTH_BIT, the 3311 implicit pname:usage is equal to slink:VkImageCreateInfo::pname:usage. 3312 * If both aspects are included in pname:aspectMask, the implicit 3313 pname:usage is equal to the intersection of 3314 slink:VkImageCreateInfo::pname:usage and 3315 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. 3316endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3317 3318If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 3319flag, 3320ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3321and if the pname:format of the image is not 3322<<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, 3323endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3324pname:format can: be different from the image's format, but if 3325ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3326pname:image was created without the 3327ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and 3328endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3329they are not equal they must: be _compatible_. 3330Image format compatibility is defined in the 3331<<formats-compatibility-classes,Format Compatibility Classes>> section. 3332Views of compatible formats will have the same mapping between texel 3333coordinates and memory locations irrespective of the pname:format, with only 3334the interpretation of the bit pattern changing. 3335 3336[NOTE] 3337.Note 3338==== 3339Values intended to be used with one view format may: not be exactly 3340preserved when written or read through a different format. 3341For example, an integer value that happens to have the bit pattern of a 3342floating point denorm or NaN may: be flushed or canonicalized when written 3343or read through a view with a floating point format. 3344Similarly, a value written through a signed normalized format that has a bit 3345pattern exactly equal to [eq]#-2^b^# may: be changed to [eq]#-2^b^ {plus} 1# 3346as described in <<fundamentals-fixedfpconv,Conversion from Normalized 3347Fixed-Point to Floating-Point>>. 3348==== 3349 3350ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3351If pname:image was created with the 3352ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 3353must: be _compatible_ with the image's format as described above, or must: 3354be an uncompressed format in which case it must: be _size-compatible_ with 3355the image's format, as defined for 3356<<copies-images-format-size-compatibility, copying data between images>>. 3357In this case, the resulting image view's texel dimensions equal the 3358dimensions of the selected mip level divided by the compressed texel block 3359size and rounded up. 3360endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3361 3362The slink:VkComponentMapping pname:components member describes a remapping 3363from components of the image to components of the vector returned by shader 3364image instructions. 3365This remapping must: be the identity swizzle for storage image descriptors, 3366input attachment descriptors, 3367ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3368and framebuffer attachments. 3369endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3370ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3371framebuffer attachments, and any sname:VkImageView used with a combined 3372image sampler that enables <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ 3373conversion>>. 3374endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3375 3376ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3377If the image view is to be used with a sampler which supports 3378<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>, an _identically 3379defined object_ of type slink:VkSamplerYcbcrConversion to that used to 3380create the sampler must: be passed to flink:vkCreateImageView in a 3381slink:VkSamplerYcbcrConversionInfo included in the pname:pNext chain of 3382slink:VkImageViewCreateInfo. 3383Conversely, if a slink:VkSamplerYcbcrConversion object is passed to 3384flink:vkCreateImageView, an identically defined 3385slink:VkSamplerYcbcrConversion object must: be used when sampling the image. 3386 3387If the image has a 3388<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and 3389pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, 3390ifdef::VK_KHR_video_decode_queue[] 3391and pname:image has been created with a pname:usage value *not* containing 3392any of the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, 3393ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, 3394ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, 3395ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 3396ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, and 3397ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR flags, 3398endif::VK_KHR_video_decode_queue[] 3399then the pname:format must: be identical to the image pname:format, and the 3400sampler to be used with the image view must: enable 3401<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>. 3402 3403ifdef::VK_KHR_video_decode_queue[] 3404If the image has a 3405<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and 3406the pname:image has been created with a pname:usage value containing any of 3407the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, 3408ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, and 3409ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR flags, then all of the 3410<<video-decode-operations, video decode operations>> would ignore the 3411slink:VkSamplerYcbcrConversionInfo structure and/or 3412<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> object, 3413associated with the image view. 3414endif::VK_KHR_video_decode_queue[] 3415ifdef::VK_KHR_video_encode_queue[] 3416If the image has a 3417<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and 3418the pname:image has been created with a pname:usage value containing any of 3419the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 3420ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, and 3421ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR flags, then all of the 3422<<video-encode-operations, video encode operations>> would ignore the 3423slink:VkSamplerYcbcrConversionInfo structure and/or 3424<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> object, 3425associated with the image view. 3426endif::VK_KHR_video_encode_queue[] 3427 3428If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 3429and the image has a 3430<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format, 3431and if pname:subresourceRange.aspectMask is 3432ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 3433ename:VK_IMAGE_ASPECT_PLANE_2_BIT, pname:format must: be 3434<<formats-compatible-planes,compatible>> with the corresponding plane of the 3435image, and the sampler to be used with the image view must: not enable 3436<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>. 3437The pname:width and pname:height of the single-plane image view must: be 3438derived from the multi-planar image's dimensions in the manner listed for 3439<<formats-compatible-planes,plane compatibility>> for the plane. 3440 3441Any view of an image plane will have the same mapping between texel 3442coordinates and memory locations as used by the components of the color 3443aspect, subject to the formulae relating texel coordinates to 3444lower-resolution planes as described in <<textures-chroma-reconstruction, 3445Chroma Reconstruction>>. 3446That is, if an R or B plane has a reduced resolution relative to the G plane 3447of the multi-planar image, the image view operates using the (_u~plane~_, 3448_v~plane~_) unnormalized coordinates of the reduced-resolution plane, and 3449these coordinates access the same memory locations as the (_u~color~_, 3450_v~color~_) unnormalized coordinates of the color aspect for which chroma 3451reconstruction operations operate on the same (_u~plane~_, _v~plane~_) or 3452(_i~plane~_, _j~plane~_) coordinates. 3453endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3454 3455[[resources-image-views-compatibility]] 3456.Image type and image view type compatibility requirements 3457[cols="35%,50%",options="header"] 3458|==== 3459| Image View Type | Compatible Image Types 3460| ename:VK_IMAGE_VIEW_TYPE_1D | ename:VK_IMAGE_TYPE_1D 3461| ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY | ename:VK_IMAGE_TYPE_1D 3462| ename:VK_IMAGE_VIEW_TYPE_2D | ename:VK_IMAGE_TYPE_2D 3463ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] 3464| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY | ename:VK_IMAGE_TYPE_2D 3465ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] 3466| ename:VK_IMAGE_VIEW_TYPE_CUBE | ename:VK_IMAGE_TYPE_2D 3467| ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY | ename:VK_IMAGE_TYPE_2D 3468| ename:VK_IMAGE_VIEW_TYPE_3D | ename:VK_IMAGE_TYPE_3D 3469|==== 3470 3471.Valid Usage 3472**** 3473 * [[VUID-VkImageViewCreateInfo-image-01003]] 3474 If pname:image was not created with 3475 ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then pname:viewType must: not 3476 be ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 3477 * [[VUID-VkImageViewCreateInfo-viewType-01004]] 3478 If the <<features-imageCubeArray,image cube map arrays>> feature is not 3479 enabled, pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 3480ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3481 * [[VUID-VkImageViewCreateInfo-image-01005]] 3482 If pname:image was created with ename:VK_IMAGE_TYPE_3D but without 3483 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then pname:viewType 3484 must: not be ename:VK_IMAGE_VIEW_TYPE_2D or 3485 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 3486 * [[VUID-VkImageViewCreateInfo-image-04970]] 3487 If pname:image was created with ename:VK_IMAGE_TYPE_3D and 3488 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or 3489 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:subresourceRange.levelCount 3490 must: be 1 3491 * [[VUID-VkImageViewCreateInfo-image-04971]] 3492 If pname:image was created with ename:VK_IMAGE_TYPE_3D and 3493 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or 3494 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:flags must: not contain any 3495 of ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 3496 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and 3497 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 3498 * [[VUID-VkImageViewCreateInfo-image-04972]] 3499 If pname:image was created with a pname:samples value not equal to 3500 ename:VK_SAMPLE_COUNT_1_BIT then pname:viewType must: be either 3501 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 3502endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3503 * [[VUID-VkImageViewCreateInfo-image-04441]] 3504 pname:image must: have been created with a pname:usage value containing 3505 at least one of the usages defined in the <<valid-imageview-imageusage, 3506 valid image usage>> list for image views 3507 * [[VUID-VkImageViewCreateInfo-None-02273]] 3508 The <<resources-image-view-format-features,format features>> of the 3509 resultant image view must: contain at least one bit 3510 * [[VUID-VkImageViewCreateInfo-usage-02274]] 3511 If pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the 3512 <<resources-image-view-format-features,format features>> of the 3513 resultant image view must: contain 3514 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT 3515 * [[VUID-VkImageViewCreateInfo-usage-02275]] 3516 If pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, then the image 3517 view's <<resources-image-view-format-features,format features>> must: 3518 contain ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT 3519 * [[VUID-VkImageViewCreateInfo-usage-02276]] 3520 If pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then 3521 the image view's <<resources-image-view-format-features,format 3522 features>> must: contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 3523 * [[VUID-VkImageViewCreateInfo-usage-02277]] 3524 If pname:usage contains 3525 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view's 3526 <<resources-image-view-format-features,format features>> must: contain 3527 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 3528 * [[VUID-VkImageViewCreateInfo-usage-02652]] 3529 If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then 3530 the image view's <<resources-image-view-format-features,format 3531 features>> must: contain at least one of 3532 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 3533 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 3534 * [[VUID-VkImageViewCreateInfo-subresourceRange-01478]] 3535 pname:subresourceRange.baseMipLevel must: be less than the 3536 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 3537 was created 3538 * [[VUID-VkImageViewCreateInfo-subresourceRange-01718]] 3539 If pname:subresourceRange.levelCount is not 3540 ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel 3541 {plus} pname:subresourceRange.levelCount# must: be less than or equal to 3542 the pname:mipLevels specified in slink:VkImageCreateInfo when 3543 pname:image was created 3544ifdef::VK_EXT_fragment_density_map[] 3545 * [[VUID-VkImageViewCreateInfo-image-02571]] 3546 If pname:image was created with pname:usage containing 3547 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, 3548 pname:subresourceRange.levelCount must: be `1` 3549endif::VK_EXT_fragment_density_map[] 3550ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3551 * [[VUID-VkImageViewCreateInfo-subresourceRange-01480]] 3552 pname:subresourceRange.baseArrayLayer must: be less than the 3553 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 3554 was created 3555 * [[VUID-VkImageViewCreateInfo-subresourceRange-01719]] 3556 If pname:subresourceRange.layerCount is not 3557 ename:VK_REMAINING_ARRAY_LAYERS, 3558 [eq]#pname:subresourceRange.baseArrayLayer {plus} 3559 pname:subresourceRange.layerCount# must: be less than or equal to the 3560 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 3561 was created 3562endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3563ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3564 * [[VUID-VkImageViewCreateInfo-image-01482]] 3565 If pname:image is not a 3D image created with 3566 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or pname:viewType is 3567 not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 3568 pname:subresourceRange.baseArrayLayer must: be less than the 3569 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 3570 was created 3571 * [[VUID-VkImageViewCreateInfo-subresourceRange-01483]] 3572 If pname:subresourceRange.layerCount is not 3573 ename:VK_REMAINING_ARRAY_LAYERS, pname:image is not a 3D image created 3574 with ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or 3575 pname:viewType is not ename:VK_IMAGE_VIEW_TYPE_2D or 3576 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, pname:subresourceRange.layerCount 3577 must: be non-zero and [eq]#pname:subresourceRange.baseArrayLayer {plus} 3578 pname:subresourceRange.layerCount# must: be less than or equal to the 3579 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 3580 was created 3581 * [[VUID-VkImageViewCreateInfo-image-02724]] 3582 If pname:image is a 3D image created with 3583 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is 3584 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 3585 pname:subresourceRange.baseArrayLayer must: be less than the depth 3586 computed from pname:baseMipLevel and pname:extent.depth specified in 3587 slink:VkImageCreateInfo when pname:image was created, according to the 3588 formula defined in <<resources-image-miplevel-sizing,Image Miplevel 3589 Sizing>> 3590 * [[VUID-VkImageViewCreateInfo-subresourceRange-02725]] 3591 If pname:subresourceRange.layerCount is not 3592 ename:VK_REMAINING_ARRAY_LAYERS, pname:image is a 3D image created with 3593 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is 3594 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 3595 pname:subresourceRange.layerCount must: be non-zero and 3596 [eq]#pname:subresourceRange.baseArrayLayer {plus} 3597 pname:subresourceRange.layerCount# must: be less than or equal to the 3598 depth computed from pname:baseMipLevel and pname:extent.depth specified 3599 in slink:VkImageCreateInfo when pname:image was created, according to 3600 the formula defined in <<resources-image-miplevel-sizing,Image Miplevel 3601 Sizing>> 3602endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3603// The VU below comes in 4 alternate versions 3604// both disabled, both enabled, maintenance2 only, ycbcr only 3605ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3606ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3607 * [[VUID-VkImageViewCreateInfo-image-01018]] 3608 If pname:image was created with the 3609 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be 3610 compatible with the pname:format used to create pname:image, as defined 3611 in <<formats-compatibility-classes,Format Compatibility Classes>> 3612endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3613endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3614// The nested ifdefs are there in anticipation of the hoped-for day when the 3615// VU extractor and validation layers can handle VU with imbedded 3616// conditionals. They are commented out until then. 3617// 3618// If VK_VERSION_1_1,VK_KHR_maintenance2 and NOT VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 3619ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3620ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3621 * [[VUID-VkImageViewCreateInfo-image-01759]] 3622 If pname:image was created with the 3623 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the 3624 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 3625 must: be compatible with the pname:format used to create pname:image, as 3626 defined in <<formats-compatibility-classes,Format Compatibility 3627 Classes>> 3628endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3629endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3630// If NOT VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 3631ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3632ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3633 * [[VUID-VkImageViewCreateInfo-image-01760]] 3634 If pname:image was created with the 3635 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the pname:format 3636 of the pname:image is not a 3637 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, 3638 pname:format must: be compatible with the pname:format used to create 3639 pname:image, as defined in <<formats-compatibility-classes,Format 3640 Compatibility Classes>> 3641endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3642endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3643// If VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 3644ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3645ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3646 * [[VUID-VkImageViewCreateInfo-image-01761]] 3647 If pname:image was created with the 3648 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, 3649// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3650 but without the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT 3651 flag, 3652// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3653// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3654 and if the pname:format of the pname:image is not a 3655 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, 3656// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3657 pname:format must: be compatible with the pname:format used to create 3658 pname:image, as defined in <<formats-compatibility-classes,Format 3659 Compatibility Classes>> 3660endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3661endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3662ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3663 * [[VUID-VkImageViewCreateInfo-image-01583]] 3664 If pname:image was created with the 3665 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 3666 must: be compatible with, or must: be an uncompressed format that is 3667 size-compatible with, the pname:format used to create pname:image 3668 * [[VUID-VkImageViewCreateInfo-image-01584]] 3669 If pname:image was created with the 3670 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the 3671 pname:levelCount and pname:layerCount members of pname:subresourceRange 3672 must: both be `1` 3673 * [[VUID-VkImageViewCreateInfo-image-04739]] 3674 If pname:image was created with the 3675 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and 3676 pname:format is a non-compressed format, pname:viewType must: not be 3677 ename:VK_IMAGE_VIEW_TYPE_3D 3678endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3679ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 3680 * [[VUID-VkImageViewCreateInfo-pNext-01585]] 3681 If a slink:VkImageFormatListCreateInfo structure was included in the 3682 pname:pNext chain of the slink:VkImageCreateInfo structure used when 3683 creating pname:image and 3684 slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero 3685 then pname:format must: be one of the formats in 3686 slink:VkImageFormatListCreateInfo::pname:pViewFormats 3687endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 3688ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3689 * [[VUID-VkImageViewCreateInfo-image-01586]] 3690 If pname:image was created with the 3691 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the pname:format of 3692 the pname:image is a 3693 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and 3694 if pname:subresourceRange.aspectMask is one of 3695 ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 3696 ename:VK_IMAGE_ASPECT_PLANE_2_BIT, then pname:format must: be compatible 3697 with the elink:VkFormat for the plane of the pname:image pname:format 3698 indicated by pname:subresourceRange.aspectMask, as defined in 3699 <<formats-compatible-planes>> 3700endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3701ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3702// The VU below comes in an alternate version when the extension is 3703// enabled. 3704 * [[VUID-VkImageViewCreateInfo-image-01019]] 3705 If pname:image was not created with the 3706 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be 3707 identical to the pname:format used to create pname:image 3708endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3709// The nested ifdefs are there in anticipation of the hoped-for day when the 3710// VU extractor and validation layers can handle VU with imbedded 3711// conditionals. They are commented out until then. 3712ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3713 * [[VUID-VkImageViewCreateInfo-image-01762]] 3714 If pname:image was not created with the 3715 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, 3716// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3717 or if the pname:format of the pname:image is a 3718 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format and 3719 if pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, 3720// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3721 pname:format must: be identical to the pname:format used to create 3722 pname:image 3723endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3724ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3725 * [[VUID-VkImageViewCreateInfo-format-06415]] 3726 If the image pname:format is one of the 3727 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 3728 sampler Y'C~B~C~R~ conversion>>, then the pname:pNext chain must: 3729 include a slink:VkSamplerYcbcrConversionInfo structure with a conversion 3730 value other than dlink:VK_NULL_HANDLE 3731 * [[VUID-VkImageViewCreateInfo-format-04714]] 3732 If pname:format has a code:_422 or code:_420 suffix then pname:image 3733 must: have been created with a width that is a multiple of 2 3734 * [[VUID-VkImageViewCreateInfo-format-04715]] 3735 If pname:format has a code:_420 suffix then pname:image must: have been 3736 created with a height that is a multiple of 2 3737 * [[VUID-VkImageViewCreateInfo-pNext-01970]] 3738 If the pname:pNext chain includes a slink:VkSamplerYcbcrConversionInfo 3739 structure with a pname:conversion value other than dlink:VK_NULL_HANDLE, 3740 all members of pname:components must: have the 3741 <<resources-image-views-identity-mappings,identity swizzle>> 3742endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3743 * [[VUID-VkImageViewCreateInfo-image-01020]] 3744 If pname:image is non-sparse then it must: be bound completely and 3745 contiguously to a single sname:VkDeviceMemory object 3746 * [[VUID-VkImageViewCreateInfo-subResourceRange-01021]] 3747 pname:viewType must: be compatible with the type of pname:image as shown 3748 in the <<resources-image-views-compatibility,view type compatibility 3749 table>> 3750ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 3751 * [[VUID-VkImageViewCreateInfo-image-02399]] 3752 If pname:image has an 3753 <<memory-external-android-hardware-buffer-external-formats,external 3754 format>>, pname:format must: be ename:VK_FORMAT_UNDEFINED 3755 * [[VUID-VkImageViewCreateInfo-image-02400]] 3756 If pname:image has an 3757 <<memory-external-android-hardware-buffer-external-formats,external 3758 format>>, the pname:pNext chain must: include a 3759 slink:VkSamplerYcbcrConversionInfo structure with a pname:conversion 3760 object created with the same external format as pname:image 3761 * [[VUID-VkImageViewCreateInfo-image-02401]] 3762 If pname:image has an 3763 <<memory-external-android-hardware-buffer-external-formats,external 3764 format>>, all members of pname:components must: be the 3765 <<resources-image-views-identity-mappings,identity swizzle>> 3766endif::VK_ANDROID_external_memory_android_hardware_buffer[] 3767ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3768 * [[VUID-VkImageViewCreateInfo-image-02086]] 3769 If pname:image was created with pname:usage containing 3770 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 3771 pname:viewType must: be ename:VK_IMAGE_VIEW_TYPE_2D or 3772 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 3773endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3774ifdef::VK_NV_shading_rate_image[] 3775 * [[VUID-VkImageViewCreateInfo-image-02087]] 3776 If the <<features-shadingRateImage, pname:shadingRateImage feature>> is 3777 enabled, and If pname:image was created with pname:usage containing 3778 ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, pname:format must: be 3779 ename:VK_FORMAT_R8_UINT 3780endif::VK_NV_shading_rate_image[] 3781ifdef::VK_KHR_fragment_shading_rate[] 3782 * [[VUID-VkImageViewCreateInfo-usage-04550]] 3783 If the <<features-attachmentFragmentShadingRate, 3784 pname:attachmentFragmentShadingRate feature>> is enabled, and the 3785 pname:usage for the image view includes 3786 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then the 3787 image view's <<resources-image-view-format-features,format features>> 3788 must: contain 3789 ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 3790 * [[VUID-VkImageViewCreateInfo-usage-04551]] 3791 If the <<features-attachmentFragmentShadingRate, 3792 pname:attachmentFragmentShadingRate feature>> is enabled, the 3793 pname:usage for the image view includes 3794 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, and 3795 <<limits-layeredShadingRateAttachments, 3796 pname:layeredShadingRateAttachments>> is ename:VK_FALSE, 3797 pname:subresourceRange.layerCount must: be `1` 3798endif::VK_KHR_fragment_shading_rate[] 3799ifdef::VK_EXT_fragment_density_map[] 3800 * [[VUID-VkImageViewCreateInfo-flags-02572]] 3801 If <<features-fragmentDensityMapDynamic,dynamic fragment density map>> 3802 feature is not enabled, pname:flags must: not contain 3803 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 3804ifdef::VK_EXT_fragment_density_map2[] 3805 * [[VUID-VkImageViewCreateInfo-flags-03567]] 3806 If <<features-fragmentDensityMapDeferred,deferred fragment density map>> 3807 feature is not enabled, pname:flags must: not contain 3808 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT 3809 * [[VUID-VkImageViewCreateInfo-flags-03568]] 3810 If pname:flags contains 3811 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT, 3812 pname:flags must: not contain 3813 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 3814 * [[VUID-VkImageViewCreateInfo-image-03569]] 3815 If pname:image was created with pname:flags containing 3816 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT and pname:usage containing 3817 ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:subresourceRange.layerCount 3818 must: be less than or equal to 3819 <<limits-maxSubsampledArrayLayers,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:maxSubsampledArrayLayers>> 3820endif::VK_EXT_fragment_density_map2[] 3821ifdef::VK_HUAWEI_invocation_mask[] 3822 * [[VUID-VkImageViewCreateInfo-invocationMask-04993]] 3823 If the <<features-invocationMask, pname:invocationMask feature>> is 3824 enabled, and if pname:image was created with pname:usage containing 3825 ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, pname:format must: be 3826 ename:VK_FORMAT_R8_UINT 3827endif::VK_HUAWEI_invocation_mask[] 3828 * [[VUID-VkImageViewCreateInfo-flags-04116]] 3829 If pname:flags does not contain 3830 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT and 3831 pname:image was created with pname:usage containing 3832 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, its pname:flags must: 3833 not contain any of ename:VK_IMAGE_CREATE_PROTECTED_BIT, 3834 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 3835 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 3836 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 3837endif::VK_EXT_fragment_density_map[] 3838ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3839ifndef::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] 3840 * [[VUID-VkImageViewCreateInfo-pNext-02661]] 3841 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 3842 structure, its pname:usage member must: not include any bits that were 3843 not set in the pname:usage member of the slink:VkImageCreateInfo 3844 structure used to create pname:image 3845endif::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] 3846ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3847 * [[VUID-VkImageViewCreateInfo-pNext-02662]] 3848 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 3849 structure, and pname:image was not created with a 3850 slink:VkImageStencilUsageCreateInfo structure included in the 3851 pname:pNext chain of slink:VkImageCreateInfo, its pname:usage member 3852 must: not include any bits that were not set in the pname:usage member 3853 of the slink:VkImageCreateInfo structure used to create pname:image 3854 * [[VUID-VkImageViewCreateInfo-pNext-02663]] 3855 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 3856 structure, pname:image was created with a 3857 slink:VkImageStencilUsageCreateInfo structure included in the 3858 pname:pNext chain of slink:VkImageCreateInfo, and 3859 pname:subresourceRange.aspectMask includes 3860 ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the 3861 slink:VkImageViewUsageCreateInfo structure must: not include any bits 3862 that were not set in the pname:usage member of the 3863 slink:VkImageStencilUsageCreateInfo structure used to create pname:image 3864 * [[VUID-VkImageViewCreateInfo-pNext-02664]] 3865 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 3866 structure, pname:image was created with a 3867 slink:VkImageStencilUsageCreateInfo structure included in the 3868 pname:pNext chain of slink:VkImageCreateInfo, and 3869 pname:subresourceRange.aspectMask includes bits other than 3870 ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the 3871 slink:VkImageViewUsageCreateInfo structure must: not include any bits 3872 that were not set in the pname:usage member of the 3873 slink:VkImageCreateInfo structure used to create pname:image 3874endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3875endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3876 * [[VUID-VkImageViewCreateInfo-imageViewType-04973]] 3877 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, 3878 ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and 3879 pname:subresourceRange.layerCount is not 3880 ename:VK_REMAINING_ARRAY_LAYERS, then pname:subresourceRange.layerCount 3881 must: be 1 3882 * [[VUID-VkImageViewCreateInfo-imageViewType-04974]] 3883 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, 3884 ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and 3885 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 3886 then the remaining number of layers must: be 1 3887 * [[VUID-VkImageViewCreateInfo-viewType-02960]] 3888 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and 3889 pname:subresourceRange.layerCount is not 3890 ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: 3891 be `6` 3892 * [[VUID-VkImageViewCreateInfo-viewType-02961]] 3893 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and 3894 pname:subresourceRange.layerCount is not 3895 ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: 3896 be a multiple of `6` 3897 * [[VUID-VkImageViewCreateInfo-viewType-02962]] 3898 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and 3899 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 3900 the remaining number of layers must: be `6` 3901 * [[VUID-VkImageViewCreateInfo-viewType-02963]] 3902 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and 3903 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 3904 the remaining number of layers must: be a multiple of `6` 3905ifdef::VK_KHR_portability_subset[] 3906 * [[VUID-VkImageViewCreateInfo-imageViewFormatSwizzle-04465]] 3907 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 3908 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatSwizzle 3909 is ename:VK_FALSE, all elements of pname:components must: have the 3910 <<resources-image-views-identity-mappings,identity swizzle>> 3911 * [[VUID-VkImageViewCreateInfo-imageViewFormatReinterpretation-04466]] 3912 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 3913 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatReinterpretation 3914 is ename:VK_FALSE, the elink:VkFormat in pname:format must: not contain 3915 a different number of components, or a different number of bits in each 3916 component, than the format of the sname:VkImage in pname:image 3917endif::VK_KHR_portability_subset[] 3918ifdef::VK_KHR_video_decode_queue[] 3919 * [[VUID-VkImageViewCreateInfo-image-04817]] 3920 If pname:image was created with pname:usage containing 3921 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, 3922 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, 3923 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:viewType 3924 must: be ename:VK_IMAGE_VIEW_TYPE_2D or 3925 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY and all members of pname:components 3926 must: have the <<resources-image-views-identity-mappings,identity 3927 swizzle>> 3928endif::VK_KHR_video_decode_queue[] 3929ifdef::VK_KHR_video_encode_queue[] 3930 * [[VUID-VkImageViewCreateInfo-image-04818]] 3931 If pname:image was created with pname:usage containing 3932 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 3933 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, 3934 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:viewType 3935 must: be ename:VK_IMAGE_VIEW_TYPE_2D or 3936 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY and all members of pname:components 3937 must: have the <<resources-image-views-identity-mappings,identity 3938 swizzle>> 3939endif::VK_KHR_video_encode_queue[] 3940**** 3941 3942include::{generated}/validity/structs/VkImageViewCreateInfo.txt[] 3943-- 3944 3945[open,refpage='VkImageViewCreateFlagBits',desc='Bitmask specifying additional parameters of an image view',type='enums'] 3946-- 3947Bits which can: be set in slink:VkImageViewCreateInfo::pname:flags, 3948specifying additional parameters of an image view, are: 3949 3950include::{generated}/api/enums/VkImageViewCreateFlagBits.txt[] 3951 3952ifdef::VK_EXT_fragment_density_map[] 3953 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 3954 specifies that the fragment density map will be read by device during 3955 ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 3956endif::VK_EXT_fragment_density_map[] 3957ifdef::VK_EXT_fragment_density_map2[] 3958 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT 3959 specifies that the fragment density map will be read by the host during 3960 flink:vkEndCommandBuffer for the primary command buffer that the render 3961 pass is recorded into 3962endif::VK_EXT_fragment_density_map2[] 3963-- 3964 3965[open,refpage='VkImageViewCreateFlags',desc='Reserved for future use',type='flags'] 3966-- 3967include::{generated}/api/flags/VkImageViewCreateFlags.txt[] 3968 3969tname:VkImageViewCreateFlags is a bitmask type for setting a mask of zero or 3970more elink:VkImageViewCreateFlagBits. 3971-- 3972 3973ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3974[open,refpage='VkImageViewUsageCreateInfo',desc='Specify the intended usage of an image view',type='structs'] 3975-- 3976The set of usages for the created image view can: be restricted compared to 3977the parent image's pname:usage flags by adding a 3978sname:VkImageViewUsageCreateInfo structure to the pname:pNext chain of 3979slink:VkImageViewCreateInfo. 3980 3981The sname:VkImageViewUsageCreateInfo structure is defined as: 3982 3983include::{generated}/api/structs/VkImageViewUsageCreateInfo.txt[] 3984 3985ifdef::VK_KHR_maintenance2[] 3986or the equivalent 3987 3988include::{generated}/api/structs/VkImageViewUsageCreateInfoKHR.txt[] 3989endif::VK_KHR_maintenance2[] 3990 3991 * pname:sType is the type of this structure. 3992 * pname:pNext is `NULL` or a pointer to a structure extending this 3993 structure. 3994 * pname:usage is a bitmask of elink:VkImageUsageFlagBits specifying 3995 allowed usages of the image view. 3996 3997When this structure is chained to slink:VkImageViewCreateInfo the 3998pname:usage field overrides the implicit pname:usage parameter inherited 3999from image creation time and its value is used instead for the purposes of 4000determining the valid usage conditions of slink:VkImageViewCreateInfo. 4001 4002include::{generated}/validity/structs/VkImageViewUsageCreateInfo.txt[] 4003-- 4004endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4005 4006[open,refpage='VkImageSubresourceRange',desc='Structure specifying an image subresource range',type='structs'] 4007-- 4008The sname:VkImageSubresourceRange structure is defined as: 4009 4010include::{generated}/api/structs/VkImageSubresourceRange.txt[] 4011 4012 * pname:aspectMask is a bitmask of elink:VkImageAspectFlagBits specifying 4013 which aspect(s) of the image are included in the view. 4014 * pname:baseMipLevel is the first mipmap level accessible to the view. 4015 * pname:levelCount is the number of mipmap levels (starting from 4016 pname:baseMipLevel) accessible to the view. 4017 * pname:baseArrayLayer is the first array layer accessible to the view. 4018 * pname:layerCount is the number of array layers (starting from 4019 pname:baseArrayLayer) accessible to the view. 4020 4021The number of mipmap levels and array layers must: be a subset of the image 4022subresources in the image. 4023If an application wants to use all mip levels or layers in an image after 4024the pname:baseMipLevel or pname:baseArrayLayer, it can: set pname:levelCount 4025and pname:layerCount to the special values ename:VK_REMAINING_MIP_LEVELS and 4026ename:VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip 4027levels or layers. 4028 4029For cube and cube array image views, the layers of the image view starting 4030at pname:baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, 4031-Z. 4032For cube arrays, each set of six sequential layers is a single cube, so the 4033number of cube maps in a cube map array view is _pname:layerCount / 6_, and 4034image array layer [eq]#(pname:baseArrayLayer {plus} i)# is face index 4035[eq]#(i mod 6)# of cube _i / 6_. 4036If the number of layers in the view, whether set explicitly in 4037pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a 4038multiple of 6, the last cube map in the array must: not be accessed. 4039 4040pname:aspectMask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT, 4041ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if 4042pname:format is a color, depth-only or stencil-only format, 4043ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4044respectively. 4045endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4046ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4047respectively, except if pname:format is a 4048<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>. 4049endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4050If using a depth/stencil format with both depth and stencil components, 4051pname:aspectMask must: include at least one of 4052ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT, and 4053can: include both. 4054 4055ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 4056When the sname:VkImageSubresourceRange structure is used to select a subset 4057of the slices of a 3D image's mip level in order to create a 2D or 2D array 4058image view of a 3D image created with 4059ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, pname:baseArrayLayer and 4060pname:layerCount specify the first slice index and the number of slices to 4061include in the created image view. 4062Such an image view can: be used as a framebuffer attachment that refers only 4063to the specified range of slices of the selected mip level. 4064However, any layout transitions performed on such an attachment view during 4065a render pass instance still apply to the entire subresource referenced 4066which includes all the slices of the selected mip level. 4067endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 4068 4069When using an image view of a depth/stencil image to populate a descriptor 4070set (e.g. for sampling in the shader, or for use as an input attachment), 4071the pname:aspectMask must: only include one bit, which selects whether the 4072image view is used for depth reads (i.e. using a floating-point sampler or 4073input attachment in the shader) or stencil reads (i.e. using an unsigned 4074integer sampler or input attachment in the shader). 4075When an image view of a depth/stencil image is used as a depth/stencil 4076framebuffer attachment, the pname:aspectMask is ignored and both depth and 4077stencil image subresources are used. 4078 4079ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4080When creating a sname:VkImageView, if <<samplers-YCbCr-conversion,sampler 4081{YCbCr} conversion>> is enabled in the sampler, the pname:aspectMask of a 4082pname:subresourceRange used by the sname:VkImageView must: be 4083ename:VK_IMAGE_ASPECT_COLOR_BIT. 4084 4085When creating a sname:VkImageView, if sampler {YCbCr} conversion is not 4086enabled in the sampler and the image pname:format is 4087<<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, the image must: 4088have been created with ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the 4089pname:aspectMask of the sname:VkImageView's pname:subresourceRange must: be 4090ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or 4091ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 4092endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4093 4094.Valid Usage 4095**** 4096 * [[VUID-VkImageSubresourceRange-levelCount-01720]] 4097 If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: be 4098 greater than `0` 4099 * [[VUID-VkImageSubresourceRange-layerCount-01721]] 4100 If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be 4101 greater than `0` 4102ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4103 * [[VUID-VkImageSubresourceRange-aspectMask-01670]] 4104 If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, then it 4105 must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 4106 ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT 4107endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4108ifdef::VK_EXT_image_drm_format_modifier[] 4109 * [[VUID-VkImageSubresourceRange-aspectMask-02278]] 4110 pname:aspectMask must: not include 4111 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ 4112endif::VK_EXT_image_drm_format_modifier[] 4113**** 4114 4115include::{generated}/validity/structs/VkImageSubresourceRange.txt[] 4116-- 4117 4118[open,refpage='VkImageAspectFlagBits',desc='Bitmask specifying which aspects of an image are included in a view',type='enums'] 4119-- 4120Bits which can: be set in an aspect mask to specify aspects of an image for 4121purposes such as identifying a subresource, are: 4122 4123include::{generated}/api/enums/VkImageAspectFlagBits.txt[] 4124 4125 * ename:VK_IMAGE_ASPECT_COLOR_BIT specifies the color aspect. 4126 * ename:VK_IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect. 4127 * ename:VK_IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect. 4128 * ename:VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect, used 4129 for <<sparsememory, sparse resource>> operations. 4130ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4131 * ename:VK_IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a _multi-planar_ 4132 image format. 4133 * ename:VK_IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a _multi-planar_ 4134 image format. 4135 * ename:VK_IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a _multi-planar_ 4136 image format. 4137endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4138ifdef::VK_EXT_image_drm_format_modifier[] 4139 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT specifies _memory plane_ 0. 4140 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT specifies _memory plane_ 1. 4141 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT specifies _memory plane_ 2. 4142 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT specifies _memory plane_ 3. 4143endif::VK_EXT_image_drm_format_modifier[] 4144-- 4145 4146[open,refpage='VkImageAspectFlags',desc='Bitmask of VkImageAspectFlagBits',type='flags'] 4147-- 4148include::{generated}/api/flags/VkImageAspectFlags.txt[] 4149 4150tname:VkImageAspectFlags is a bitmask type for setting a mask of zero or 4151more elink:VkImageAspectFlagBits. 4152-- 4153 4154[open,refpage='VkComponentMapping',desc='Structure specifying a color component mapping',type='structs'] 4155-- 4156The sname:VkComponentMapping structure is defined as: 4157 4158include::{generated}/api/structs/VkComponentMapping.txt[] 4159 4160 * pname:r is a elink:VkComponentSwizzle specifying the component value 4161 placed in the R component of the output vector. 4162 * pname:g is a elink:VkComponentSwizzle specifying the component value 4163 placed in the G component of the output vector. 4164 * pname:b is a elink:VkComponentSwizzle specifying the component value 4165 placed in the B component of the output vector. 4166 * pname:a is a elink:VkComponentSwizzle specifying the component value 4167 placed in the A component of the output vector. 4168 4169include::{generated}/validity/structs/VkComponentMapping.txt[] 4170-- 4171 4172[open,refpage='VkComponentSwizzle',desc='Specify how a component is swizzled',type='enums'] 4173-- 4174Possible values of the members of slink:VkComponentMapping, specifying the 4175component values placed in each component of the output vector, are: 4176 4177include::{generated}/api/enums/VkComponentSwizzle.txt[] 4178 4179 * ename:VK_COMPONENT_SWIZZLE_IDENTITY specifies that the component is set 4180 to the identity swizzle. 4181 * ename:VK_COMPONENT_SWIZZLE_ZERO specifies that the component is set to 4182 zero. 4183 * ename:VK_COMPONENT_SWIZZLE_ONE specifies that the component is set to 4184 either 1 or 1.0, depending on whether the type of the image view format 4185 is integer or floating-point respectively, as determined by the 4186 <<formats-definition,Format Definition>> section for each 4187 elink:VkFormat. 4188 * ename:VK_COMPONENT_SWIZZLE_R specifies that the component is set to the 4189 value of the R component of the image. 4190 * ename:VK_COMPONENT_SWIZZLE_G specifies that the component is set to the 4191 value of the G component of the image. 4192 * ename:VK_COMPONENT_SWIZZLE_B specifies that the component is set to the 4193 value of the B component of the image. 4194 * ename:VK_COMPONENT_SWIZZLE_A specifies that the component is set to the 4195 value of the A component of the image. 4196 4197[[resources-image-views-identity-mappings]] 4198Setting the identity swizzle on a component is equivalent to setting the 4199identity mapping on that component. 4200That is: 4201 4202.Component Mappings Equivalent To ename:VK_COMPONENT_SWIZZLE_IDENTITY 4203[options="header"] 4204|==== 4205| Component | Identity Mapping 4206| pname:components.r | ename:VK_COMPONENT_SWIZZLE_R 4207| pname:components.g | ename:VK_COMPONENT_SWIZZLE_G 4208| pname:components.b | ename:VK_COMPONENT_SWIZZLE_B 4209| pname:components.a | ename:VK_COMPONENT_SWIZZLE_A 4210|==== 4211-- 4212 4213ifdef::VK_EXT_astc_decode_mode[] 4214[open,refpage='VkImageViewASTCDecodeModeEXT',desc='Structure describing the ASTC decode mode for an image view',type='structs'] 4215-- 4216If the pname:pNext chain includes a sname:VkImageViewASTCDecodeModeEXT 4217structure, then that structure includes a parameter specifying the decode 4218mode for image views using ASTC compressed formats. 4219 4220The sname:VkImageViewASTCDecodeModeEXT structure is defined as: 4221 4222include::{generated}/api/structs/VkImageViewASTCDecodeModeEXT.txt[] 4223 4224 * pname:sType is the type of this structure. 4225 * pname:pNext is `NULL` or a pointer to a structure extending this 4226 structure. 4227 * pname:decodeMode is the intermediate format used to decode ASTC 4228 compressed formats. 4229 4230.Valid Usage 4231**** 4232 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02230]] 4233 pname:decodeMode must: be one of ename:VK_FORMAT_R16G16B16A16_SFLOAT, 4234 ename:VK_FORMAT_R8G8B8A8_UNORM, or 4235 ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 4236 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02231]] 4237 If the <<features-astc-decodeModeSharedExponent, 4238 pname:decodeModeSharedExponent>> feature is not enabled, 4239 pname:decodeMode must: not be ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 4240 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02232]] 4241 If pname:decodeMode is ename:VK_FORMAT_R8G8B8A8_UNORM the image view 4242 must: not include blocks using any of the ASTC HDR modes 4243 * [[VUID-VkImageViewASTCDecodeModeEXT-format-04084]] 4244 pname:format of the image view must: be one of the 4245 <<appendix-compressedtex-astc, ASTC Compressed Image Formats>> 4246**** 4247 4248If pname:format uses sRGB encoding then the pname:decodeMode has no effect. 4249 4250include::{generated}/validity/structs/VkImageViewASTCDecodeModeEXT.txt[] 4251-- 4252endif::VK_EXT_astc_decode_mode[] 4253 4254[open,refpage='vkDestroyImageView',desc='Destroy an image view object',type='protos'] 4255-- 4256To destroy an image view, call: 4257 4258include::{generated}/api/protos/vkDestroyImageView.txt[] 4259 4260 * pname:device is the logical device that destroys the image view. 4261 * pname:imageView is the image view to destroy. 4262 * pname:pAllocator controls host memory allocation as described in the 4263 <<memory-allocation, Memory Allocation>> chapter. 4264 4265.Valid Usage 4266**** 4267 * [[VUID-vkDestroyImageView-imageView-01026]] 4268 All submitted commands that refer to pname:imageView must: have 4269 completed execution 4270 * [[VUID-vkDestroyImageView-imageView-01027]] 4271 If sname:VkAllocationCallbacks were provided when pname:imageView was 4272 created, a compatible set of callbacks must: be provided here 4273 * [[VUID-vkDestroyImageView-imageView-01028]] 4274 If no sname:VkAllocationCallbacks were provided when pname:imageView was 4275 created, pname:pAllocator must: be `NULL` 4276**** 4277 4278include::{generated}/validity/protos/vkDestroyImageView.txt[] 4279-- 4280 4281ifdef::VK_NVX_image_view_handle[] 4282[open,refpage='vkGetImageViewHandleNVX',desc='Get the handle for an image view for a specific descriptor type',type='protos'] 4283-- 4284To get the handle for an image view, call: 4285 4286include::{generated}/api/protos/vkGetImageViewHandleNVX.txt[] 4287 4288 * pname:device is the logical device that owns the image view. 4289 * pname:pInfo describes the image view to query and type of handle. 4290 4291include::{generated}/validity/protos/vkGetImageViewHandleNVX.txt[] 4292-- 4293 4294[open,refpage='VkImageViewHandleInfoNVX',desc='Structure specifying the image view for handle queries',type='structs'] 4295-- 4296The sname:VkImageViewHandleInfoNVX structure is defined as: 4297 4298include::{generated}/api/structs/VkImageViewHandleInfoNVX.txt[] 4299 4300 * pname:sType is the type of this structure. 4301 * pname:pNext is `NULL` or a pointer to a structure extending this 4302 structure. 4303 * pname:imageView is the image view to query. 4304 * pname:descriptorType is the type of descriptor for which to query a 4305 handle. 4306 * pname:sampler is the sampler to combine with the image view when 4307 generating the handle. 4308 4309.Valid Usage 4310**** 4311 * [[VUID-VkImageViewHandleInfoNVX-descriptorType-02654]] 4312 pname:descriptorType must: be ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 4313 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 4314 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 4315 * [[VUID-VkImageViewHandleInfoNVX-sampler-02655]] 4316 pname:sampler must: be a valid slink:VkSampler if pname:descriptorType 4317 is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 4318 * [[VUID-VkImageViewHandleInfoNVX-imageView-02656]] 4319 If descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 4320 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the image that 4321 pname:imageView was created from must: have been created with the 4322 ename:VK_IMAGE_USAGE_SAMPLED_BIT usage bit set 4323 * [[VUID-VkImageViewHandleInfoNVX-imageView-02657]] 4324 If descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the image 4325 that pname:imageView was created from must: have been created with the 4326 ename:VK_IMAGE_USAGE_STORAGE_BIT usage bit set 4327**** 4328 4329include::{generated}/validity/structs/VkImageViewHandleInfoNVX.txt[] 4330-- 4331 4332[open,refpage='vkGetImageViewAddressNVX',desc='Get the device address of an image view',type='protos'] 4333-- 4334To get the device address for an image view, call: 4335 4336include::{generated}/api/protos/vkGetImageViewAddressNVX.txt[] 4337 4338 * pname:device is the logical device that owns the image view. 4339 * pname:imageView is a handle to the image view. 4340 * pname:pProperties contains the device address and size when the call 4341 returns. 4342 4343include::{generated}/validity/protos/vkGetImageViewAddressNVX.txt[] 4344-- 4345 4346[open,refpage='VkImageViewAddressPropertiesNVX',desc='Structure specifying the image view for handle queries',type='structs'] 4347-- 4348The sname:VkImageViewAddressPropertiesNVX structure is defined as: 4349 4350include::{generated}/api/structs/VkImageViewAddressPropertiesNVX.txt[] 4351 4352 * pname:sType is the type of this structure. 4353 * pname:pNext is `NULL` or a pointer to a structure extending this 4354 structure. 4355 * pname:deviceAddress is the device address of the image view. 4356 * pname:size is the size in bytes of the image view device memory. 4357 4358 4359include::{generated}/validity/structs/VkImageViewAddressPropertiesNVX.txt[] 4360-- 4361endif::VK_NVX_image_view_handle[] 4362 4363 4364[[resources-image-view-format-features]] 4365=== Image View Format Features 4366 4367Valid uses of a slink:VkImageView may: depend on the image view's _format 4368features_, defined below. 4369Such constraints are documented in the affected valid usage statement. 4370 4371ifndef::VK_KHR_format_feature_flags2[] 4372 * If slink:VkImageViewCreateInfo::pname:image was created with 4373 ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format 4374 features_ is the value of 4375 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 4376 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 4377 slink:VkImageViewCreateInfo::pname:format. 4378endif::VK_KHR_format_feature_flags2[] 4379ifdef::VK_KHR_format_feature_flags2[] 4380 * If the extension `apiext:VK_KHR_format_feature_flags2` is enabled and 4381 slink:VkImageViewCreateInfo::pname:image was created with 4382 ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format 4383 features_ is the value of 4384 slink:VkFormatProperties3KHR::pname:linearTilingFeatures found by 4385 calling flink:vkGetPhysicalDeviceFormatProperties2 on the same 4386 pname:format as slink:VkImageViewCreateInfo::pname:format. 4387 * If the extension `apiext:VK_KHR_format_feature_flags2` is not enabled 4388 and slink:VkImageViewCreateInfo::pname:image was created with 4389 ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format 4390 features_ is the union of the value of 4391 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 4392 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 4393 slink:VkImageViewCreateInfo::pname:format, with: 4394 - ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR if 4395 the format is a depth/stencil format and the image view features also 4396 contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR. 4397 - ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR if the 4398 format is one of the <<formats-without-shader-storage-format,extended 4399 storage formats>> and pname:shaderStorageImageReadWithoutFormat is 4400 enabled on the device. 4401 - ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR if the 4402 format is one of the <<formats-without-shader-storage-format,extended 4403 storage formats>> and pname:shaderStorageImageWriteWithoutFormat is 4404 enabled on the device. 4405endif::VK_KHR_format_feature_flags2[] 4406ifndef::VK_KHR_format_feature_flags2[] 4407 * If slink:VkImageViewCreateInfo::pname:image was created with 4408 ename:VK_IMAGE_TILING_OPTIMAL, 4409ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4410 but without an 4411 <<memory-external-android-hardware-buffer-external-formats,Android 4412 hardware buffer external format>>, 4413endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4414 then the image view's set of _format features_ is the value of 4415 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 4416 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 4417 slink:VkImageViewCreateInfo::pname:format. 4418endif::VK_KHR_format_feature_flags2[] 4419ifdef::VK_KHR_format_feature_flags2[] 4420 * If the extension `apiext:VK_KHR_format_feature_flags2` is enabled and 4421 slink:VkImageViewCreateInfo::pname:image was created with 4422 ename:VK_IMAGE_TILING_OPTIMAL, 4423ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4424 but without an 4425 <<memory-external-android-hardware-buffer-external-formats,Android 4426 hardware buffer external format>>, 4427endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4428 then the image view's set of _format features_ is the value of 4429 slink:VkFormatProperties::pname:optimalTilingFeatures or 4430 slink:VkFormatProperties3KHR::pname:optimalTilingFeatures found by 4431 calling flink:vkGetPhysicalDeviceFormatProperties or 4432 flink:vkGetPhysicalDeviceImageFormatProperties2 on the same pname:format 4433 as slink:VkImageViewCreateInfo::pname:format. 4434 * If the extension `apiext:VK_KHR_format_feature_flags2` is not enabled 4435 and slink:VkImageViewCreateInfo::pname:image was created with 4436 ename:VK_IMAGE_TILING_OPTIMAL, 4437ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4438 but without an 4439 <<memory-external-android-hardware-buffer-external-formats,Android 4440 hardware buffer external format>>, 4441endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4442 then the image view's set of _format features_ is the union of the value 4443 of slink:VkFormatProperties::pname:optimalTilingFeatures found by 4444 calling flink:vkGetPhysicalDeviceFormatProperties on the same 4445 pname:format as slink:VkImageViewCreateInfo::pname:format, with: 4446 - ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR if 4447 the format is a depth/stencil format and the image view features also 4448 contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR. 4449 - ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR if the 4450 format is one of the <<formats-without-shader-storage-format,extended 4451 storage formats>> and pname:shaderStorageImageReadWithoutFormat is 4452 enabled on the device. 4453 - ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR if the 4454 format is one of the <<formats-without-shader-storage-format,extended 4455 storage formats>> and pname:shaderStorageImageWriteWithoutFormat is 4456 enabled on the device. 4457endif::VK_KHR_format_feature_flags2[] 4458ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4459 * If slink:VkImageViewCreateInfo::pname:image was created with an 4460 <<memory-external-android-hardware-buffer-external-formats,Android 4461 hardware buffer external format>>, then the image views's set of _format 4462 features_ is the value of 4463 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 4464 found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on 4465 the Android hardware buffer that was imported to the 4466 slink:VkDeviceMemory to which the 4467 slink:VkImageViewCreateInfo::pname:image is bound. 4468endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4469ifdef::VK_FUCHSIA_buffer_collection[] 4470 * If slink:VkImageViewCreateInfo::pname:image was created with a chained 4471 slink:VkBufferCollectionImageCreateInfoFUCHSIA, then the image view's 4472 set of _format features_ is the value of 4473 slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found by 4474 calling flink:vkGetBufferCollectionPropertiesFUCHSIA on the buffer 4475 collection passed as 4476 slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection when 4477 the image was created. 4478endif::VK_FUCHSIA_buffer_collection[] 4479ifdef::VK_EXT_image_drm_format_modifier[] 4480 * If slink:VkImageViewCreateInfo::pname:image was created with 4481 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: 4482 ** The image's DRM format modifier is the value of 4483 slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier 4484 found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. 4485 ** Let 4486 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 4487 be the array found by calling 4488 flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as 4489 slink:VkImageViewCreateInfo::pname:format. 4490 ** Let `VkDrmFormatModifierPropertiesEXT prop` be an array element whose 4491 pname:drmFormatModifier member is the value of the image's DRM format 4492 modifier. 4493 ** Then the image view's set of _format features_ is the value of taking 4494 the bitwise intersection, over the collected 4495 `prop`::pname:drmFormatModifierTilingFeatures. 4496endif::VK_EXT_image_drm_format_modifier[] 4497 4498ifdef::VK_EXT_image_view_min_lod[] 4499[open,refpage='VkImageViewMinLodCreateInfoEXT',desc='Structure describing the minimum lod of an image view',type='structs'] 4500-- 4501If the pname:pNext chain includes a sname:VkImageViewMinLodCreateInfoEXT 4502structure, then that structure includes a parameter specifying a value to 4503clamp the minimum LOD value during <<textures-image-level-selection,Image 4504Level(s) Selection>> and <<textures-integer-coordinate-operations,Integer 4505Texel Coordinate Operations>>. 4506 4507The sname:VkImageViewMinLodCreateInfoEXT structure is defined as: 4508 4509include::{generated}/api/structs/VkImageViewMinLodCreateInfoEXT.txt[] 4510 4511 * pname:sType is the type of this structure. 4512 * pname:pNext is `NULL` or a pointer to a structure extending this 4513 structure. 4514 * pname:minLod is the value to clamp the minimum LOD accessible by this 4515 slink:VkImageView. 4516 4517.Valid Usage 4518**** 4519 * [[VUID-VkImageViewMinLodCreateInfoEXT-minLod-06455]] 4520 If the <<features-minLod, pname:minLod>> feature is not enabled, 4521 pname:minLod must: be `0.0`. 4522 * [[VUID-VkImageViewMinLodCreateInfoEXT-minLod-06456]] 4523 pname:minLod must: be less or equal to the index of the last mipmap 4524 level accessible to the view. 4525**** 4526 4527include::{generated}/validity/structs/VkImageViewMinLodCreateInfoEXT.txt[] 4528-- 4529endif::VK_EXT_image_view_min_lod[] 4530 4531 4532ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 4533[[resources-acceleration-structures]] 4534== Acceleration Structures 4535 4536[open,refpage='VkAccelerationStructureKHR',desc='Opaque handle to an acceleration structure object',type='handles'] 4537-- 4538:refpage: VkAccelerationStructureKHR 4539 4540Acceleration structures are opaque data structures that are built by the 4541implementation to more efficiently perform spatial queries on the provided 4542geometric data. 4543For this extension, an acceleration structure is either a top-level 4544acceleration structure containing a set of bottom-level acceleration 4545structures or a bottom-level acceleration structure containing either a set 4546of axis-aligned bounding boxes for custom geometry or a set of triangles. 4547 4548Each instance in the top-level acceleration structure contains a reference 4549to a bottom-level acceleration structure as well as an instance transform 4550plus information required to index into the shader bindings. 4551The top-level acceleration structure is what is bound to the acceleration 4552descriptor, for example to trace inside the shader in the ray tracing 4553pipeline. 4554 4555Acceleration structures are represented by sname:VkAccelerationStructureKHR 4556handles: 4557 4558include::{generated}/api/handles/VkAccelerationStructureKHR.txt[] 4559-- 4560 4561ifdef::VK_NV_ray_tracing[] 4562[open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] 4563-- 4564:refpage: VkAccelerationStructureNV 4565 4566Acceleration structures for the apiext:VK_NV_ray_tracing extension are 4567represented by the similar sname:VkAccelerationStructureNV handles: 4568 4569include::{generated}/api/handles/VkAccelerationStructureNV.txt[] 4570-- 4571 4572[open,refpage='vkCreateAccelerationStructureNV',desc='Create a new acceleration structure object',type='protos'] 4573-- 4574:refpage: vkCreateAccelerationStructureNV 4575 4576To create acceleration structures, call: 4577 4578include::{generated}/api/protos/vkCreateAccelerationStructureNV.txt[] 4579 4580 * pname:device is the logical device that creates the buffer object. 4581 * pname:pCreateInfo is a pointer to a 4582 slink:VkAccelerationStructureCreateInfoNV structure containing 4583 parameters affecting creation of the acceleration structure. 4584 * pname:pAllocator controls host memory allocation as described in the 4585 <<memory-allocation, Memory Allocation>> chapter. 4586 * pname:pAccelerationStructure is a pointer to a 4587 slink:VkAccelerationStructureNV handle in which the resulting 4588 acceleration structure object is returned. 4589 4590Similarly to other objects in Vulkan, the acceleration structure creation 4591merely creates an object with a specific "`shape`" as specified by the 4592information in slink:VkAccelerationStructureInfoNV and pname:compactedSize 4593in pname:pCreateInfo. 4594Populating the data in the object after allocating and binding memory is 4595done with flink:vkCmdBuildAccelerationStructureNV and 4596flink:vkCmdCopyAccelerationStructureNV. 4597 4598Acceleration structure creation uses the count and type information from the 4599geometries, but does not use the data references in the structures. 4600 4601include::{generated}/validity/protos/vkCreateAccelerationStructureNV.txt[] 4602-- 4603 4604[open,refpage='VkAccelerationStructureCreateInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 4605-- 4606:refpage: VkAccelerationStructureCreateInfoNV 4607 4608The sname:VkAccelerationStructureCreateInfoNV structure is defined as: 4609 4610include::{generated}/api/structs/VkAccelerationStructureCreateInfoNV.txt[] 4611 4612 * pname:sType is the type of this structure. 4613 * pname:pNext is `NULL` or a pointer to a structure extending this 4614 structure. 4615 * pname:compactedSize is the size from the result of 4616 flink:vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration 4617 structure is going to be the target of a compacting copy. 4618 * pname:info is the slink:VkAccelerationStructureInfoNV structure 4619 specifying further parameters of the created acceleration structure. 4620 4621.Valid Usage 4622**** 4623 * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] 4624 If pname:compactedSize is not `0` then both pname:info.geometryCount and 4625 pname:info.instanceCount must: be `0` 4626**** 4627 4628include::{generated}/validity/structs/VkAccelerationStructureCreateInfoNV.txt[] 4629-- 4630 4631[open,refpage='VkAccelerationStructureInfoNV',desc='Structure specifying the parameters of acceleration structure object',type='structs'] 4632-- 4633:refpage: VkAccelerationStructureInfoNV 4634 4635The sname:VkAccelerationStructureInfoNV structure is defined as: 4636 4637include::{generated}/api/structs/VkAccelerationStructureInfoNV.txt[] 4638 4639 * pname:sType is the type of this structure. 4640 * pname:pNext is `NULL` or a pointer to a structure extending this 4641 structure. 4642 * pname:type is a elink:VkAccelerationStructureTypeNV value specifying the 4643 type of acceleration structure that will be created. 4644 * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsNV 4645 specifying additional parameters of the acceleration structure. 4646 * pname:instanceCount specifies the number of instances that will be in 4647 the new acceleration structure. 4648 * pname:geometryCount specifies the number of geometries that will be in 4649 the new acceleration structure. 4650 * pname:pGeometries is a pointer to an array of pname:geometryCount 4651 slink:VkGeometryNV structures containing the scene data being passed 4652 into the acceleration structure. 4653 4654sname:VkAccelerationStructureInfoNV contains information that is used both 4655for acceleration structure creation with 4656flink:vkCreateAccelerationStructureNV and in combination with the actual 4657geometric data to build the acceleration structure with 4658flink:vkCmdBuildAccelerationStructureNV. 4659 4660.Valid Usage 4661**** 4662 * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] 4663 pname:geometryCount must: be less than or equal to 4664 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount 4665 * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] 4666 pname:instanceCount must: be less than or equal to 4667 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount 4668 * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] 4669 The total number of triangles in all geometries must: be less than or 4670 equal to 4671 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount 4672 * [[VUID-VkAccelerationStructureInfoNV-type-02425]] 4673 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then 4674 pname:geometryCount must: be `0` 4675 * [[VUID-VkAccelerationStructureInfoNV-type-02426]] 4676 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV 4677 then pname:instanceCount must: be `0` 4678 * [[VUID-VkAccelerationStructureInfoNV-type-02786]] 4679 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV 4680 then the pname:geometryType member of each geometry in pname:pGeometries 4681 must: be the same 4682ifdef::VK_KHR_acceleration_structure[] 4683 * [[VUID-VkAccelerationStructureInfoNV-type-04623]] 4684 pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 4685endif::VK_KHR_acceleration_structure[] 4686 * [[VUID-VkAccelerationStructureInfoNV-flags-02592]] 4687 If pname:flags has the 4688 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, 4689 then it must: not have the 4690 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set 4691 * [[VUID-VkAccelerationStructureInfoNV-scratch-02781]] 4692 pname:scratch must: have been created with 4693 ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag 4694 * [[VUID-VkAccelerationStructureInfoNV-instanceData-02782]] 4695 If pname:instanceData is not dlink:VK_NULL_HANDLE, pname:instanceData 4696 must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV 4697 usage flag 4698**** 4699 4700include::{generated}/validity/structs/VkAccelerationStructureInfoNV.txt[] 4701-- 4702endif::VK_NV_ray_tracing[] 4703 4704ifdef::VK_KHR_acceleration_structure[] 4705[open,refpage='vkCreateAccelerationStructureKHR',desc='Create a new acceleration structure object',type='protos'] 4706-- 4707:refpage: vkCreateAccelerationStructureKHR 4708 4709To create an acceleration structure, call: 4710 4711include::{generated}/api/protos/vkCreateAccelerationStructureKHR.txt[] 4712 4713 * pname:device is the logical device that creates the acceleration 4714 structure object. 4715 * pname:pCreateInfo is a pointer to a 4716 slink:VkAccelerationStructureCreateInfoKHR structure containing 4717 parameters affecting creation of the acceleration structure. 4718 * pname:pAllocator controls host memory allocation as described in the 4719 <<memory-allocation, Memory Allocation>> chapter. 4720 * pname:pAccelerationStructure is a pointer to a 4721 sname:VkAccelerationStructureKHR handle in which the resulting 4722 acceleration structure object is returned. 4723 4724Similar to other objects in Vulkan, the acceleration structure creation 4725merely creates an object with a specific "`shape`". 4726The type and quantity of geometry that can be built into an acceleration 4727structure is determined by the parameters of 4728slink:VkAccelerationStructureCreateInfoKHR. 4729 4730Populating the data in the object after allocating and binding memory is 4731done with commands such as flink:vkCmdBuildAccelerationStructuresKHR, 4732flink:vkBuildAccelerationStructuresKHR, 4733flink:vkCmdCopyAccelerationStructureKHR, and 4734flink:vkCopyAccelerationStructureKHR. 4735 4736The input buffers passed to acceleration structure build commands will be 4737referenced by the implementation for the duration of the command. 4738After the command completes, the acceleration structure may: hold a 4739reference to any acceleration structure specified by an active instance 4740contained therein. 4741Apart from this referencing, acceleration structures must: be fully 4742self-contained. 4743The application may: re-use or free any memory which was used by the command 4744as an input or as scratch without affecting the results of ray traversal. 4745 4746.Valid Usage 4747**** 4748 * [[VUID-vkCreateAccelerationStructureKHR-accelerationStructure-03611]] 4749 The <<features-accelerationStructure, pname:accelerationStructure>> 4750 feature must: be enabled 4751 * [[VUID-vkCreateAccelerationStructureKHR-deviceAddress-03488]] 4752 If slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress is 4753 not zero, the 4754 <<features-accelerationStructureCaptureReplay,pname:accelerationStructureCaptureReplay>> 4755 feature must: be enabled 4756 * [[VUID-vkCreateAccelerationStructureKHR-device-03489]] 4757 If pname:device was created with multiple physical devices, then the 4758 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 4759 feature must: be enabled 4760**** 4761 4762include::{generated}/validity/protos/vkCreateAccelerationStructureKHR.txt[] 4763-- 4764 4765[open,refpage='VkAccelerationStructureCreateInfoKHR',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 4766-- 4767:refpage: VkAccelerationStructureCreateInfoKHR 4768 4769The sname:VkAccelerationStructureCreateInfoKHR structure is defined as: 4770 4771include::{generated}/api/structs/VkAccelerationStructureCreateInfoKHR.txt[] 4772 4773 * pname:sType is the type of this structure. 4774 * pname:pNext is `NULL` or a pointer to a structure extending this 4775 structure. 4776 * pname:createFlags is a bitmask of 4777 elink:VkAccelerationStructureCreateFlagBitsKHR specifying additional 4778 creation parameters of the acceleration structure. 4779 * pname:buffer is the buffer on which the acceleration structure will be 4780 stored. 4781 * pname:offset is an offset in bytes from the base address of the buffer 4782 at which the acceleration structure will be stored, and must: be a 4783 multiple of `256`. 4784 * pname:size is the size required for the acceleration structure. 4785 * pname:type is a elink:VkAccelerationStructureTypeKHR value specifying 4786 the type of acceleration structure that will be created. 4787 * pname:deviceAddress is the device address requested for the acceleration 4788 structure if the <<features-accelerationStructureCaptureReplay, 4789 pname:accelerationStructureCaptureReplay>> feature is being used. 4790 4791If pname:deviceAddress is zero, no specific address is requested. 4792 4793If pname:deviceAddress is not zero, pname:deviceAddress must: be an address 4794retrieved from an identically created acceleration structure on the same 4795implementation. 4796The acceleration structure must: also be placed on an identically created 4797pname:buffer and at the same pname:offset. 4798 4799Applications should: avoid creating acceleration structures with 4800application-provided addresses and implementation-provided addresses in the 4801same process, to reduce the likelihood of 4802ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors. 4803 4804[NOTE] 4805.Note 4806==== 4807The expected usage for this is that a trace capture/replay tool will add the 4808ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers 4809that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add 4810ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as 4811storage for an acceleration structure where pname:deviceAddress is not zero. 4812This also means that the tool will need to add 4813ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow 4814the flag to be set where the application may not have otherwise required it. 4815During capture the tool will save the queried opaque device addresses in the 4816trace. 4817During replay, the buffers will be created specifying the original address 4818so any address values stored in the trace data will remain valid. 4819 4820Implementations are expected to separate such buffers in the GPU address 4821space so normal allocations will avoid using these addresses. 4822Apps/tools should avoid mixing app-provided and implementation-provided 4823addresses for buffers created with 4824ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address 4825space allocation conflicts. 4826==== 4827 4828 4829Applications should: create an acceleration structure with a specific 4830elink:VkAccelerationStructureTypeKHR other than 4831ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. 4832 4833If the acceleration structure will be the target of a build operation, the 4834required size for an acceleration structure can: be queried with 4835flink:vkGetAccelerationStructureBuildSizesKHR. 4836If the acceleration structure is going to be the target of a compacting 4837copy, flink:vkCmdWriteAccelerationStructuresPropertiesKHR or 4838flink:vkWriteAccelerationStructuresPropertiesKHR can: be used to obtain the 4839compacted size required. 4840 4841ifdef::VK_NV_ray_tracing_motion_blur[] 4842If the acceleration structure will be the target of a build operation with 4843ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must: include 4844ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in pname:flags and 4845include slink:VkAccelerationStructureMotionInfoNV as an extension structure 4846in pname:pNext with the number of instances as metadata for the object. 4847endif::VK_NV_ray_tracing_motion_blur[] 4848 4849.Valid Usage 4850**** 4851 * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612]] 4852 If pname:deviceAddress is not zero, pname:createFlags must: include 4853 ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR 4854 * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613]] 4855 If pname:createFlags includes 4856 ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, 4857 slink:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureCaptureReplay 4858 must: be ename:VK_TRUE 4859 * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614]] 4860 pname:buffer must: have been created with a pname:usage value containing 4861 ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR 4862 * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615]] 4863 pname:buffer must: not have been created with 4864 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT 4865 * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03616]] 4866 The sum of pname:offset and pname:size must: be less than the size of 4867 pname:buffer 4868 * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03734]] 4869 pname:offset must: be a multiple of `256` bytes 4870ifdef::VK_NV_ray_tracing_motion_blur[] 4871 * [[VUID-VkAccelerationStructureCreateInfoKHR-flags-04954]] 4872 If ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV is set in 4873 pname:flags and pname:type is 4874 ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, 4875 one member of the pname:pNext chain must: be a pointer to a valid instance 4876 of slink:VkAccelerationStructureMotionInfoNV 4877 * [[VUID-VkAccelerationStructureCreateInfoKHR-flags-04955]] 4878 If any geometry includes 4879 sname:VkAccelerationStructureGeometryMotionTrianglesDataNV then 4880 pname:flags must: contain 4881 ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV 4882endif::VK_NV_ray_tracing_motion_blur[] 4883**** 4884 4885include::{generated}/validity/structs/VkAccelerationStructureCreateInfoKHR.txt[] 4886-- 4887 4888ifdef::VK_NV_ray_tracing_motion_blur[] 4889[open,refpage='VkAccelerationStructureMotionInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 4890-- 4891:refpage: VkAccelerationStructureMotionInfoNV 4892 4893The sname:VkAccelerationStructureMotionInfoNV structure is defined as: 4894 4895include::{generated}/api/structs/VkAccelerationStructureMotionInfoNV.txt[] 4896 4897 * pname:sType is the type of this structure. 4898 * pname:pNext is `NULL` or a pointer to a structure extending this 4899 structure. 4900 * pname:maxInstances is the maximum number of instances that may: be used 4901 in the motion top-level acceleration structure. 4902 * pname:flags is 0 and reserved for future use. 4903 4904include::{generated}/validity/structs/VkAccelerationStructureMotionInfoNV.txt[] 4905-- 4906 4907[open,refpage='VkAccelerationStructureMotionInfoFlagsNV',desc='Reserved for future use',type='flags'] 4908-- 4909include::{generated}/api/flags/VkAccelerationStructureMotionInfoFlagsNV.txt[] 4910 4911tname:VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting 4912a mask, but is currently reserved for future use. 4913-- 4914endif::VK_NV_ray_tracing_motion_blur[] 4915 4916[open,refpage='vkGetAccelerationStructureBuildSizesKHR',desc='Retrieve the required size for an acceleration structure',type='protos'] 4917-- 4918:refpage: vkGetAccelerationStructureBuildSizesKHR 4919 4920To get the build sizes for an acceleration structure, call: 4921 4922include::{generated}/api/protos/vkGetAccelerationStructureBuildSizesKHR.txt[] 4923 4924 * pname:device is the logical device that will be used for creating the 4925 acceleration structure. 4926 * pname:buildType defines whether host or device operations (or both) are 4927 being queried for. 4928 * pname:pBuildInfo is a pointer to a 4929 slink:VkAccelerationStructureBuildGeometryInfoKHR structure describing 4930 parameters of a build operation. 4931 * pname:pMaxPrimitiveCounts is a pointer to an array of 4932 pname:pBuildInfo->geometryCount code:uint32_t values defining the number 4933 of primitives built into each geometry. 4934 * pname:pSizeInfo is a pointer to a 4935 slink:VkAccelerationStructureBuildSizesInfoKHR structure which returns 4936 the size required for an acceleration structure and the sizes required 4937 for the scratch buffers, given the build parameters. 4938 4939The pname:srcAccelerationStructure, pname:dstAccelerationStructure, and 4940pname:mode members of pname:pBuildInfo are ignored. 4941Any slink:VkDeviceOrHostAddressKHR members of pname:pBuildInfo are ignored 4942by this command, except that the pname:hostAddress member of 4943slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 4944will be examined to check if it is `NULL`. 4945 4946An acceleration structure created with the pname:accelerationStructureSize 4947returned by this command supports any build or update with a 4948slink:VkAccelerationStructureBuildGeometryInfoKHR structure and array of 4949slink:VkAccelerationStructureBuildRangeInfoKHR structures subject to the 4950following properties: 4951 4952 * The build command is a host build command, and pname:buildType is 4953 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or 4954 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 4955 * The build command is a device build command, and pname:buildType is 4956 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or 4957 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 4958 * For slink:VkAccelerationStructureBuildGeometryInfoKHR: 4959 ** Its pname:type, and pname:flags members are equal to 4960 pname:pBuildInfo->type andm pname:pBuildInfo->flags, respectively. 4961 ** pname:geometryCount is less than or equal to 4962 pname:pBuildInfo->geometryCount. 4963 ** For each element of either pname:pGeometries or pname:ppGeometries at a 4964 given index, its pname:geometryType member is equal to 4965 pname:pBuildInfo->geometryType. 4966 ** For each element of either pname:pGeometries or pname:ppGeometries at a 4967 given index, with a pname:geometryType member equal to 4968 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:vertexFormat and 4969 pname:indexType members of pname:geometry.triangles are equal to the 4970 corresponding members of the same element in pname:pBuildInfo. 4971 ** For each element of either pname:pGeometries or pname:ppGeometries at a 4972 given index, with a pname:geometryType member equal to 4973 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:maxVertex member of 4974 pname:geometry.triangles is less than or equal to the corresponding 4975 member of the same element in pname:pBuildInfo. 4976 ** For each element of either pname:pGeometries or pname:ppGeometries at a 4977 given index, with a pname:geometryType member equal to 4978 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the 4979 pname:transformData member of pname:geometry.triangles is not `NULL`, 4980 the corresponding pname:transformData.hostAddress parameter in 4981 pname:pBuildInfo is not `NULL`. 4982 * For each slink:VkAccelerationStructureBuildRangeInfoKHR corresponding to 4983 the slink:VkAccelerationStructureBuildGeometryInfoKHR: 4984 ** Its pname:primitiveCount member is less than or equal to the 4985 corresponding element of pname:pMaxPrimitiveCounts. 4986 4987Similarly, the pname:updateScratchSize value will support any build command 4988specifying the ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR 4989pname:mode under the above conditions, and the pname:buildScratchSize value 4990will support any build command specifying the 4991ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR pname:mode under the 4992above conditions. 4993 4994.Valid Usage 4995**** 4996 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-rayTracingPipeline-03617]] 4997 The <<features-rayTracingPipeline, pname:rayTracingPipeline>> or 4998 <<features-rayQuery, pname:rayQuery>> feature must: be enabled 4999 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-device-03618]] 5000 If pname:device was created with multiple physical devices, then the 5001 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 5002 feature must: be enabled 5003 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03619]] 5004 If pname:pBuildInfo->geometryCount is not `0`, pname:pMaxPrimitiveCounts 5005 must: be a valid pointer to an array of pname:pBuildInfo->geometryCount 5006 code:uint32_t values 5007 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03785]] 5008 If pname:pBuildInfo->pGeometries or pname:pBuildInfo->ppGeometries has a 5009 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each 5010 pname:pMaxPrimitiveCounts[i] must: be less than or equal to 5011 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxInstanceCount 5012**** 5013 5014include::{generated}/validity/protos/vkGetAccelerationStructureBuildSizesKHR.txt[] 5015-- 5016 5017[open,refpage='VkAccelerationStructureBuildSizesInfoKHR',desc='Structure specifying build sizes for an acceleration structure',type='structs'] 5018-- 5019:refpage: VkAccelerationStructureBuildSizesInfoKHR 5020 5021The sname:VkAccelerationStructureBuildSizesInfoKHR structure describes the 5022required build sizes for an acceleration structure and scratch buffers and 5023is defined as: 5024 5025include::{generated}/api/structs/VkAccelerationStructureBuildSizesInfoKHR.txt[] 5026 5027 * pname:sType is the type of this structure. 5028 * pname:pNext is `NULL` or a pointer to a structure extending this 5029 structure. 5030 * pname:accelerationStructureSize is the size in bytes required in a 5031 slink:VkAccelerationStructureKHR for a build or update operation. 5032 * pname:updateScratchSize is the size in bytes required in a scratch 5033 buffer for an update operation. 5034 * pname:buildScratchSize is the size in bytes required in a scratch buffer 5035 for a build operation. 5036 5037include::{generated}/validity/structs/VkAccelerationStructureBuildSizesInfoKHR.txt[] 5038-- 5039endif::VK_KHR_acceleration_structure[] 5040 5041[open,refpage='VkAccelerationStructureTypeKHR',desc='Type of acceleration structure',type='enums',alias='VkAccelerationStructureTypeNV'] 5042-- 5043:refpage: VkAccelerationStructureTypeKHR 5044 5045Values which can: be set in 5046ifdef::VK_KHR_acceleration_structure[] 5047slink:VkAccelerationStructureCreateInfoKHR::pname:type 5048endif::VK_KHR_acceleration_structure[] 5049ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 5050ifdef::VK_NV_ray_tracing[] 5051slink:VkAccelerationStructureInfoNV::pname:type 5052endif::VK_NV_ray_tracing[] 5053specifying the type of acceleration structure, are: 5054 5055include::{generated}/api/enums/VkAccelerationStructureTypeKHR.txt[] 5056 5057ifdef::VK_NV_ray_tracing[] 5058or the equivalent 5059 5060include::{generated}/api/enums/VkAccelerationStructureTypeNV.txt[] 5061endif::VK_NV_ray_tracing[] 5062 5063 * ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR is a top-level 5064 acceleration structure containing instance data referring to 5065 bottom-level acceleration structures. 5066 * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR is a bottom-level 5067 acceleration structure containing the AABBs or geometry to be 5068 intersected. 5069 * ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is an acceleration 5070 structure whose type is determined at build time used for special 5071 circumstances. 5072-- 5073 5074ifdef::VK_KHR_acceleration_structure[] 5075[open,refpage='VkAccelerationStructureCreateFlagBitsKHR',desc='Bitmask specifying additional creation parameters for acceleration structure',type='enums'] 5076-- 5077Bits which can: be set in 5078slink:VkAccelerationStructureCreateInfoKHR::pname:createFlags specifying 5079additional creation parameters for acceleration structures, are: 5080 5081include::{generated}/api/enums/VkAccelerationStructureCreateFlagBitsKHR.txt[] 5082 5083 * ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR 5084 specifies that the acceleration structure's address can: be saved and 5085 reused on a subsequent run. 5086-- 5087 5088[open,refpage='VkAccelerationStructureCreateFlagsKHR',desc='Bitmask of VkAccelerationStructureCreateFlagBitsKHR',type='flags'] 5089-- 5090include::{generated}/api/flags/VkAccelerationStructureCreateFlagsKHR.txt[] 5091 5092tname:VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a 5093mask of zero or more elink:VkAccelerationStructureCreateFlagBitsKHR. 5094-- 5095endif::VK_KHR_acceleration_structure[] 5096 5097[open,refpage='VkBuildAccelerationStructureFlagBitsKHR',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums',alias='VkBuildAccelerationStructureFlagBitsNV'] 5098-- 5099:refpage: VkBuildAccelerationStructureFlagBitsKHR 5100 5101Bits which can: be set in 5102ifdef::VK_KHR_acceleration_structure[] 5103slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:flags 5104endif::VK_KHR_acceleration_structure[] 5105ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 5106ifdef::VK_NV_ray_tracing[] 5107slink:VkAccelerationStructureInfoNV::pname:flags 5108endif::VK_NV_ray_tracing[] 5109specifying additional parameters for acceleration structure builds, are: 5110 5111include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsKHR.txt[] 5112 5113ifdef::VK_NV_ray_tracing[] 5114or the equivalent 5115 5116include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsNV.txt[] 5117endif::VK_NV_ray_tracing[] 5118 5119 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR indicates 5120 that the specified acceleration structure can: be updated with 5121ifdef::VK_KHR_acceleration_structure[] 5122 a pname:mode of ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR in 5123 slink:VkAccelerationStructureBuildGeometryInfoKHR 5124endif::VK_KHR_acceleration_structure[] 5125ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 5126ifdef::VK_NV_ray_tracing[] 5127 an pname:update of ename:VK_TRUE in 5128 flink:vkCmdBuildAccelerationStructureNV 5129endif::VK_NV_ray_tracing[] 5130 . 5131 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR indicates 5132 that the specified acceleration structure can: act as the source for a 5133 copy acceleration structure command with pname:mode of 5134 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR to produce a 5135 compacted acceleration structure. 5136 * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR 5137 indicates that the given acceleration structure build should: prioritize 5138 trace performance over build time. 5139 * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR 5140 indicates that the given acceleration structure build should: prioritize 5141 build time over trace performance. 5142 * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR indicates that 5143 this acceleration structure should: minimize the size of the scratch 5144 memory and the final result acceleration structure, potentially at the 5145 expense of build time or trace performance. 5146 5147[NOTE] 5148.Note 5149==== 5150ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and 5151ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR may: take 5152more time and memory than a normal build, and so should: only be used when 5153those features are needed. 5154==== 5155-- 5156 5157[open,refpage='VkBuildAccelerationStructureFlagsKHR',desc='Bitmask of VkBuildAccelerationStructureFlagBitsKHR',type='flags',alias='VkBuildAccelerationStructureFlagsNV'] 5158-- 5159:refpage: VkBuildAccelerationStructureFlagsKHR 5160 5161include::{generated}/api/flags/VkBuildAccelerationStructureFlagsKHR.txt[] 5162 5163ifdef::VK_NV_ray_tracing[] 5164or the equivalent 5165 5166include::{generated}/api/flags/VkBuildAccelerationStructureFlagsNV.txt[] 5167endif::VK_NV_ray_tracing[] 5168 5169tname:VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a 5170mask of zero or more elink:VkBuildAccelerationStructureFlagBitsKHR. 5171-- 5172 5173ifdef::VK_NV_ray_tracing[] 5174[open,refpage='VkGeometryNV',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] 5175-- 5176:refpage: VkGeometryNV 5177 5178The sname:VkGeometryNV structure describes geometry in a bottom-level 5179acceleration structure and is defined as: 5180 5181include::{generated}/api/structs/VkGeometryNV.txt[] 5182 5183 * pname:sType is the type of this structure. 5184 * pname:pNext is `NULL` or a pointer to a structure extending this 5185 structure. 5186 * pname:geometryType specifies the elink:VkGeometryTypeKHR which this 5187 geometry refers to. 5188 * pname:geometry contains the geometry data as described in 5189 slink:VkGeometryDataNV. 5190 * pname:flags has elink:VkGeometryFlagBitsKHR describing options for this 5191 geometry. 5192 5193.Valid Usage 5194**** 5195 * [[VUID-VkGeometryNV-geometryType-03503]] 5196 pname:geometryType must: be ename:VK_GEOMETRY_TYPE_TRIANGLES_NV or 5197 ename:VK_GEOMETRY_TYPE_AABBS_NV 5198**** 5199 5200include::{generated}/validity/structs/VkGeometryNV.txt[] 5201-- 5202endif::VK_NV_ray_tracing[] 5203 5204[open,refpage='VkGeometryTypeKHR',desc='Enum specifying which type of geometry is provided',type='enums',alias='VkGeometryTypeNV'] 5205-- 5206:refpage: VkGeometryTypeKHR 5207 5208Geometry types are specified by elink:VkGeometryTypeKHR, which takes values: 5209 5210include::{generated}/api/enums/VkGeometryTypeKHR.txt[] 5211 5212ifdef::VK_NV_ray_tracing[] 5213or the equivalent 5214 5215include::{generated}/api/enums/VkGeometryTypeNV.txt[] 5216endif::VK_NV_ray_tracing[] 5217 5218 * ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR specifies a geometry type 5219 consisting of triangles. 5220 * ename:VK_GEOMETRY_TYPE_AABBS_KHR specifies a geometry type consisting of 5221 axis-aligned bounding boxes. 5222ifdef::VK_KHR_acceleration_structure[] 5223 * ename:VK_GEOMETRY_TYPE_INSTANCES_KHR specifies a geometry type 5224 consisting of acceleration structure instances. 5225endif::VK_KHR_acceleration_structure[] 5226-- 5227 5228[open,refpage='VkGeometryFlagBitsKHR',desc='Bitmask specifying additional parameters for a geometry',type='enums',alias='VkGeometryFlagBitsNV'] 5229-- 5230:refpage: VkGeometryFlagBitsKHR 5231 5232Bits specifying additional parameters for geometries in acceleration 5233structure builds, are: 5234 5235include::{generated}/api/enums/VkGeometryFlagBitsKHR.txt[] 5236 5237ifdef::VK_NV_ray_tracing[] 5238or the equivalent 5239 5240include::{generated}/api/enums/VkGeometryFlagBitsNV.txt[] 5241endif::VK_NV_ray_tracing[] 5242 5243 * ename:VK_GEOMETRY_OPAQUE_BIT_KHR indicates that this geometry does not 5244 invoke the any-hit shaders even if present in a hit group. 5245 * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR indicates that 5246 the implementation must: only call the any-hit shader a single time for 5247 each primitive in this geometry. 5248 If this bit is absent an implementation may: invoke the any-hit shader 5249 more than once for this geometry. 5250-- 5251 5252[open,refpage='VkGeometryFlagsKHR',desc='Bitmask of VkGeometryFlagBitsKHR',type='flags',alias='VkGeometryFlagsNV'] 5253-- 5254:refpage: VkGeometryFlagsKHR 5255 5256include::{generated}/api/flags/VkGeometryFlagsKHR.txt[] 5257 5258ifdef::VK_NV_ray_tracing[] 5259or the equivalent 5260 5261include::{generated}/api/flags/VkGeometryFlagsNV.txt[] 5262endif::VK_NV_ray_tracing[] 5263 5264tname:VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or 5265more elink:VkGeometryFlagBitsKHR. 5266-- 5267 5268ifdef::VK_NV_ray_tracing[] 5269[open,refpage='VkGeometryDataNV',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] 5270-- 5271:refpage: VkGeometryDataNV 5272 5273The sname:VkGeometryDataNV structure specifes geometry in a bottom-level 5274acceleration structure and is defined as: 5275 5276include::{generated}/api/structs/VkGeometryDataNV.txt[] 5277 5278 * pname:triangles contains triangle data if 5279 slink:VkGeometryNV::pname:geometryType is 5280 ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. 5281 * pname:aabbs contains axis-aligned bounding box data if 5282 slink:VkGeometryNV::pname:geometryType is 5283 ename:VK_GEOMETRY_TYPE_AABBS_NV. 5284 5285include::{generated}/validity/structs/VkGeometryDataNV.txt[] 5286-- 5287 5288[open,refpage='VkGeometryTrianglesNV',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] 5289-- 5290:refpage: VkGeometryTrianglesNV 5291 5292The sname:VkGeometryTrianglesNV structure specifies triangle geometry in a 5293bottom-level acceleration structure and is defined as: 5294 5295include::{generated}/api/structs/VkGeometryTrianglesNV.txt[] 5296 5297 * pname:sType is the type of this structure. 5298 * pname:pNext is `NULL` or a pointer to a structure extending this 5299 structure. 5300 * pname:vertexData is the buffer containing vertex data for this geometry. 5301 * pname:vertexOffset is the offset in bytes within pname:vertexData 5302 containing vertex data for this geometry. 5303 * pname:vertexCount is the number of valid vertices. 5304 * pname:vertexStride is the stride in bytes between each vertex. 5305 * pname:vertexFormat is a elink:VkFormat describing the format of each 5306 vertex element. 5307 * pname:indexData is the buffer containing index data for this geometry. 5308 * pname:indexOffset is the offset in bytes within pname:indexData 5309 containing index data for this geometry. 5310 * pname:indexCount is the number of indices to include in this geometry. 5311 * pname:indexType is a elink:VkIndexType describing the format of each 5312 index. 5313 * pname:transformData is an optional buffer containing an 5314 slink:VkTransformMatrixNV structure defining a transformation to be 5315 applied to this geometry. 5316 * pname:transformOffset is the offset in bytes in pname:transformData of 5317 the transform information described above. 5318 5319If pname:indexType is ename:VK_INDEX_TYPE_NONE_NV, then this structure 5320describes a set of triangles determined by pname:vertexCount. 5321Otherwise, this structure describes a set of indexed triangles determined by 5322pname:indexCount. 5323 5324.Valid Usage 5325**** 5326 * [[VUID-VkGeometryTrianglesNV-vertexOffset-02428]] 5327 pname:vertexOffset must: be less than the size of pname:vertexData 5328 * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] 5329 pname:vertexOffset must: be a multiple of the component size of 5330 pname:vertexFormat 5331 * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] 5332 pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, 5333 ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, 5334 ename:VK_FORMAT_R16G16_SFLOAT, ename:VK_FORMAT_R16G16_SNORM, or 5335 ename:VK_FORMAT_R16G16B16_SNORM 5336 * [[VUID-VkGeometryTrianglesNV-vertexStride-03818]] 5337 pname:vertexStride must: be less than or equal to [eq]#2^32^-1# 5338 * [[VUID-VkGeometryTrianglesNV-indexOffset-02431]] 5339 pname:indexOffset must: be less than the size of pname:indexData 5340 * [[VUID-VkGeometryTrianglesNV-indexOffset-02432]] 5341 pname:indexOffset must: be a multiple of the element size of 5342 pname:indexType 5343 * [[VUID-VkGeometryTrianglesNV-indexType-02433]] 5344 pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, 5345 ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_NV 5346 * [[VUID-VkGeometryTrianglesNV-indexData-02434]] 5347 pname:indexData must: be dlink:VK_NULL_HANDLE if pname:indexType is 5348 ename:VK_INDEX_TYPE_NONE_NV 5349 * [[VUID-VkGeometryTrianglesNV-indexData-02435]] 5350 pname:indexData must: be a valid sname:VkBuffer handle if 5351 pname:indexType is not ename:VK_INDEX_TYPE_NONE_NV 5352 * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] 5353 pname:indexCount must: be `0` if pname:indexType is 5354 ename:VK_INDEX_TYPE_NONE_NV 5355 * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] 5356 pname:transformOffset must: be less than the size of pname:transformData 5357 * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] 5358 pname:transformOffset must: be a multiple of `16` 5359**** 5360 5361include::{generated}/validity/structs/VkGeometryTrianglesNV.txt[] 5362-- 5363 5364[open,refpage='VkGeometryAABBNV',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] 5365-- 5366:refpage: VkGeometryAABBNV 5367 5368The sname:VkGeometryAABBNV structure specifies axis-aligned bounding box 5369geometry in a bottom-level acceleration structure, and is defined as: 5370 5371include::{generated}/api/structs/VkGeometryAABBNV.txt[] 5372 5373 * pname:sType is the type of this structure. 5374 * pname:pNext is `NULL` or a pointer to a structure extending this 5375 structure. 5376 * pname:aabbData is the buffer containing axis-aligned bounding box data. 5377 * pname:numAABBs is the number of AABBs in this geometry. 5378 * pname:stride is the stride in bytes between AABBs in pname:aabbData. 5379 * pname:offset is the offset in bytes of the first AABB in pname:aabbData. 5380 5381The AABB data in memory is six 32-bit floats consisting of the minimum x, y, 5382and z values followed by the maximum x, y, and z values. 5383 5384.Valid Usage 5385**** 5386 * [[VUID-VkGeometryAABBNV-offset-02439]] 5387 pname:offset must: be less than the size of pname:aabbData 5388 * [[VUID-VkGeometryAABBNV-offset-02440]] 5389 pname:offset must: be a multiple of `8` 5390 * [[VUID-VkGeometryAABBNV-stride-02441]] 5391 pname:stride must: be a multiple of `8` 5392**** 5393 5394include::{generated}/validity/structs/VkGeometryAABBNV.txt[] 5395-- 5396endif::VK_NV_ray_tracing[] 5397 5398[open,refpage='vkDestroyAccelerationStructureKHR',desc='Destroy an acceleration structure object',type='protos'] 5399-- 5400:refpage: vkDestroyAccelerationStructureKHR 5401 5402To destroy an acceleration structure, call: 5403 5404ifdef::VK_KHR_acceleration_structure[] 5405include::{generated}/api/protos/vkDestroyAccelerationStructureKHR.txt[] 5406endif::VK_KHR_acceleration_structure[] 5407 5408 * pname:device is the logical device that destroys the acceleration 5409 structure. 5410 * pname:accelerationStructure is the acceleration structure to destroy. 5411 * pname:pAllocator controls host memory allocation as described in the 5412 <<memory-allocation, Memory Allocation>> chapter. 5413 5414.Valid Usage 5415**** 5416 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02442]] 5417 All submitted commands that refer to pname:accelerationStructure must: 5418 have completed execution 5419 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02443]] 5420 If sname:VkAllocationCallbacks were provided when 5421 pname:accelerationStructure was created, a compatible set of callbacks 5422 must: be provided here 5423 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02444]] 5424 If no sname:VkAllocationCallbacks were provided when 5425 pname:accelerationStructure was created, pname:pAllocator must: be 5426 `NULL` 5427**** 5428 5429include::{generated}/validity/protos/vkDestroyAccelerationStructureKHR.txt[] 5430-- 5431 5432ifdef::VK_NV_ray_tracing[] 5433[open,refpage='vkDestroyAccelerationStructureNV',desc='Destroy an acceleration structure object',type='protos'] 5434-- 5435:refpage: vkDestroyAccelerationStructureNV 5436 5437To destroy an acceleration structure, call: 5438 5439include::{generated}/api/protos/vkDestroyAccelerationStructureNV.txt[] 5440 5441 * pname:device is the logical device that destroys the buffer. 5442 * pname:accelerationStructure is the acceleration structure to destroy. 5443 * pname:pAllocator controls host memory allocation as described in the 5444 <<memory-allocation, Memory Allocation>> chapter. 5445 5446.Valid Usage 5447**** 5448 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03752]] 5449 All submitted commands that refer to pname:accelerationStructure must: 5450 have completed execution 5451 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03753]] 5452 If sname:VkAllocationCallbacks were provided when 5453 pname:accelerationStructure was created, a compatible set of callbacks 5454 must: be provided here 5455 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03754]] 5456 If no sname:VkAllocationCallbacks were provided when 5457 pname:accelerationStructure was created, pname:pAllocator must: be 5458 `NULL` 5459**** 5460 5461include::{generated}/validity/protos/vkDestroyAccelerationStructureNV.txt[] 5462-- 5463 5464[open,refpage='vkGetAccelerationStructureMemoryRequirementsNV',desc='Get acceleration structure memory requirements',type='protos'] 5465-- 5466:refpage: vkGetAccelerationStructureMemoryRequirementsNV 5467 5468An acceleration structure has memory requirements for the structure object 5469itself, scratch space for the build, and scratch space for the update. 5470 5471Scratch space is allocated as a sname:VkBuffer, so for 5472ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 5473and 5474ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 5475the pname:pMemoryRequirements->alignment and 5476pname:pMemoryRequirements->memoryTypeBits values returned by this call must: 5477be filled with zero, and should: be ignored by the application. 5478 5479To query the memory requirements, call: 5480 5481include::{generated}/api/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] 5482 5483 * pname:device is the logical device on which the acceleration structure 5484 was created. 5485 * pname:pInfo is a pointer to a 5486 slink:VkAccelerationStructureMemoryRequirementsInfoNV structure 5487 specifying the acceleration structure to get memory requirements for. 5488 * pname:pMemoryRequirements is a pointer to a 5489 slink:VkMemoryRequirements2KHR structure in which the requested 5490 acceleration structure memory requirements are returned. 5491 5492include::{generated}/validity/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] 5493-- 5494 5495[open,refpage='VkAccelerationStructureMemoryRequirementsInfoNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] 5496-- 5497:refpage: VkAccelerationStructureMemoryRequirementsInfoNV 5498 5499The sname:VkAccelerationStructureMemoryRequirementsInfoNV structure is 5500defined as: 5501 5502include::{generated}/api/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] 5503 5504 * pname:sType is the type of this structure. 5505 * pname:pNext is `NULL` or a pointer to a structure extending this 5506 structure. 5507 * pname:type selects the type of memory requirement being queried. 5508 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 5509 returns the memory requirements for the object itself. 5510 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 5511 returns the memory requirements for the scratch memory when doing a 5512 build. 5513 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 5514 returns the memory requirements for the scratch memory when doing an 5515 update. 5516 * pname:accelerationStructure is the acceleration structure to be queried 5517 for memory requirements. 5518 5519include::{generated}/validity/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] 5520-- 5521 5522[open,refpage='VkAccelerationStructureMemoryRequirementsTypeNV',desc='Acceleration structure memory requirement type',type='enums'] 5523-- 5524:refpage: VkAccelerationStructureMemoryRequirementsTypeNV 5525 5526Possible values of pname:type in 5527sname:VkAccelerationStructureMemoryRequirementsInfoNV are:, 5528 5529include::{generated}/api/enums/VkAccelerationStructureMemoryRequirementsTypeNV.txt[] 5530 5531 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 5532 requests the memory requirement for the sname:VkAccelerationStructureNV 5533 backing store. 5534 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 5535 requests the memory requirement for scratch space during the initial 5536 build. 5537 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 5538 requests the memory requirement for scratch space during an update. 5539-- 5540endif::VK_NV_ray_tracing[] 5541 5542ifdef::VK_KHR_acceleration_structure[] 5543[open,refpage='VkAccelerationStructureBuildTypeKHR',desc='Acceleration structure build type',type='enums'] 5544-- 5545:refpage: VkAccelerationStructureBuildTypeKHR 5546 5547Possible values of pname:buildType in 5548flink:vkGetAccelerationStructureBuildSizesKHR are: 5549 5550include::{generated}/api/enums/VkAccelerationStructureBuildTypeKHR.txt[] 5551 5552 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR requests the memory 5553 requirement for operations performed by the host. 5554 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR requests the 5555 memory requirement for operations performed by the device. 5556 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR requests 5557 the memory requirement for operations performed by either the host, or 5558 the device. 5559-- 5560endif::VK_KHR_acceleration_structure[] 5561 5562ifdef::VK_NV_ray_tracing[] 5563[open,refpage='vkBindAccelerationStructureMemoryNV',desc='Bind acceleration structure memory',type='protos'] 5564-- 5565:refpage: vkBindAccelerationStructureMemoryNV 5566 5567To attach memory to one or more acceleration structures at a time, call: 5568 5569include::{generated}/api/protos/vkBindAccelerationStructureMemoryNV.txt[] 5570 5571 * pname:device is the logical device that owns the acceleration structures 5572 and memory. 5573 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 5574 * pname:pBindInfos is a pointer to an array of 5575 slink:VkBindAccelerationStructureMemoryInfoNV structures describing 5576 acceleration structures and memory to bind. 5577 5578include::{generated}/validity/protos/vkBindAccelerationStructureMemoryNV.txt[] 5579-- 5580 5581[open,refpage='VkBindAccelerationStructureMemoryInfoNV',desc='Structure specifying acceleration structure memory binding',type='structs'] 5582-- 5583:refpage: VkBindAccelerationStructureMemoryInfoNV 5584 5585The sname:VkBindAccelerationStructureMemoryInfoNV structure is defined as: 5586 5587include::{generated}/api/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] 5588 5589 * pname:sType is the type of this structure. 5590 * pname:pNext is `NULL` or a pointer to a structure extending this 5591 structure. 5592 * pname:accelerationStructure is the acceleration structure to be attached 5593 to memory. 5594 * pname:memory is a sname:VkDeviceMemory object describing the device 5595 memory to attach. 5596 * pname:memoryOffset is the start offset of the region of memory that is 5597 to be bound to the acceleration structure. 5598 The number of bytes returned in the 5599 slink:VkMemoryRequirements::pname:size member in pname:memory, starting 5600 from pname:memoryOffset bytes, will be bound to the specified 5601 acceleration structure. 5602 * pname:deviceIndexCount is the number of elements in 5603 pname:pDeviceIndices. 5604 * pname:pDeviceIndices is a pointer to an array of device indices. 5605 5606.Valid Usage 5607**** 5608 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-03620]] 5609 pname:accelerationStructure must: not already be backed by a memory 5610 object 5611 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03621]] 5612 pname:memoryOffset must: be less than the size of pname:memory 5613 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-03622]] 5614 pname:memory must: have been allocated using one of the memory types 5615 allowed in the pname:memoryTypeBits member of the 5616 slink:VkMemoryRequirements structure returned from a call to 5617 flink:vkGetAccelerationStructureMemoryRequirementsNV with 5618 pname:accelerationStructure and pname:type of 5619 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 5620 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03623]] 5621 pname:memoryOffset must: be an integer multiple of the pname:alignment 5622 member of the slink:VkMemoryRequirements structure returned from a call 5623 to flink:vkGetAccelerationStructureMemoryRequirementsNV with 5624 pname:accelerationStructure and pname:type of 5625 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 5626 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-03624]] 5627 The pname:size member of the sname:VkMemoryRequirements structure 5628 returned from a call to 5629 flink:vkGetAccelerationStructureMemoryRequirementsNV with 5630 pname:accelerationStructure and pname:type of 5631 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: 5632 be less than or equal to the size of pname:memory minus 5633 pname:memoryOffset 5634**** 5635 5636include::{generated}/validity/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] 5637-- 5638 5639[open,refpage='vkGetAccelerationStructureHandleNV',desc='Get opaque acceleration structure handle',type='protos'] 5640-- 5641:refpage: vkGetAccelerationStructureHandleNV 5642 5643To allow constructing geometry instances with device code if desired, we 5644need to be able to query a opaque handle for an acceleration structure. 5645This handle is a value of 8 bytes. 5646To get this handle, call: 5647 5648include::{generated}/api/protos/vkGetAccelerationStructureHandleNV.txt[] 5649 5650 * pname:device is the logical device that owns the acceleration 5651 structures. 5652 * pname:accelerationStructure is the acceleration structure. 5653 * pname:dataSize is the size in bytes of the buffer pointed to by 5654 pname:pData. 5655 * pname:pData is a pointer to a user-allocated buffer where the results 5656 will be written. 5657 5658.Valid Usage 5659**** 5660 * [[VUID-vkGetAccelerationStructureHandleNV-dataSize-02240]] 5661 pname:dataSize must: be large enough to contain the result of the query, 5662 as described above 5663 * [[VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-02787]] 5664 pname:accelerationStructure must: be bound completely and contiguously 5665 to a single sname:VkDeviceMemory object via 5666 flink:vkBindAccelerationStructureMemoryNV 5667**** 5668 5669include::{generated}/validity/protos/vkGetAccelerationStructureHandleNV.txt[] 5670-- 5671endif::VK_NV_ray_tracing[] 5672 5673ifdef::VK_KHR_acceleration_structure[] 5674[open,refpage='vkGetAccelerationStructureDeviceAddressKHR',desc='Query an address of a acceleration structure',type='protos'] 5675-- 5676:refpage: vkGetAccelerationStructureDeviceAddressKHR 5677 5678To query the 64-bit device address for an acceleration structure, call: 5679 5680include::{generated}/api/protos/vkGetAccelerationStructureDeviceAddressKHR.txt[] 5681 5682 * pname:device is the logical device that the acceleration structure was 5683 created on. 5684 * pname:pInfo is a pointer to a 5685 slink:VkAccelerationStructureDeviceAddressInfoKHR structure specifying 5686 the acceleration structure to retrieve an address for. 5687 5688The 64-bit return value is an address of the acceleration structure, which 5689can be used for device and shader operations that involve acceleration 5690structures, such as 5691ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 5692ray traversal and 5693endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 5694acceleration structure building. 5695 5696If the acceleration structure was created with a non-zero value of 5697slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress, the return 5698value will be the same address. 5699 5700If the acceleration structure was created with a pname:type of 5701ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must: 5702be consistent with the relative offset to other acceleration structures with 5703pname:type ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with 5704the same slink:VkBuffer. 5705That is, the difference in returned addresses between the two must: be the 5706same as the difference in offsets provided at acceleration structure 5707creation. 5708 5709[NOTE] 5710.Note 5711==== 5712The acceleration structure device address may: be different from the buffer 5713device address corresponding to the acceleration structure's start offset in 5714its storage buffer for acceleration structure types other than 5715ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. 5716==== 5717 5718.Valid Usage 5719**** 5720 * [[VUID-vkGetAccelerationStructureDeviceAddressKHR-device-03504]] 5721 If pname:device was created with multiple physical devices, then the 5722 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 5723 feature must: be enabled 5724**** 5725 5726include::{generated}/validity/protos/vkGetAccelerationStructureDeviceAddressKHR.txt[] 5727-- 5728 5729[open,refpage='VkAccelerationStructureDeviceAddressInfoKHR',desc='Structure specifying the acceleration structure to query an address for',type='structs'] 5730-- 5731:refpage: VkAccelerationStructureDeviceAddressInfoKHR 5732 5733The sname:VkAccelerationStructureDeviceAddressInfoKHR structure is defined 5734as: 5735 5736include::{generated}/api/structs/VkAccelerationStructureDeviceAddressInfoKHR.txt[] 5737 5738 * pname:sType is the type of this structure. 5739 * pname:pNext is `NULL` or a pointer to a structure extending this 5740 structure. 5741 * pname:accelerationStructure specifies the acceleration structure whose 5742 address is being queried. 5743 5744include::{generated}/validity/structs/VkAccelerationStructureDeviceAddressInfoKHR.txt[] 5745-- 5746endif::VK_KHR_acceleration_structure[] 5747endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 5748 5749 5750[[resources-association]] 5751== Resource Memory Association 5752 5753Resources are initially created as _virtual allocations_ with no backing 5754memory. 5755Device memory is allocated separately (see <<memory-device>>) and then 5756associated with the resource. 5757This association is done differently for sparse and non-sparse resources. 5758 5759Resources created with any of the sparse creation flags are considered 5760sparse resources. 5761Resources created without these flags are non-sparse. 5762The details on resource memory association for sparse resources is described 5763in <<sparsememory>>. 5764 5765Non-sparse resources must: be bound completely and contiguously to a single 5766sname:VkDeviceMemory object before the resource is passed as a parameter to 5767any of the following operations: 5768 5769 * creating image or buffer views 5770 * updating descriptor sets 5771 * recording commands in a command buffer 5772 5773Once bound, the memory binding is immutable for the lifetime of the 5774resource. 5775 5776ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5777 5778In a logical device representing more than one physical device, buffer and 5779image resources exist on all physical devices but can: be bound to memory 5780differently on each. 5781Each such replicated resource is an _instance_ of the resource. 5782For sparse resources, each instance can: be bound to memory arbitrarily 5783differently. 5784For non-sparse resources, each instance can: either be bound to the local or 5785a peer instance of the memory, or for images can: be bound to rectangular 5786regions from the local and/or peer instances. 5787When a resource is used in a descriptor set, each physical device interprets 5788the descriptor according to its own instance's binding to memory. 5789 5790[NOTE] 5791.Note 5792==== 5793There are no new copy commands to transfer data between physical devices. 5794Instead, an application can: create a resource with a peer mapping and use 5795it as the source or destination of a transfer command executed by a single 5796physical device to copy the data from one physical device to another. 5797==== 5798 5799endif::VK_VERSION_1_1,VK_KHR_device_group[] 5800 5801[open,refpage='vkGetBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 5802-- 5803To determine the memory requirements for a buffer resource, call: 5804 5805include::{generated}/api/protos/vkGetBufferMemoryRequirements.txt[] 5806 5807 * pname:device is the logical device that owns the buffer. 5808 * pname:buffer is the buffer to query. 5809 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements 5810 structure in which the memory requirements of the buffer object are 5811 returned. 5812 5813include::{generated}/validity/protos/vkGetBufferMemoryRequirements.txt[] 5814-- 5815 5816[open,refpage='vkGetImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 5817-- 5818ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5819To determine the memory requirements for an image resource, call: 5820endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5821ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5822To determine the memory requirements for an image resource which is not 5823created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set, call: 5824endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5825 5826include::{generated}/api/protos/vkGetImageMemoryRequirements.txt[] 5827 5828 * pname:device is the logical device that owns the image. 5829 * pname:image is the image to query. 5830 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements 5831 structure in which the memory requirements of the image object are 5832 returned. 5833 5834.Valid Usage 5835**** 5836ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5837 * [[VUID-vkGetImageMemoryRequirements-image-01588]] 5838 pname:image must: not have been created with the 5839 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set 5840endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5841ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 5842 * [[VUID-vkGetImageMemoryRequirements-image-04004]] 5843 If pname:image was created with the 5844 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 5845 external memory handle type, then pname:image must: be bound to memory 5846endif::VK_ANDROID_external_memory_android_hardware_buffer[] 5847**** 5848 5849include::{generated}/validity/protos/vkGetImageMemoryRequirements.txt[] 5850-- 5851 5852[open,refpage='VkMemoryRequirements',desc='Structure specifying memory requirements',type='structs'] 5853-- 5854The sname:VkMemoryRequirements structure is defined as: 5855 5856include::{generated}/api/structs/VkMemoryRequirements.txt[] 5857 5858 * pname:size is the size, in bytes, of the memory allocation required: for 5859 the resource. 5860 * pname:alignment is the alignment, in bytes, of the offset within the 5861 allocation required: for the resource. 5862 * pname:memoryTypeBits is a bitmask and contains one bit set for every 5863 supported memory type for the resource. 5864 Bit `i` is set if and only if the memory type `i` in the 5865 sname:VkPhysicalDeviceMemoryProperties structure for the physical device 5866 is supported for the resource. 5867 5868include::{generated}/validity/structs/VkMemoryRequirements.txt[] 5869-- 5870 5871ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 5872The precise size of images that will be bound to external Android hardware 5873buffer memory is unknown until the memory has been imported or allocated, so 5874applications must: not call flink:vkGetImageMemoryRequirements or 5875flink:vkGetImageMemoryRequirements2 with such an slink:VkImage before it has 5876been bound to memory. 5877ifdef::VK_KHR_maintenance4[] 5878For this reason, applications also must: not call 5879flink:vkGetDeviceImageMemoryRequirementsKHR with a slink:VkImageCreateInfo 5880describing an external Android hardware buffer. 5881endif::VK_KHR_maintenance4[] 5882When importing Android hardware buffer memory, the pname:allocationSize can: 5883be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID. 5884When allocating new memory for a slink:VkImage that can: be exported to an 5885Android hardware buffer, the memory's pname:allocationSize must: be zero; 5886the actual size will be determined by the dedicated image's parameters. 5887After the memory has been allocated, the amount of space allocated from the 5888memory's heap can: be obtained by getting the image's memory requirements or 5889by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID with the 5890Android hardware buffer exported from the memory. 5891 5892When allocating new memory for a slink:VkBuffer that can: be exported to an 5893Android hardware buffer an application may: still call 5894flink:vkGetBufferMemoryRequirements or flink:vkGetBufferMemoryRequirements2 5895with slink:VkBuffer before it has been bound to memory. 5896endif::VK_ANDROID_external_memory_android_hardware_buffer[] 5897 5898ifdef::VK_KHR_external_memory_win32[] 5899If the resource being queried was created with the 5900ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 5901ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or 5902ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT external memory 5903handle type, the value of pname:size has no meaning and should: be ignored. 5904endif::VK_KHR_external_memory_win32[] 5905 5906The implementation guarantees certain properties about the memory 5907requirements returned by 5908ifdef::VK_KHR_get_memory_requirements2[] 5909flink:vkGetBufferMemoryRequirements2, flink:vkGetImageMemoryRequirements2, 5910endif::VK_KHR_get_memory_requirements2[] 5911ifdef::VK_KHR_maintenance4[] 5912flink:vkGetDeviceBufferMemoryRequirementsKHR, 5913flink:vkGetDeviceImageMemoryRequirementsKHR, 5914endif::VK_KHR_maintenance4[] 5915flink:vkGetBufferMemoryRequirements and flink:vkGetImageMemoryRequirements: 5916 5917 * The pname:memoryTypeBits member always contains at least one bit set. 5918 * If pname:buffer is a sname:VkBuffer not created with the 5919 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bit set, or if pname:image is 5920 <<glossary-linear-resource,linear>> image, then the pname:memoryTypeBits 5921 member always contains at least one bit set corresponding to a 5922 sname:VkMemoryType with a pname:propertyFlags that has both the 5923 ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the 5924 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set. 5925 In other words, mappable coherent memory can: always be attached to 5926 these objects. 5927ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 5928 * If pname:buffer was created with 5929 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes set to `0` or 5930 pname:image was created with 5931 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes set to `0`, the 5932endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5933ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 5934 * The 5935endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5936 pname:memoryTypeBits member always contains at least one bit set 5937 corresponding to a sname:VkMemoryType with a pname:propertyFlags that 5938 has the ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set. 5939 * The pname:memoryTypeBits member is identical for all sname:VkBuffer 5940 objects created with the same value for the pname:flags and pname:usage 5941 members in the slink:VkBufferCreateInfo structure 5942ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 5943 and the pname:handleTypes member of the 5944 slink:VkExternalMemoryBufferCreateInfo structure 5945endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5946 passed to flink:vkCreateBuffer. 5947 Further, if code:usage1 and code:usage2 of type tlink:VkBufferUsageFlags 5948 are such that the bits set in code:usage2 are a subset of the bits set 5949 in code:usage1, and they have the same 5950ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 5951 pname:flags and 5952 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes, 5953endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5954ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 5955 pname:flags, 5956endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5957 then the bits set in pname:memoryTypeBits returned for code:usage1 must: 5958 be a subset of the bits set in pname:memoryTypeBits returned for 5959 code:usage2, for all values of pname:flags. 5960 * The pname:alignment member is a power of two. 5961 * The pname:alignment member is identical for all sname:VkBuffer objects 5962 created with the same combination of values for the pname:usage and 5963 pname:flags members in the slink:VkBufferCreateInfo structure passed to 5964 flink:vkCreateBuffer. 5965ifdef::VK_KHR_maintenance4[] 5966 * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, 5967 then the pname:alignment member is identical for all sname:VkImage 5968 objects created with the same combination of values for the pname:flags, 5969 pname:imageType, pname:format, pname:extent, pname:mipLevels, 5970 pname:arrayLayers, pname:samples, pname:tiling and pname:usage members 5971 in the slink:VkImageCreateInfo structure passed to flink:vkCreateImage. 5972endif::VK_KHR_maintenance4[] 5973 * The pname:alignment member satisfies the buffer descriptor offset 5974 alignment requirements associated with the sname:VkBuffer's pname:usage: 5975 ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT 5976 or ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:alignment 5977 must: be an integer multiple of 5978 sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment. 5979 ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, 5980 pname:alignment must: be an integer multiple of 5981 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment. 5982 ** If pname:usage included ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, 5983 pname:alignment must: be an integer multiple of 5984 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment. 5985 * For images created with a color format, the pname:memoryTypeBits member 5986 is identical for all sname:VkImage objects created with the same 5987 combination of values for the pname:tiling member, the 5988 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the pname:flags member, 5989ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 5990 the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the 5991 pname:flags member, 5992endif::VK_VERSION_1_1,VK_KHR_device_group[] 5993ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 5994 pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, 5995endif::VK_VERSION_1_1,VK_KHR_external_memory[] 5996 and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage 5997 member in the slink:VkImageCreateInfo structure passed to 5998 flink:vkCreateImage. 5999 * For images created with a depth/stencil format, the pname:memoryTypeBits 6000 member is identical for all sname:VkImage objects created with the same 6001 combination of values for the pname:format member, the pname:tiling 6002 member, the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the 6003 pname:flags member, 6004ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6005 the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the 6006 pname:flags member, 6007endif::VK_VERSION_1_1,VK_KHR_device_group[] 6008ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6009 pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, 6010endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6011 and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage 6012 member in the slink:VkImageCreateInfo structure passed to 6013 flink:vkCreateImage. 6014 * If the memory requirements are for a sname:VkImage, the 6015 pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with 6016 a pname:propertyFlags that has the 6017 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set if the pname:image 6018 did not have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in 6019 the pname:usage member of the slink:VkImageCreateInfo structure passed 6020 to flink:vkCreateImage. 6021 * If the memory requirements are for a sname:VkBuffer, the 6022 pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with 6023 a pname:propertyFlags that has the 6024 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set. 6025+ 6026[NOTE] 6027.Note 6028==== 6029The implication of this requirement is that lazily allocated memory is 6030disallowed for buffers in all cases. 6031==== 6032 * The pname:size member is identical for all sname:VkBuffer objects 6033 created with the same combination of creation parameters specified in 6034 slink:VkBufferCreateInfo and its pname:pNext chain. 6035 * The pname:size member is identical for all sname:VkImage objects created 6036 with the same combination of creation parameters specified in 6037 slink:VkImageCreateInfo and its pname:pNext chain. 6038+ 6039[NOTE] 6040.Note 6041==== 6042This, however, does not imply that they interpret the contents of the bound 6043memory identically with each other. 6044ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6045That additional guarantee, however, can: be explicitly requested using 6046ename:VK_IMAGE_CREATE_ALIAS_BIT. 6047endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6048==== 6049ifdef::VK_KHR_maintenance4[] 6050 * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, 6051 these additional guarantees apply: 6052 ** For a sname:VkBuffer, the pname:size memory requirement is never 6053 greater than that of another sname:VkBuffer created with a greater or 6054 equal pname:size specified in slink:VkBufferCreateInfo, all other 6055 creation parameters being identical. 6056 ** For a sname:VkBuffer, the pname:size memory requirement is never 6057 greater than the result of aligning 6058 slink:VkBufferCreateInfo::pname:size with the pname:alignment memory 6059 requirement. 6060 ** For a slink:VkImage, the pname:size memory requirement is never greater 6061 than that of another slink:VkImage created with a greater or equal 6062 value in each of pname:extent.width, pname:extent.height, and 6063 pname:extent.depth; all other creation parameters being identical. 6064 ** The memory requirements returned by 6065 flink:vkGetDeviceBufferMemoryRequirementsKHR are identical to those 6066 that would be returned by flink:vkGetBufferMemoryRequirements2 if it 6067 were called with a sname:VkBuffer created with the same 6068 slink:VkBufferCreateInfo values. 6069 ** The memory requirements returned by 6070 flink:vkGetDeviceImageMemoryRequirementsKHR are identical to those that 6071 would be returned by flink:vkGetImageMemoryRequirements2 if it were 6072 called with a sname:VkImage created with the same 6073 slink:VkImageCreateInfo values. 6074endif::VK_KHR_maintenance4[] 6075 6076ifdef::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 6077[open,refpage='vkGetBufferMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 6078-- 6079To determine the memory requirements for a buffer resource, call: 6080 6081ifdef::VK_VERSION_1_1[] 6082include::{generated}/api/protos/vkGetBufferMemoryRequirements2.txt[] 6083endif::VK_VERSION_1_1[] 6084 6085ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] 6086 6087ifdef::VK_KHR_get_memory_requirements2[] 6088include::{generated}/api/protos/vkGetBufferMemoryRequirements2KHR.txt[] 6089endif::VK_KHR_get_memory_requirements2[] 6090 6091 * pname:device is the logical device that owns the buffer. 6092 * pname:pInfo is a pointer to a slink:VkBufferMemoryRequirementsInfo2 6093 structure containing parameters required for the memory requirements 6094 query. 6095 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 6096 structure in which the memory requirements of the buffer object are 6097 returned. 6098 6099include::{generated}/validity/protos/vkGetBufferMemoryRequirements2.txt[] 6100-- 6101 6102ifdef::VK_KHR_maintenance4[] 6103[open,refpage='vkGetDeviceBufferMemoryRequirementsKHR',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 6104-- 6105To determine the memory requirements for a buffer resource without creating 6106an object, call: 6107 6108include::{generated}/api/protos/vkGetDeviceBufferMemoryRequirementsKHR.txt[] 6109 6110 * pname:device is the logical device intended to own the buffer. 6111 * pname:pInfo is a pointer to a slink:VkDeviceBufferMemoryRequirementsKHR 6112 structure containing parameters required for the memory requirements 6113 query. 6114 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 6115 structure in which the memory requirements of the buffer object are 6116 returned. 6117 6118include::{generated}/validity/protos/vkGetDeviceBufferMemoryRequirementsKHR.txt[] 6119-- 6120endif::VK_KHR_maintenance4[] 6121 6122[open,refpage='VkBufferMemoryRequirementsInfo2',desc='(None)',type='structs'] 6123-- 6124The sname:VkBufferMemoryRequirementsInfo2 structure is defined as: 6125 6126include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2.txt[] 6127 6128ifdef::VK_KHR_get_memory_requirements2[] 6129or the equivalent 6130 6131include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2KHR.txt[] 6132endif::VK_KHR_get_memory_requirements2[] 6133 6134 * pname:sType is the type of this structure. 6135 * pname:pNext is `NULL` or a pointer to a structure extending this 6136 structure. 6137 * pname:buffer is the buffer to query. 6138 6139include::{generated}/validity/structs/VkBufferMemoryRequirementsInfo2.txt[] 6140-- 6141 6142ifdef::VK_KHR_maintenance4[] 6143[open,refpage='VkDeviceBufferMemoryRequirementsKHR',desc='(None)',type='structs'] 6144-- 6145The sname:VkDeviceBufferMemoryRequirementsKHR structure is defined as: 6146 6147include::{generated}/api/structs/VkDeviceBufferMemoryRequirementsKHR.txt[] 6148 6149 * pname:sType is the type of this structure. 6150 * pname:pNext is `NULL` or a pointer to a structure extending this 6151 structure. 6152 * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure 6153 containing parameters affecting creation of the buffer to query. 6154 6155include::{generated}/validity/structs/VkDeviceBufferMemoryRequirementsKHR.txt[] 6156-- 6157endif::VK_KHR_maintenance4[] 6158 6159[open,refpage='vkGetImageMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 6160-- 6161To determine the memory requirements for an image resource, call: 6162 6163ifdef::VK_VERSION_1_1[] 6164include::{generated}/api/protos/vkGetImageMemoryRequirements2.txt[] 6165endif::VK_VERSION_1_1[] 6166 6167ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] 6168 6169ifdef::VK_KHR_get_memory_requirements2[] 6170include::{generated}/api/protos/vkGetImageMemoryRequirements2KHR.txt[] 6171endif::VK_KHR_get_memory_requirements2[] 6172 6173 * pname:device is the logical device that owns the image. 6174 * pname:pInfo is a pointer to a slink:VkImageMemoryRequirementsInfo2 6175 structure containing parameters required for the memory requirements 6176 query. 6177 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 6178 structure in which the memory requirements of the image object are 6179 returned. 6180 6181include::{generated}/validity/protos/vkGetImageMemoryRequirements2.txt[] 6182-- 6183 6184ifdef::VK_KHR_maintenance4[] 6185[open,refpage='vkGetDeviceImageMemoryRequirementsKHR',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 6186-- 6187To determine the memory requirements for an image resource without creating 6188an object, call: 6189 6190include::{generated}/api/protos/vkGetDeviceImageMemoryRequirementsKHR.txt[] 6191 6192 * pname:device is the logical device intended to own the image. 6193 * pname:pInfo is a pointer to a slink:VkDeviceImageMemoryRequirementsKHR 6194 structure containing parameters required for the memory requirements 6195 query. 6196 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 6197 structure in which the memory requirements of the image object are 6198 returned. 6199 6200include::{generated}/validity/protos/vkGetDeviceImageMemoryRequirementsKHR.txt[] 6201-- 6202endif::VK_KHR_maintenance4[] 6203 6204[open,refpage='VkImageMemoryRequirementsInfo2',desc='(None)',type='structs'] 6205-- 6206The sname:VkImageMemoryRequirementsInfo2 structure is defined as: 6207 6208include::{generated}/api/structs/VkImageMemoryRequirementsInfo2.txt[] 6209 6210ifdef::VK_KHR_get_memory_requirements2[] 6211or the equivalent 6212 6213include::{generated}/api/structs/VkImageMemoryRequirementsInfo2KHR.txt[] 6214endif::VK_KHR_get_memory_requirements2[] 6215 6216 * pname:sType is the type of this structure. 6217 * pname:pNext is `NULL` or a pointer to a structure extending this 6218 structure. 6219 * pname:image is the image to query. 6220 6221ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6222 6223.Valid Usage 6224**** 6225 * [[VUID-VkImageMemoryRequirementsInfo2-image-01589]] 6226 If pname:image was created with a _multi-planar_ format and the 6227 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: be a 6228 slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 6229 chain of the slink:VkImageMemoryRequirementsInfo2 structure 6230ifdef::VK_EXT_image_drm_format_modifier[] 6231 * [[VUID-VkImageMemoryRequirementsInfo2-image-02279]] 6232 If pname:image was created with ename:VK_IMAGE_CREATE_DISJOINT_BIT and 6233 with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then there must: be 6234 a slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 6235 chain of the slink:VkImageMemoryRequirementsInfo2 structure 6236endif::VK_EXT_image_drm_format_modifier[] 6237 * [[VUID-VkImageMemoryRequirementsInfo2-image-01590]] 6238 If pname:image was not created with the 6239 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: not be a 6240 slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 6241 chain of the slink:VkImageMemoryRequirementsInfo2 structure 6242ifndef::VK_EXT_image_drm_format_modifier[] 6243 * [[VUID-VkImageMemoryRequirementsInfo2-image-01591]] 6244 If pname:image was created with a single-plane format, there must: not 6245 be a slink:VkImagePlaneMemoryRequirementsInfo included in the 6246 pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure 6247endif::VK_EXT_image_drm_format_modifier[] 6248ifdef::VK_EXT_image_drm_format_modifier[] 6249 * [[VUID-VkImageMemoryRequirementsInfo2-image-02280]] 6250 If pname:image was created with a single-plane format and with any 6251 pname:tiling other than ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 6252 then there must: not be a slink:VkImagePlaneMemoryRequirementsInfo 6253 included in the pname:pNext chain of the 6254 slink:VkImageMemoryRequirementsInfo2 structure 6255endif::VK_EXT_image_drm_format_modifier[] 6256ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 6257 * [[VUID-VkImageMemoryRequirementsInfo2-image-01897]] 6258 If pname:image was created with the 6259 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 6260 external memory handle type, then pname:image must: be bound to memory 6261endif::VK_ANDROID_external_memory_android_hardware_buffer[] 6262**** 6263 6264endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6265 6266include::{generated}/validity/structs/VkImageMemoryRequirementsInfo2.txt[] 6267-- 6268 6269ifdef::VK_KHR_maintenance4[] 6270[open,refpage='VkDeviceImageMemoryRequirementsKHR',desc='(None)',type='structs'] 6271-- 6272The sname:VkDeviceImageMemoryRequirementsKHR structure is defined as: 6273 6274include::{generated}/api/structs/VkDeviceImageMemoryRequirementsKHR.txt[] 6275 6276 * pname:sType is the type of this structure. 6277 * pname:pNext is `NULL` or a pointer to a structure extending this 6278 structure. 6279 * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure 6280 containing parameters affecting creation of the image to query. 6281 * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the 6282 aspect corresponding to the image plane to query. 6283 This parameter is ignored unless pname:pCreateInfo::pname:flags has 6284 ename:VK_IMAGE_CREATE_DISJOINT_BIT 6285ifdef::VK_EXT_image_drm_format_modifier[] 6286 or ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 6287endif::VK_EXT_image_drm_format_modifier[] 6288 set. 6289 6290.Valid Usage 6291**** 6292 * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06416]] 6293 The pname:pCreateInfo::pname:pNext chain must: not contain a 6294 slink:VkImageSwapchainCreateInfoKHR structure 6295 * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06417]] 6296 If pname:pCreateInfo::pname:flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT 6297 set then pname:planAspect must: not be zero 6298ifdef::VK_EXT_image_drm_format_modifier[] 6299 * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06418]] 6300 If pname:pCreateInfo::pname:flags has 6301 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT set then pname:planAspect 6302 must: not be zero 6303endif::VK_EXT_image_drm_format_modifier[] 6304 * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06419]] 6305 If pname:pCreateInfo::pname:flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT 6306 set and if the pname:pCreateInfo::pname:tiling is 6307 ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_OPTIMAL, then 6308 pname:planeAspect must: be a single valid _format plane_ for the image 6309 (that is, for a two-plane image pname:planeAspect must: be 6310 ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT, 6311 and for a three-plane image pname:planeAspect must: be 6312 ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or 6313 ename:VK_IMAGE_ASPECT_PLANE_2_BIT) 6314ifdef::VK_EXT_image_drm_format_modifier[] 6315 * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06420]] 6316 If pname:pCreateInfo::pname:flags has 6317 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT set and the 6318 pname:pCreateInfo::pname:tiling is 6319 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 6320 must: be a single valid _memory plane_ for the image (that is, 6321 pname:aspectMask must: specify a plane index that is less than the 6322 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 6323 associated with the image's pname:format and 6324 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 6325endif::VK_EXT_image_drm_format_modifier[] 6326**** 6327 6328include::{generated}/validity/structs/VkDeviceImageMemoryRequirementsKHR.txt[] 6329-- 6330endif::VK_KHR_maintenance4[] 6331 6332ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6333[open,refpage='VkImagePlaneMemoryRequirementsInfo',desc='Structure specifying image plane for memory requirements',type='structs'] 6334-- 6335To determine the memory requirements for a plane of a disjoint image, add a 6336sname:VkImagePlaneMemoryRequirementsInfo structure to the pname:pNext chain 6337of the sname:VkImageMemoryRequirementsInfo2 structure. 6338 6339The sname:VkImagePlaneMemoryRequirementsInfo structure is defined as: 6340 6341include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfo.txt[] 6342 6343ifdef::VK_KHR_sampler_ycbcr_conversion[] 6344or the equivalent 6345 6346include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfoKHR.txt[] 6347endif::VK_KHR_sampler_ycbcr_conversion[] 6348 6349 * pname:sType is the type of this structure. 6350 * pname:pNext is `NULL` or a pointer to a structure extending this 6351 structure. 6352 * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the 6353 aspect corresponding to the image plane to query. 6354 6355.Valid Usage 6356**** 6357 * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02281]] 6358 If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or 6359 ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single 6360 valid _format plane_ for the image (that is, for a two-plane image 6361 pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or 6362 ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image 6363 pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 6364 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) 6365ifdef::VK_EXT_image_drm_format_modifier[] 6366 * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02282]] 6367 If the image's pname:tiling is 6368 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 6369 must: be a single valid _memory plane_ for the image (that is, 6370 pname:aspectMask must: specify a plane index that is less than the 6371 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 6372 associated with the image's pname:format and 6373 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 6374endif::VK_EXT_image_drm_format_modifier[] 6375**** 6376 6377include::{generated}/validity/structs/VkImagePlaneMemoryRequirementsInfo.txt[] 6378-- 6379endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6380 6381[open,refpage='VkMemoryRequirements2',desc='Structure specifying memory requirements',type='structs'] 6382-- 6383The sname:VkMemoryRequirements2 structure is defined as: 6384 6385include::{generated}/api/structs/VkMemoryRequirements2.txt[] 6386 6387ifdef::VK_KHR_get_memory_requirements2[] 6388or the equivalent 6389 6390include::{generated}/api/structs/VkMemoryRequirements2KHR.txt[] 6391endif::VK_KHR_get_memory_requirements2[] 6392 6393 * pname:sType is the type of this structure. 6394 * pname:pNext is `NULL` or a pointer to a structure extending this 6395 structure. 6396 * pname:memoryRequirements is a slink:VkMemoryRequirements structure 6397 describing the memory requirements of the resource. 6398 6399include::{generated}/validity/structs/VkMemoryRequirements2.txt[] 6400-- 6401endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 6402 6403ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 6404[open,refpage='VkMemoryDedicatedRequirements',desc='Structure describing dedicated allocation requirements of buffer and image resources',type='structs'] 6405-- 6406The sname:VkMemoryDedicatedRequirements structure is defined as: 6407 6408include::{generated}/api/structs/VkMemoryDedicatedRequirements.txt[] 6409 6410ifdef::VK_KHR_dedicated_allocation[] 6411or the equivalent 6412 6413include::{generated}/api/structs/VkMemoryDedicatedRequirementsKHR.txt[] 6414endif::VK_KHR_dedicated_allocation[] 6415 6416 * pname:sType is the type of this structure. 6417 * pname:pNext is `NULL` or a pointer to a structure extending this 6418 structure. 6419 * pname:prefersDedicatedAllocation specifies that the implementation would 6420 prefer a dedicated allocation for this resource. 6421 The application is still free to suballocate the resource but it may: 6422 get better performance if a dedicated allocation is used. 6423 * pname:requiresDedicatedAllocation specifies that a dedicated allocation 6424 is required for this resource. 6425 6426To determine the dedicated allocation requirements of a buffer or image 6427resource, add a slink:VkMemoryDedicatedRequirements structure to the 6428pname:pNext chain of the slink:VkMemoryRequirements2 structure passed as the 6429pname:pMemoryRequirements parameter of flink:vkGetBufferMemoryRequirements2 6430or flink:vkGetImageMemoryRequirements2, respectively. 6431 6432Constraints on the values returned for buffer resources are: 6433 6434ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6435 * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the 6436 pname:pNext chain of slink:VkBufferCreateInfo for the call to 6437 fname:vkCreateBuffer used to create the buffer being queried included a 6438 slink:VkExternalMemoryBufferCreateInfo structure, and any of the handle 6439 types specified in 6440 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes requires 6441 dedicated allocation, as reported by 6442 flink:vkGetPhysicalDeviceExternalBufferProperties in 6443 sname:VkExternalBufferProperties::pname:externalMemoryProperties.externalMemoryFeatures. 6444 Otherwise, pname:requiresDedicatedAllocation will be ename:VK_FALSE. 6445 6446endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6447ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 6448 * pname:requiresDedicatedAllocation will be ename:VK_FALSE 6449endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6450 * When the implementation sets pname:requiresDedicatedAllocation to 6451 ename:VK_TRUE, it must: also set pname:prefersDedicatedAllocation to 6452 ename:VK_TRUE. 6453 * If ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in 6454 slink:VkBufferCreateInfo::pname:flags when pname:buffer was created, 6455 then both pname:prefersDedicatedAllocation and 6456 pname:requiresDedicatedAllocation will be ename:VK_FALSE. 6457 6458Constraints on the values returned for image resources are: 6459 6460ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 6461 * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the 6462 pname:pNext chain of slink:VkImageCreateInfo for the call to 6463 flink:vkCreateImage used to create the image being queried included a 6464 slink:VkExternalMemoryImageCreateInfo structure, and any of the handle 6465 types specified in 6466 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes requires 6467 dedicated allocation, as reported by 6468 flink:vkGetPhysicalDeviceImageFormatProperties2 in 6469 sname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures. 6470 Otherwise, pname:requiresDedicatedAllocation will be ename:VK_FALSE. 6471endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6472ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 6473 * pname:requiresDedicatedAllocation will be ename:VK_FALSE 6474endif::VK_VERSION_1_1,VK_KHR_external_memory[] 6475 * If ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in 6476 slink:VkImageCreateInfo::pname:flags when pname:image was created, then 6477 both pname:prefersDedicatedAllocation and 6478 pname:requiresDedicatedAllocation will be ename:VK_FALSE. 6479 6480include::{generated}/validity/structs/VkMemoryDedicatedRequirements.txt[] 6481-- 6482endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 6483 6484[open,refpage='vkBindBufferMemory',desc='Bind device memory to a buffer object',type='protos'] 6485-- 6486:refpage: vkBindBufferMemory 6487 6488To attach memory to a buffer object, call: 6489 6490include::{generated}/api/protos/vkBindBufferMemory.txt[] 6491 6492 * pname:device is the logical device that owns the buffer and memory. 6493 * pname:buffer is the buffer to be attached to memory. 6494 * pname:memory is a slink:VkDeviceMemory object describing the device 6495 memory to attach. 6496 * pname:memoryOffset is the start offset of the region of pname:memory 6497 which is to be bound to the buffer. 6498 The number of bytes returned in the 6499 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 6500 from pname:memoryOffset bytes, will be bound to the specified buffer. 6501 6502ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6503fname:vkBindBufferMemory is equivalent to passing the same parameters 6504through slink:VkBindBufferMemoryInfo to flink:vkBindBufferMemory2. 6505endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6506 6507.Valid Usage 6508**** 6509include::{chapters}/commonvalidity/bind_buffer_common.txt[] 6510**** 6511 6512include::{generated}/validity/protos/vkBindBufferMemory.txt[] 6513-- 6514 6515ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6516[open,refpage='vkBindBufferMemory2',desc='Bind device memory to buffer objects',type='protos'] 6517-- 6518To attach memory to buffer objects for one or more buffers at a time, call: 6519 6520ifdef::VK_VERSION_1_1[] 6521include::{generated}/api/protos/vkBindBufferMemory2.txt[] 6522endif::VK_VERSION_1_1[] 6523 6524ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] 6525 6526ifdef::VK_KHR_bind_memory2[] 6527include::{generated}/api/protos/vkBindBufferMemory2KHR.txt[] 6528endif::VK_KHR_bind_memory2[] 6529 6530 * pname:device is the logical device that owns the buffers and memory. 6531 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 6532 * pname:pBindInfos is a pointer to an array of pname:bindInfoCount 6533 slink:VkBindBufferMemoryInfo structures describing buffers and memory to 6534 bind. 6535 6536On some implementations, it may: be more efficient to batch memory bindings 6537into a single command. 6538 6539include::{generated}/validity/protos/vkBindBufferMemory2.txt[] 6540-- 6541 6542[open,refpage='VkBindBufferMemoryInfo',desc='Structure specifying how to bind a buffer to memory',type='structs'] 6543-- 6544:refpage: VkBindBufferMemoryInfo 6545 6546sname:VkBindBufferMemoryInfo contains members corresponding to the 6547parameters of flink:vkBindBufferMemory. 6548 6549The sname:VkBindBufferMemoryInfo structure is defined as: 6550 6551include::{generated}/api/structs/VkBindBufferMemoryInfo.txt[] 6552 6553ifdef::VK_KHR_bind_memory2[] 6554or the equivalent 6555 6556include::{generated}/api/structs/VkBindBufferMemoryInfoKHR.txt[] 6557endif::VK_KHR_bind_memory2[] 6558 6559 * pname:sType is the type of this structure. 6560 * pname:pNext is `NULL` or a pointer to a structure extending this 6561 structure. 6562 * pname:buffer is the buffer to be attached to memory. 6563 * pname:memory is a slink:VkDeviceMemory object describing the device 6564 memory to attach. 6565 * pname:memoryOffset is the start offset of the region of pname:memory 6566 which is to be bound to the buffer. 6567 The number of bytes returned in the 6568 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 6569 from pname:memoryOffset bytes, will be bound to the specified buffer. 6570 6571.Valid Usage 6572**** 6573include::{chapters}/commonvalidity/bind_buffer_common.txt[] 6574ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6575 * [[VUID-VkBindBufferMemoryInfo-pNext-01605]] 6576 If the pname:pNext chain includes a 6577 slink:VkBindBufferMemoryDeviceGroupInfo structure, all instances of 6578 pname:memory specified by 6579 slink:VkBindBufferMemoryDeviceGroupInfo::pname:pDeviceIndices must: have 6580 been allocated 6581endif::VK_VERSION_1_1,VK_KHR_device_group[] 6582**** 6583 6584include::{generated}/validity/structs/VkBindBufferMemoryInfo.txt[] 6585-- 6586 6587ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6588[open,refpage='VkBindBufferMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] 6589-- 6590The sname:VkBindBufferMemoryDeviceGroupInfo structure is defined as: 6591 6592include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfo.txt[] 6593 6594// Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2 6595ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[] 6596or the equivalent 6597 6598include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfoKHR.txt[] 6599endif::VK_KHR_device_group+VK_KHR_bind_memory2[] 6600 6601 * pname:sType is the type of this structure. 6602 * pname:pNext is `NULL` or a pointer to a structure extending this 6603 structure. 6604 * pname:deviceIndexCount is the number of elements in 6605 pname:pDeviceIndices. 6606 * pname:pDeviceIndices is a pointer to an array of device indices. 6607 6608If the pname:pNext chain of slink:VkBindBufferMemoryInfo includes a 6609sname:VkBindBufferMemoryDeviceGroupInfo structure, then that structure 6610determines how memory is bound to buffers across multiple devices in a 6611device group. 6612 6613If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# 6614the buffer is attached to the instance of pname:memory on the physical 6615device with device index [eq]#pname:pDeviceIndices[i]#. 6616 6617If pname:deviceIndexCount is zero and pname:memory comes from a memory heap 6618with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 6619pname:pDeviceIndices contains consecutive indices from zero to the number of 6620physical devices in the logical device, minus one. 6621In other words, by default each physical device attaches to its own instance 6622of pname:memory. 6623 6624If pname:deviceIndexCount is zero and pname:memory comes from a memory heap 6625without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as 6626if pname:pDeviceIndices contains an array of zeros. 6627In other words, by default each physical device attaches to instance zero. 6628 6629.Valid Usage 6630**** 6631 * [[VUID-VkBindBufferMemoryDeviceGroupInfo-deviceIndexCount-01606]] 6632 pname:deviceIndexCount must: either be zero or equal to the number of 6633 physical devices in the logical device 6634 * [[VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-01607]] 6635 All elements of pname:pDeviceIndices must: be valid device indices 6636**** 6637 6638include::{generated}/validity/structs/VkBindBufferMemoryDeviceGroupInfo.txt[] 6639-- 6640endif::VK_VERSION_1_1,VK_KHR_device_group[] 6641endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6642 6643[open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos'] 6644-- 6645:refpage: vkBindImageMemory 6646 6647ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6648To attach memory to an image object, call: 6649endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6650ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6651To attach memory to a sname:VkImage object created without the 6652ename:VK_IMAGE_CREATE_DISJOINT_BIT set, call: 6653endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6654 6655include::{generated}/api/protos/vkBindImageMemory.txt[] 6656 6657 * pname:device is the logical device that owns the image and memory. 6658 * pname:image is the image. 6659 * pname:memory is the slink:VkDeviceMemory object describing the device 6660 memory to attach. 6661 * pname:memoryOffset is the start offset of the region of pname:memory 6662 which is to be bound to the image. 6663 The number of bytes returned in the 6664 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 6665 from pname:memoryOffset bytes, will be bound to the specified image. 6666 6667ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6668fname:vkBindImageMemory is equivalent to passing the same parameters through 6669slink:VkBindImageMemoryInfo to flink:vkBindImageMemory2. 6670endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6671 6672.Valid Usage 6673**** 6674include::{chapters}/commonvalidity/bind_image_common.txt[] 6675ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6676 * [[VUID-vkBindImageMemory-image-01608]] 6677 pname:image must: not have been created with the 6678 ename:VK_IMAGE_CREATE_DISJOINT_BIT set 6679endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6680 * [[VUID-vkBindImageMemory-memory-01047]] 6681 pname:memory must: have been allocated using one of the memory types 6682 allowed in the pname:memoryTypeBits member of the 6683 sname:VkMemoryRequirements structure returned from a call to 6684 flink:vkGetImageMemoryRequirements with pname:image 6685 * [[VUID-vkBindImageMemory-memoryOffset-01048]] 6686 pname:memoryOffset must: be an integer multiple of the pname:alignment 6687 member of the sname:VkMemoryRequirements structure returned from a call 6688 to flink:vkGetImageMemoryRequirements with pname:image 6689 * [[VUID-vkBindImageMemory-size-01049]] 6690 The difference of the size of pname:memory and pname:memoryOffset must: 6691 be greater than or equal to the pname:size member of the 6692 slink:VkMemoryRequirements structure returned from a call to 6693 flink:vkGetImageMemoryRequirements with the same pname:image 6694ifdef::VK_FUCHSIA_buffer_collection[] 6695 * [[VUID-vkBindImageMemory-image-06392]] 6696 If pname:image was created with 6697 slink:VkBufferCollectionImageCreateInfoFUCHSIA chained to 6698 slink:VkImageCreateInfo::pname:pNext, pname:memory must: be allocated 6699 with a slink:VkImportMemoryBufferCollectionFUCHSIA chained to 6700 slink:VkMemoryAllocateInfo::pname:pNext 6701endif::VK_FUCHSIA_buffer_collection[] 6702**** 6703 6704include::{generated}/validity/protos/vkBindImageMemory.txt[] 6705-- 6706 6707ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 6708[open,refpage='vkBindImageMemory2',desc='Bind device memory to image objects',type='protos'] 6709-- 6710To attach memory to image objects for one or more images at a time, call: 6711 6712ifdef::VK_VERSION_1_1[] 6713include::{generated}/api/protos/vkBindImageMemory2.txt[] 6714endif::VK_VERSION_1_1[] 6715 6716ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] 6717 6718ifdef::VK_KHR_bind_memory2[] 6719include::{generated}/api/protos/vkBindImageMemory2KHR.txt[] 6720endif::VK_KHR_bind_memory2[] 6721 6722 * pname:device is the logical device that owns the images and memory. 6723 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 6724 * pname:pBindInfos is a pointer to an array of slink:VkBindImageMemoryInfo 6725 structures, describing images and memory to bind. 6726 6727On some implementations, it may: be more efficient to batch memory bindings 6728into a single command. 6729 6730.Valid Usage 6731**** 6732ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6733 * [[VUID-vkBindImageMemory2-pBindInfos-02858]] 6734 If any slink:VkBindImageMemoryInfo::pname:image was created with 6735 ename:VK_IMAGE_CREATE_DISJOINT_BIT then all planes of 6736 slink:VkBindImageMemoryInfo::pname:image must: be bound individually in 6737 separate pname:pBindInfos 6738 * [[VUID-vkBindImageMemory2-pBindInfos-04006]] 6739 pname:pBindInfos must: not refer to the same image subresource more than 6740 once 6741endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6742**** 6743 6744include::{generated}/validity/protos/vkBindImageMemory2.txt[] 6745-- 6746 6747[open,refpage='VkBindImageMemoryInfo',desc='Structure specifying how to bind an image to memory',type='structs'] 6748-- 6749:refpage: VkBindImageMemoryInfo 6750 6751sname:VkBindImageMemoryInfo contains members corresponding to the parameters 6752of flink:vkBindImageMemory. 6753 6754The sname:VkBindImageMemoryInfo structure is defined as: 6755 6756include::{generated}/api/structs/VkBindImageMemoryInfo.txt[] 6757 6758ifdef::VK_KHR_bind_memory2[] 6759or the equivalent 6760 6761include::{generated}/api/structs/VkBindImageMemoryInfoKHR.txt[] 6762endif::VK_KHR_bind_memory2[] 6763 6764 * pname:sType is the type of this structure. 6765 * pname:pNext is `NULL` or a pointer to a structure extending this 6766 structure. 6767 * pname:image is the image to be attached to memory. 6768 * pname:memory is a slink:VkDeviceMemory object describing the device 6769 memory to attach. 6770 * pname:memoryOffset is the start offset of the region of pname:memory 6771 which is to be bound to the image. 6772 The number of bytes returned in the 6773 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 6774 from pname:memoryOffset bytes, will be bound to the specified image. 6775 6776.Valid Usage 6777**** 6778include::{chapters}/commonvalidity/bind_image_common.txt[] 6779ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6780 * [[VUID-VkBindImageMemoryInfo-memory-01612]] 6781 pname:memory must: have been allocated using one of the memory types 6782 allowed in the pname:memoryTypeBits member of the 6783 slink:VkMemoryRequirements structure returned from a call to 6784 flink:vkGetImageMemoryRequirements with pname:image 6785 * [[VUID-VkBindImageMemoryInfo-memoryOffset-01613]] 6786 pname:memoryOffset must: be an integer multiple of the pname:alignment 6787 member of the slink:VkMemoryRequirements structure returned from a call 6788 to flink:vkGetImageMemoryRequirements with pname:image 6789 * [[VUID-VkBindImageMemoryInfo-memory-01614]] 6790 The difference of the size of pname:memory and pname:memoryOffset must: 6791 be greater than or equal to the pname:size member of the 6792 slink:VkMemoryRequirements structure returned from a call to 6793 flink:vkGetImageMemoryRequirements with the same pname:image 6794endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6795ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6796 * [[VUID-VkBindImageMemoryInfo-pNext-01615]] 6797 If the pname:pNext chain does not include a 6798 slink:VkBindImagePlaneMemoryInfo structure, pname:memory must: have been 6799 allocated using one of the memory types allowed in the 6800 pname:memoryTypeBits member of the slink:VkMemoryRequirements structure 6801 returned from a call to flink:vkGetImageMemoryRequirements2 with 6802 pname:image 6803 * [[VUID-VkBindImageMemoryInfo-pNext-01616]] 6804 If the pname:pNext chain does not include a 6805 slink:VkBindImagePlaneMemoryInfo structure, pname:memoryOffset must: be 6806 an integer multiple of the pname:alignment member of the 6807 slink:VkMemoryRequirements structure returned from a call to 6808 flink:vkGetImageMemoryRequirements2 with pname:image 6809 * [[VUID-VkBindImageMemoryInfo-pNext-01617]] 6810 If the pname:pNext chain does not include a 6811 slink:VkBindImagePlaneMemoryInfo structure, the difference of the size 6812 of pname:memory and pname:memoryOffset must: be greater than or equal to 6813 the pname:size member of the slink:VkMemoryRequirements structure 6814 returned from a call to flink:vkGetImageMemoryRequirements2 with the 6815 same pname:image 6816 * [[VUID-VkBindImageMemoryInfo-pNext-01618]] 6817 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 6818 structure, pname:image must: have been created with the 6819 ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set 6820 * [[VUID-VkBindImageMemoryInfo-pNext-01619]] 6821 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 6822 structure, pname:memory must: have been allocated using one of the 6823 memory types allowed in the pname:memoryTypeBits member of the 6824 slink:VkMemoryRequirements structure returned from a call to 6825 flink:vkGetImageMemoryRequirements2 with pname:image and where 6826 slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the 6827 slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 6828 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 6829 * [[VUID-VkBindImageMemoryInfo-pNext-01620]] 6830 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 6831 structure, pname:memoryOffset must: be an integer multiple of the 6832 pname:alignment member of the slink:VkMemoryRequirements structure 6833 returned from a call to flink:vkGetImageMemoryRequirements2 with 6834 pname:image and where 6835 slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the 6836 slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 6837 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 6838 * [[VUID-VkBindImageMemoryInfo-pNext-01621]] 6839 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 6840 structure, the difference of the size of pname:memory and 6841 pname:memoryOffset must: be greater than or equal to the pname:size 6842 member of the slink:VkMemoryRequirements structure returned from a call 6843 to flink:vkGetImageMemoryRequirements2 with the same pname:image and 6844 where slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to 6845 the slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 6846 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 6847endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 6848ifndef::VK_VERSION_1_1+VK_KHR_swapchain[] 6849ifndef::VK_KHR_device_group+VK_KHR_swapchain[] 6850 * [[VUID-VkBindImageMemoryInfo-memory-01625]] 6851 pname:memory must: be a valid slink:VkDeviceMemory handle 6852endif::VK_KHR_device_group+VK_KHR_swapchain[] 6853endif::VK_VERSION_1_1+VK_KHR_swapchain[] 6854ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6855 * [[VUID-VkBindImageMemoryInfo-pNext-01626]] 6856 If the pname:pNext chain includes a 6857 slink:VkBindImageMemoryDeviceGroupInfo structure, all instances of 6858 pname:memory specified by 6859 slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices must: have 6860 been allocated 6861 * [[VUID-VkBindImageMemoryInfo-pNext-01627]] 6862 If the pname:pNext chain includes a 6863 slink:VkBindImageMemoryDeviceGroupInfo structure, and 6864 slink:VkBindImageMemoryDeviceGroupInfo::pname:splitInstanceBindRegionCount 6865 is not zero, then pname:image must: have been created with the 6866 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set 6867 * [[VUID-VkBindImageMemoryInfo-pNext-01628]] 6868 If the pname:pNext chain includes a 6869 slink:VkBindImageMemoryDeviceGroupInfo structure, all elements of 6870 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions 6871 must: be valid rectangles contained within the dimensions of pname:image 6872 * [[VUID-VkBindImageMemoryInfo-pNext-01629]] 6873 If the pname:pNext chain includes a 6874 slink:VkBindImageMemoryDeviceGroupInfo structure, the union of the areas 6875 of all elements of 6876 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions 6877 that correspond to the same instance of pname:image must: cover the 6878 entire image 6879ifdef::VK_KHR_swapchain[] 6880 * [[VUID-VkBindImageMemoryInfo-image-01630]] 6881 If pname:image was created with a valid swapchain handle in 6882 slink:VkImageSwapchainCreateInfoKHR::pname:swapchain, then the 6883 pname:pNext chain must: include a 6884 slink:VkBindImageMemorySwapchainInfoKHR structure containing the same 6885 swapchain handle 6886 * [[VUID-VkBindImageMemoryInfo-pNext-01631]] 6887 If the pname:pNext chain includes a 6888 slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be 6889 dlink:VK_NULL_HANDLE 6890 * [[VUID-VkBindImageMemoryInfo-pNext-01632]] 6891 If the pname:pNext chain does not include a 6892 slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be 6893 a valid slink:VkDeviceMemory handle 6894endif::VK_KHR_swapchain[] 6895endif::VK_VERSION_1_1,VK_KHR_device_group[] 6896**** 6897 6898include::{generated}/validity/structs/VkBindImageMemoryInfo.txt[] 6899-- 6900 6901ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 6902[open,refpage='VkBindImageMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] 6903-- 6904The sname:VkBindImageMemoryDeviceGroupInfo structure is defined as: 6905 6906include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfo.txt[] 6907 6908// Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2 6909ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[] 6910or the equivalent 6911 6912include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfoKHR.txt[] 6913endif::VK_KHR_device_group+VK_KHR_bind_memory2[] 6914 6915 * pname:sType is the type of this structure. 6916 * pname:pNext is `NULL` or a pointer to a structure extending this 6917 structure. 6918 * pname:deviceIndexCount is the number of elements in 6919 pname:pDeviceIndices. 6920 * pname:pDeviceIndices is a pointer to an array of device indices. 6921 * pname:splitInstanceBindRegionCount is the number of elements in 6922 pname:pSplitInstanceBindRegions. 6923 * pname:pSplitInstanceBindRegions is a pointer to an array of 6924 slink:VkRect2D structures describing which regions of the image are 6925 attached to each instance of memory. 6926 6927If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a 6928sname:VkBindImageMemoryDeviceGroupInfo structure, then that structure 6929determines how memory is bound to images across multiple devices in a device 6930group. 6931 6932If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# 6933pname:image is attached to the instance of the memory on the physical device 6934with device index [eq]#pDeviceIndices[i]#. 6935 6936Let [eq]#N# be the number of physical devices in the logical device. 6937If pname:splitInstanceBindRegionCount is greater than zero, then 6938pname:pSplitInstanceBindRegions is a pointer to an array of [eq]#N^2^# 6939rectangles, where the image region specified by the rectangle at element 6940[eq]#i*N+j# in resource instance [eq]#i# is bound to the memory instance 6941[eq]#j#. 6942The blocks of the memory that are bound to each sparse image block region 6943use an offset in memory, relative to pname:memoryOffset, computed as if the 6944whole image was being bound to a contiguous range of memory. 6945In other words, horizontally adjacent image blocks use consecutive blocks of 6946memory, vertically adjacent image blocks are separated by the number of 6947bytes per block multiplied by the width in blocks of pname:image, and the 6948block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset. 6949 6950If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero 6951and the memory comes from a memory heap with the 6952ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 6953pname:pDeviceIndices contains consecutive indices from zero to the number of 6954physical devices in the logical device, minus one. 6955In other words, by default each physical device attaches to its own instance 6956of the memory. 6957 6958If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero 6959and the memory comes from a memory heap without the 6960ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 6961pname:pDeviceIndices contains an array of zeros. 6962In other words, by default each physical device attaches to instance zero. 6963 6964.Valid Usage 6965**** 6966 * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01633]] 6967 At least one of pname:deviceIndexCount and 6968 pname:splitInstanceBindRegionCount must: be zero 6969 * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01634]] 6970 pname:deviceIndexCount must: either be zero or equal to the number of 6971 physical devices in the logical device 6972 * [[VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-01635]] 6973 All elements of pname:pDeviceIndices must: be valid device indices 6974 * [[VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-01636]] 6975 pname:splitInstanceBindRegionCount must: either be zero or equal to the 6976 number of physical devices in the logical device squared 6977 * [[VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-01637]] 6978 Elements of pname:pSplitInstanceBindRegions that correspond to the same 6979 instance of an image must: not overlap 6980 * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01638]] 6981 The pname:offset.x member of any element of 6982 pname:pSplitInstanceBindRegions must: be a multiple of the sparse image 6983 block width 6984 (sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of 6985 all non-metadata aspects of the image 6986 * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01639]] 6987 The pname:offset.y member of any element of 6988 pname:pSplitInstanceBindRegions must: be a multiple of the sparse image 6989 block height 6990 (sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of 6991 all non-metadata aspects of the image 6992 * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01640]] 6993 The pname:extent.width member of any element of 6994 pname:pSplitInstanceBindRegions must: either be a multiple of the sparse 6995 image block width of all non-metadata aspects of the image, or else 6996 pname:extent.width {plus} pname:offset.x must: equal the width of the 6997 image subresource 6998 * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01641]] 6999 The pname:extent.height member of any element of 7000 pname:pSplitInstanceBindRegions must: either be a multiple of the sparse 7001 image block height of all non-metadata aspects of the image, or else 7002 pname:extent.height {plus} pname:offset.y must: equal the height of the 7003 image subresource 7004**** 7005 7006include::{generated}/validity/structs/VkBindImageMemoryDeviceGroupInfo.txt[] 7007-- 7008 7009ifdef::VK_KHR_swapchain[] 7010[open,refpage='VkBindImageMemorySwapchainInfoKHR',desc='Structure specifying swapchain image memory to bind to',type='structs'] 7011-- 7012If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a 7013sname:VkBindImageMemorySwapchainInfoKHR structure, then that structure 7014includes a swapchain handle and image index indicating that the image will 7015be bound to memory from that swapchain. 7016 7017The sname:VkBindImageMemorySwapchainInfoKHR structure is defined as: 7018 7019include::{generated}/api/structs/VkBindImageMemorySwapchainInfoKHR.txt[] 7020 7021 * pname:sType is the type of this structure. 7022 * pname:pNext is `NULL` or a pointer to a structure extending this 7023 structure. 7024 * pname:swapchain is dlink:VK_NULL_HANDLE or a swapchain handle. 7025 * pname:imageIndex is an image index within pname:swapchain. 7026 7027If pname:swapchain is not `NULL`, the pname:swapchain and pname:imageIndex 7028are used to determine the memory that the image is bound to, instead of 7029pname:memory and pname:memoryOffset. 7030 7031Memory can: be bound to a swapchain and use the pname:pDeviceIndices or 7032pname:pSplitInstanceBindRegions members of 7033slink:VkBindImageMemoryDeviceGroupInfo. 7034 7035.Valid Usage 7036**** 7037 * [[VUID-VkBindImageMemorySwapchainInfoKHR-imageIndex-01644]] 7038 pname:imageIndex must: be less than the number of images in 7039 pname:swapchain 7040**** 7041 7042include::{generated}/validity/structs/VkBindImageMemorySwapchainInfoKHR.txt[] 7043-- 7044endif::VK_KHR_swapchain[] 7045endif::VK_VERSION_1_1,VK_KHR_device_group[] 7046 7047ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 7048[open,refpage='VkBindImagePlaneMemoryInfo',desc='Structure specifying how to bind an image plane to memory',type='structs'] 7049-- 7050In order to bind _planes_ of a _disjoint image_, add a 7051sname:VkBindImagePlaneMemoryInfo structure to the pname:pNext chain of 7052slink:VkBindImageMemoryInfo. 7053 7054The sname:VkBindImagePlaneMemoryInfo structure is defined as: 7055 7056include::{generated}/api/structs/VkBindImagePlaneMemoryInfo.txt[] 7057 7058ifdef::VK_KHR_sampler_ycbcr_conversion[] 7059or the equivalent 7060 7061include::{generated}/api/structs/VkBindImagePlaneMemoryInfoKHR.txt[] 7062endif::VK_KHR_sampler_ycbcr_conversion[] 7063 7064 * pname:sType is the type of this structure. 7065 * pname:pNext is `NULL` or a pointer to a structure extending this 7066 structure. 7067 * pname:planeAspect is a ename:VkImageAspectFlagBits value specifying the 7068 aspect of the disjoint image plane to bind. 7069 7070.Valid Usage 7071**** 7072 * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02283]] 7073 If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or 7074 ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single 7075 valid _format plane_ for the image (that is, for a two-plane image 7076 pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or 7077 ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image 7078 pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 7079 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) 7080ifdef::VK_EXT_image_drm_format_modifier[] 7081 * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02284]] 7082 If the image's pname:tiling is 7083 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 7084 must: be a single valid _memory plane_ for the image (that is, 7085 pname:aspectMask must: specify a plane index that is less than the 7086 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 7087 associated with the image's pname:format and 7088 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 7089endif::VK_EXT_image_drm_format_modifier[] 7090**** 7091 7092include::{generated}/validity/structs/VkBindImagePlaneMemoryInfo.txt[] 7093-- 7094endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 7095endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 7096 7097 7098[[resources-bufferimagegranularity,Buffer-Image Granularity]] 7099.Buffer-Image Granularity 7100The implementation-dependent limit <<limits-bufferImageGranularity, 7101pname:bufferImageGranularity>> specifies a page-like granularity at which 7102linear and non-linear resources must: be placed in adjacent memory locations 7103to avoid aliasing. 7104Two resources which do not satisfy this granularity requirement are said to 7105<<resources-memory-aliasing,alias>>. 7106pname:bufferImageGranularity is specified in bytes, and must: be a power of 7107two. 7108Implementations which do not impose a granularity restriction may: report a 7109pname:bufferImageGranularity value of one. 7110 7111[NOTE] 7112.Note 7113==== 7114Despite its name, pname:bufferImageGranularity is really a granularity 7115between "`linear`" and "`non-linear`" resources. 7116==== 7117 7118Given resourceA at the lower memory offset and resourceB at the higher 7119memory offset in the same sname:VkDeviceMemory object, where one resource is 7120linear and the other is non-linear (as defined in the 7121<<glossary-linear-resource,Glossary>>), and the following: 7122 7123[source,c] 7124--------------------------------------------------- 7125resourceA.end = resourceA.memoryOffset + resourceA.size - 1 7126resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1) 7127resourceB.start = resourceB.memoryOffset 7128resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1) 7129--------------------------------------------------- 7130 7131The following property must: hold: 7132 7133[source,c] 7134--------------------------------------------------- 7135resourceA.endPage < resourceB.startPage 7136--------------------------------------------------- 7137 7138That is, the end of the first resource (A) and the beginning of the second 7139resource (B) must: be on separate "`pages`" of size 7140pname:bufferImageGranularity. 7141pname:bufferImageGranularity may: be different than the physical page size 7142of the memory heap. 7143This restriction is only needed when a linear resource and a non-linear 7144resource are adjacent in memory and will be used simultaneously. 7145The memory ranges of adjacent resources can: be closer than 7146pname:bufferImageGranularity, provided they meet the pname:alignment 7147requirement for the objects in question. 7148 7149Sparse block size in bytes and sparse image and buffer memory alignments 7150must: all be multiples of the pname:bufferImageGranularity. 7151Therefore, memory bound to sparse resources naturally satisfies the 7152pname:bufferImageGranularity. 7153 7154 7155[[resources-sharing]] 7156== Resource Sharing Mode 7157 7158[open,refpage='VkSharingMode',desc='Buffer and image sharing modes',type='enums'] 7159-- 7160Buffer and image objects are created with a _sharing mode_ controlling how 7161they can: be accessed from queues. 7162The supported sharing modes are: 7163 7164include::{generated}/api/enums/VkSharingMode.txt[] 7165 7166 * ename:VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or 7167 image subresource of the object will be exclusive to a single queue 7168 family at a time. 7169 * ename:VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any 7170 range or image subresource of the object from multiple queue families is 7171 supported. 7172 7173[NOTE] 7174.Note 7175==== 7176ename:VK_SHARING_MODE_CONCURRENT may: result in lower performance access to 7177the buffer or image than ename:VK_SHARING_MODE_EXCLUSIVE. 7178==== 7179 7180Ranges of buffers and image subresources of image objects created using 7181ename:VK_SHARING_MODE_EXCLUSIVE must: only be accessed by queues in the 7182queue family that has _ownership_ of the resource. 7183Upon creation, such resources are not owned by any queue family; ownership 7184is implicitly acquired upon first use within a queue. 7185Once a resource using ename:VK_SHARING_MODE_EXCLUSIVE is owned by some queue 7186family, the application must: perform a 7187<<synchronization-queue-transfers,queue family ownership transfer>> to make 7188the memory contents of a range or image subresource accessible to a 7189different queue family. 7190 7191[NOTE] 7192.Note 7193==== 7194Images still require a <<resources-image-layouts, layout transition>> from 7195ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED 7196before being used on the first queue. 7197==== 7198 7199A queue family can: take ownership of an image subresource or buffer range 7200of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an 7201ownership transfer, in the same way as for a resource that was just created; 7202however, taking ownership in this way has the effect that the contents of 7203the image subresource or buffer range are undefined:. 7204 7205Ranges of buffers and image subresources of image objects created using 7206ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the 7207queue families specified through the pname:queueFamilyIndexCount and 7208pname:pQueueFamilyIndices members of the corresponding create info 7209structures. 7210-- 7211 7212 7213ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 7214[[resources-external-sharing]] 7215=== External Resource Sharing 7216 7217Resources should: only be accessed in the Vulkan instance that has exclusive 7218ownership of their underlying memory. 7219Only one Vulkan instance has exclusive ownership of a resource's underlying 7220memory at a given time, regardless of whether the resource was created using 7221ename:VK_SHARING_MODE_EXCLUSIVE or ename:VK_SHARING_MODE_CONCURRENT. 7222Applications can transfer ownership of a resource's underlying memory only 7223if the memory has been imported from or exported to another instance or 7224external API using external memory handles. 7225The semantics for transferring ownership outside of the instance are similar 7226to those used for transferring ownership of ename:VK_SHARING_MODE_EXCLUSIVE 7227resources between queues, and is also accomplished using 7228slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier operations. 7229To make the contents of the underlying memory accessible in the destination 7230instance or API, applications must: 7231 7232 . Release exclusive ownership from the source instance or API. 7233 . Ensure the release operation has completed using semaphores or fences. 7234 . Acquire exclusive ownership in the destination instance or API 7235 7236Unlike queue ownership transfers, the destination instance or API is not 7237specified explicitly when releasing ownership, nor is the source instance or 7238API specified when acquiring ownership. 7239Instead, the image or memory barrier's pname:dstQueueFamilyIndex or 7240pname:srcQueueFamilyIndex parameters are set to the reserved queue family 7241index ename:VK_QUEUE_FAMILY_EXTERNAL 7242ifdef::VK_EXT_queue_family_foreign[] 7243or ename:VK_QUEUE_FAMILY_FOREIGN_EXT 7244endif::VK_EXT_queue_family_foreign[] 7245to represent the external destination or source respectively. 7246 7247Binding a resource to a memory object shared between multiple Vulkan 7248instances or other APIs does not change the ownership of the underlying 7249memory. 7250The first entity to access the resource implicitly acquires ownership. 7251An entity can: also implicitly take ownership from another entity in the 7252same way without an explicit ownership transfer. 7253However, taking ownership in this way has the effect that the contents of 7254the underlying memory are undefined:. 7255 7256Accessing a resource backed by memory that is owned by a particular instance 7257or API has the same semantics as accessing a ename:VK_SHARING_MODE_EXCLUSIVE 7258resource, with one exception: Implementations must: ensure layout 7259transitions performed on one member of a set of identical subresources of 7260identical images that alias the same range of an underlying memory object 7261affect the layout of all the subresources in the set. 7262 7263As a corollary, writes to any image subresources in such a set must: not 7264make the contents of memory used by other subresources in the set 7265undefined:. 7266An application can: define the content of a subresource of one image by 7267performing device writes to an identical subresource of another image 7268provided both images are bound to the same region of external memory. 7269Applications may: also add resources to such a set after the content of the 7270existing set members has been defined without making the content undefined: 7271by creating a new image with the initial layout 7272ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of 7273external memory as the existing images. 7274 7275[NOTE] 7276.Note 7277==== 7278Because layout transitions apply to all identical images aliasing the same 7279region of external memory, the actual layout of the memory backing a new 7280image as well as an existing image with defined content will not be 7281undefined:. 7282Such an image is not usable until it acquires ownership of its memory from 7283the existing owner. 7284Therefore, the layout specified as part of this transition will be the true 7285initial layout of the image. 7286The undefined: layout specified when creating it is a placeholder to 7287simplify valid usage requirements. 7288==== 7289endif::VK_VERSION_1_1,VK_KHR_external_memory[] 7290 7291 7292[[resources-memory-aliasing]] 7293== Memory Aliasing 7294 7295A range of a sname:VkDeviceMemory allocation is _aliased_ if it is bound to 7296multiple resources simultaneously, as described below, via 7297flink:vkBindImageMemory, flink:vkBindBufferMemory, 7298ifdef::VK_NV_ray_tracing[] 7299flink:vkBindAccelerationStructureMemoryNV, 7300endif::VK_NV_ray_tracing[] 7301ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 7302or via <<sparsememory-resource-binding,sparse memory bindings>>. 7303endif::VK_VERSION_1_1,VK_KHR_external_memory[] 7304ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 7305via <<sparsememory-resource-binding,sparse memory bindings>>, or by binding 7306the memory to resources in multiple Vulkan instances or external APIs using 7307external memory handle export and import mechanisms. 7308endif::VK_VERSION_1_1,VK_KHR_external_memory[] 7309 7310Consider two resources, resource~A~ and resource~B~, bound respectively to 7311memory range~A~ and range~B~. 7312Let paddedRange~A~ and paddedRange~B~ be, respectively, range~A~ and 7313range~B~ aligned to pname:bufferImageGranularity. 7314If the resources are both linear or both non-linear (as defined in the 7315<<glossary-linear-resource,Glossary>>), then the resources _alias_ the 7316memory in the intersection of range~A~ and range~B~. 7317If one resource is linear and the other is non-linear, then the resources 7318_alias_ the memory in the intersection of paddedRange~A~ and paddedRange~B~. 7319 7320Applications can: alias memory, but use of multiple aliases is subject to 7321several constraints. 7322 7323[NOTE] 7324.Note 7325==== 7326Memory aliasing can: be useful to reduce the total device memory footprint 7327of an application, if some large resources are used for disjoint periods of 7328time. 7329==== 7330 7331When a <<glossary-linear-resource,non-linear>>, 7332non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased 7333range, all image subresources of the image _overlap_ the range. 7334When a linear image is bound to an aliased range, the image subresources 7335that (according to the image's advertised layout) include bytes from the 7336aliased range overlap the range. 7337When a ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image 7338blocks bound to an aliased range, only image subresources including those 7339sparse image blocks overlap the range, and when the memory bound to the 7340image's mip tail overlaps an aliased range all image subresources in the mip 7341tail overlap the range. 7342 7343Buffers, and linear image subresources in either the 7344ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL 7345layouts, are _host-accessible subresources_. 7346That is, the host has a well-defined addressing scheme to interpret the 7347contents, and thus the layout of the data in memory can: be consistently 7348interpreted across aliases if each of those aliases is a host-accessible 7349subresource. 7350Non-linear images, and linear image subresources in other layouts, are not 7351host-accessible. 7352 7353If two aliases are both host-accessible, then they interpret the contents of 7354the memory in consistent ways, and data written to one alias can: be read by 7355the other alias. 7356 7357ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 7358[[resources-memory-aliasing-consistency]] 7359If two aliases are both images that were created with identical creation 7360parameters, both were created with the ename:VK_IMAGE_CREATE_ALIAS_BIT flag 7361set, and both are bound identically to memory 7362ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 7363except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices and 7364slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions, 7365endif::VK_VERSION_1_1,VK_KHR_device_group[] 7366then they interpret the contents of the memory in consistent ways, and data 7367written to one alias can: be read by the other alias. 7368 7369ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 7370[[resources-memory-aliasing-consistency-planes]] 7371Additionally, if an individual plane of a multi-planar image and a 7372single-plane image alias the same memory, then they also interpret the 7373contents of the memory in consistent ways under the same conditions, but 7374with the following modifications: 7375 7376 * Both must: have been created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT 7377 flag. 7378 * The single-plane image must: have a elink:VkFormat that is 7379 <<formats-compatible-planes,equivalent>> to that of the multi-planar 7380 image's individual plane. 7381 * The single-plane image and the individual plane of the multi-planar 7382 image must: be bound identically to memory 7383ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 7384 except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices 7385 and 7386 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions. 7387endif::VK_VERSION_1_1,VK_KHR_device_group[] 7388 * The pname:width and pname:height of the single-plane image are derived 7389 from the multi-planar image's dimensions in the manner listed for 7390 <<formats-compatible-planes,plane compatibility>> for the aliased plane. 7391ifdef::VK_EXT_image_drm_format_modifier[] 7392 * If either image's pname:tiling is 7393 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must: be 7394 <<glossary-linear-resource,linear>>. 7395endif::VK_EXT_image_drm_format_modifier[] 7396 * All other creation parameters must: be identical 7397 7398endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 7399endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 7400 7401ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 7402Aliases created by binding the same memory to resources in multiple Vulkan 7403instances or external APIs using external memory handle export and import 7404mechanisms interpret the contents of the memory in consistent ways, and data 7405written to one alias can: be read by the other alias. 7406endif::VK_VERSION_1_1,VK_KHR_external_memory[] 7407 7408Otherwise, the aliases interpret the contents of the memory differently, and 7409writes via one alias make the contents of memory partially or completely 7410undefined: to the other alias. 7411If the first alias is a host-accessible subresource, then the bytes affected 7412are those written by the memory operations according to its addressing 7413scheme. 7414If the first alias is not host-accessible, then the bytes affected are those 7415overlapped by the image subresources that were written. 7416If the second alias is a host-accessible subresource, the affected bytes 7417become undefined:. 7418If the second alias is not host-accessible, all sparse image blocks (for 7419sparse partially-resident images) or all image subresources (for non-sparse 7420image and fully resident sparse images) that overlap the affected bytes 7421become undefined:. 7422 7423If any image subresources are made undefined: due to writes to an alias, 7424then each of those image subresources must: have its layout transitioned 7425from ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or 7426from ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by 7427the host. 7428If any sparse blocks of a sparse image have been made undefined:, then only 7429the image subresources containing them must: be transitioned. 7430 7431Use of an overlapping range by two aliases must: be separated by a memory 7432dependency using the appropriate <<synchronization-access-types, access 7433types>> if at least one of those uses performs writes, whether the aliases 7434interpret memory consistently or not. 7435If buffer or image memory barriers are used, the scope of the barrier must: 7436contain the entire range and/or set of image subresources that overlap. 7437 7438If two aliasing image views are used in the same framebuffer, then the 7439render pass must: declare the attachments using the 7440<<renderpass-aliasing,ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT>>, and 7441follow the other rules listed in that section. 7442 7443[NOTE] 7444.Note 7445==== 7446Memory recycled via an application suballocator (i.e. without freeing and 7447reallocating the memory objects) is not substantially different from memory 7448aliasing. 7449However, a suballocator usually waits on a fence before recycling a region 7450of memory, and signaling a fence involves sufficient implicit dependencies 7451to satisfy all the above requirements. 7452==== 7453 7454 7455ifdef::VK_FUCHSIA_buffer_collection[] 7456[[resources-buffer-collection-fuchsia]] 7457== Buffer Collections 7458 7459[open,refpage='VkBufferCollectionFUCHSIA',desc='Opaque handle to a buffer collection object',type='handles'] 7460-- 7461Fuchsia's FIDL-based Sysmem service interoperates with Vulkan via the 7462`apiext:VK_FUCHSIA_buffer_collection` extension. 7463 7464A buffer collection is a set of one or more buffers which were allocated 7465together as a group and which all have the same properties. 7466These properties describe the buffers' internal representation, such as its 7467dimensions and memory layout. 7468This ensures that all of the buffers can be used interchangeably by tasks 7469that require swapping among multiple buffers, such as double-buffered 7470graphics rendering. 7471 7472On Fuchsia, the Sysmem service uses buffer collections as a core construct 7473in its design. 7474 7475Buffer collections are represented by sname:VkBufferCollectionFUCHSIA 7476handles: 7477 7478include::{generated}/api/handles/VkBufferCollectionFUCHSIA.txt[] 7479-- 7480 7481 7482=== Definitions 7483 7484 * FIDL - Fuchsia Interface Definition Language. 7485 The declarative language used to define FIDL interprocess communication 7486 interfaces on Fuchsia. 7487 FIDL files use the `fidl` extension. 7488 FIDL is also used to refer to the services defined by interfaces 7489 declared in the FIDL language 7490 * Sysmem - The FIDL service that facilitates optimal buffer sharing and 7491 reuse on Fuchsia 7492 * client - Any participant of the buffer collection e.g. the Vulkan 7493 application 7494 * token - A code:zx_handle_t Zircon channel object that allows 7495 participation in the buffer collection 7496 7497 7498=== Platform initialization for buffer collections 7499To initialize a buffer collection on Fuchsia: 7500 7501 * Connect to the Sysmem service to initialize a Sysmem allocator 7502 * Create an initial buffer collection token using the Sysmem allocator 7503 * Duplicate the token for each participant beyond the initiator 7504 * See the Sysmem Overview and fuchsia.sysmem FIDL documentation on 7505 fuchsia.dev for more detailed information 7506 7507 7508=== Create the buffer collection 7509 7510[open,refpage='vkCreateBufferCollectionFUCHSIA',desc='Create a new buffer collection',type='protos'] 7511-- 7512To create an slink:VkBufferCollectionFUCHSIA for Vulkan to participate in 7513the buffer collection: 7514 7515include::{generated}/api/protos/vkCreateBufferCollectionFUCHSIA.txt[] 7516 7517 * pname:device is the logical device that creates the 7518 sname:VkBufferCollectionFUCHSIA 7519 * pname:pCreateInfo is a pointer to a 7520 slink:VkBufferCollectionCreateInfoFUCHSIA structure containing 7521 parameters affecting creation of the buffer collection 7522 * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure 7523 controlling host memory allocation as described in the 7524 <<memory-allocation, Memory Allocation>> chapter 7525 * pname:pBufferCollection is a pointer to a 7526 slink:VkBufferCollectionFUCHSIA handle in which the resulting buffer 7527 collection object is returned 7528 7529include::{generated}/validity/protos/vkCreateBufferCollectionFUCHSIA.txt[] 7530 7531.Host Access 7532**** 7533All functions referencing a slink:VkBufferCollectionFUCHSIA must: be 7534externally synchronized with the exception of 7535fname:vkCreateBufferCollectionFUCHSIA. 7536**** 7537-- 7538 7539 7540[open,refpage='VkBufferCollectionCreateInfoFUCHSIA',desc='Structure specifying desired parameters to create the buffer collection',type='structs'] 7541-- 7542The sname:VkBufferCollectionCreateInfoFUCHSIA structure is defined as: 7543 7544include::{generated}/api/structs/VkBufferCollectionCreateInfoFUCHSIA.txt[] 7545 7546 * pname:sType is the type of this structure 7547 * pname:pNext is `NULL` or a pointer to a structure extending this 7548 structure 7549 * pname:collectionToken is a fname:zx_handle_t containing the Sysmem 7550 client's buffer collection token 7551 7552.Valid Usage 7553**** 7554 * [[VUID-VkBufferCollectionCreateInfoFUCHSIA-collectionToken-06393]] 7555 pname:collectionToken must: be a valid code:zx_handle_t to a Zircon 7556 channel allocated from Sysmem 7557 (code:fuchsia.sysmem.Allocator/AllocateSharedCollection) with 7558 code:ZX_DEFAULT_CHANNEL_RIGHTS rights 7559**** 7560 7561include::{generated}/validity/structs/VkBufferCollectionCreateInfoFUCHSIA.txt[] 7562-- 7563 7564 7565=== Set the constraints 7566Buffer collections can be established for slink:VkImage allocations or 7567slink:VkBuffer allocations. 7568 7569 7570==== Set image-based buffer collection constraints 7571 7572[open,refpage='vkSetBufferCollectionImageConstraintsFUCHSIA',desc='Set image-based constraints for a buffer collection',type='protos'] 7573-- 7574Setting the constraints on the buffer collection initiates the format 7575negotiation and allocation of the buffer collection. 7576To set the constraints on a slink:VkImage buffer collection, call: 7577 7578include::{generated}/api/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.txt[] 7579 7580 * pname:device is the logical device 7581 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 7582 * pname:pImageConstraintsInfo is a pointer to a 7583 slink:VkImageConstraintsInfoFUCHSIA structure 7584 7585fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if 7586pname:pImageConstraintsInfo::pname:formatConstraintsCount is larger than the 7587implementation-defined limit. 7588If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will 7589return VK_ERROR_INITIALIZATION_FAILED. 7590 7591fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if the 7592implementation does not support any of the formats described by the 7593pname:pImageConstraintsInfo structure. 7594If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will 7595return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 7596 7597.Valid Usage 7598**** 7599 * [[VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-06394]] 7600 fname:vkSetBufferCollectionImageConstraintsFUCHSIA or 7601 fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have 7602 already been called on pname:collection 7603**** 7604 7605include::{generated}/validity/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.txt[] 7606-- 7607 7608[open,refpage='VkImageConstraintsInfoFUCHSIA',desc='Structure of image-based buffer collection constraints',type='structs'] 7609-- 7610The sname:VkImageConstraintsInfoFUCHSIA structure is defined as: 7611 7612include::{generated}/api/structs/VkImageConstraintsInfoFUCHSIA.txt[] 7613 7614 * pname:sType is the type of this structure. 7615 * pname:pNext is `NULL` or a pointer to a structure extending this 7616 structure. 7617 * pname:formatConstraintsCount is the number of elements in 7618 pname:pFormatConstraints. 7619 * pname:pFormatConstraints is a pointer to an array of 7620 slink:VkImageFormatConstraintsInfoFUCHSIA structures of size 7621 pname:formatConstraintsCount that is used to further constrain buffer 7622 collection format selection for image-based buffer collections. 7623 * pname:bufferCollectionConstraints is a 7624 slink:VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply 7625 parameters for the negotiation and allocation for buffer-based buffer 7626 collections. 7627 * pname:flags is a elink:VkImageConstraintsInfoFlagBitsFUCHSIA value 7628 specifying hints about the type of memory Sysmem should allocate for the 7629 buffer collection. 7630 7631.Valid Usage 7632**** 7633 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06395]] 7634 All elements of pname:pFormatConstraints must: have at least one bit set 7635 in its 7636 slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures 7637 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06396]] 7638 If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7639 ename:VK_IMAGE_USAGE_SAMPLED_BIT, then 7640 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain 7641 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT 7642 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06397]] 7643 If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7644 ename:VK_IMAGE_USAGE_STORAGE_BIT, then 7645 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain 7646 ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT 7647 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06398]] 7648 If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7649 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then 7650 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain 7651 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 7652 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06399]] 7653 If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7654 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then 7655 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain 7656 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 7657 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06400]] 7658 If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7659 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then 7660 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain at 7661 least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 7662 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 7663ifdef::VK_KHR_fragment_shading_rate[] 7664 * [[VUID-VkImageConstraintsInfoFUCHSIA-attachmentFragmentShadingRate-06401]] 7665 If the <<features-attachmentFragmentShadingRate, 7666 pname:attachmentFragmentShadingRate feature>> is enabled, and 7667 pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains 7668 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then 7669 pname:pFormatConstraints::pname:requiredFormatFeatures must: contain 7670 ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 7671endif::VK_KHR_fragment_shading_rate[] 7672**** 7673 7674include::{generated}/validity/structs/VkImageConstraintsInfoFUCHSIA.txt[] 7675-- 7676 7677[open,refpage='VkImageConstraintsInfoFlagsFUCHSIA',desc='Reserved for future use',type='flags'] 7678-- 7679include::{generated}/api/flags/VkImageConstraintsInfoFlagsFUCHSIA.txt[] 7680 7681tname:VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a 7682mask of zero or more elink:VkImageConstraintsInfoFlagBitsFUCHSIA bits. 7683-- 7684 7685[open,refpage='VkImageConstraintsInfoFlagBitsFUCHSIA',desc='Bitmask specifying image constraints flags',type='enums'] 7686-- 7687Bits which can: be set in 7688elink:VkImageConstraintsInfoFlagBitsFUCHSIA::pname:flags include: 7689 7690include::{generated}/api/enums/VkImageConstraintsInfoFlagBitsFUCHSIA.txt[] 7691 7692General hints about the type of memory that should be allocated by Sysmem 7693based on the expected usage of the images in the buffer collection include: 7694 7695 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA 7696 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA 7697 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA 7698 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA 7699 7700For protected memory: 7701 7702 * ename:VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA specifies 7703 that protected memory is optional for the buffer collection. 7704 7705Note that if all participants in the buffer collection (Vulkan or otherwise) 7706specify that protected memory is optional, Sysmem will not allocate 7707protected memory. 7708-- 7709 7710[open,refpage='VkImageFormatConstraintsInfoFUCHSIA',desc='Structure image-based buffer collection constraints',type='structs'] 7711-- 7712The sname:VkImageFormatConstraintsInfoFUCHSIA structure is defined as: 7713 7714include::{generated}/api/structs/VkImageFormatConstraintsInfoFUCHSIA.txt[] 7715 7716 * pname:sType is the type of this structure 7717 * pname:pNext is `NULL` or a pointer to a structure extending this 7718 structure 7719 * pname:imageCreateInfo is the slink:VkImageCreateInfo used to create a 7720 slink:VkImage that is to use memory from the 7721 slink:VkBufferCollectionFUCHSIA 7722 * pname:requiredFormatFeatures is a bitmask of 7723 ename:VkFormatFeatureFlagBits specifying required features of the 7724 buffers in the buffer collection 7725 * pname:flags is reserved for future use 7726 * pname:sysmemPixelFormat is a code:PixelFormatType value from the 7727 `fuchsia.sysmem/image_formats.fidl` FIDL interface 7728 * pname:colorSpaceCount the element count of pname:pColorSpaces 7729 * pname:pColorSpaces is a pointer to an array of 7730 slink:VkSysmemColorSpaceFUCHSIA structs of size pname:colorSpaceCount 7731 7732include::{generated}/validity/structs/VkImageFormatConstraintsInfoFUCHSIA.txt[] 7733-- 7734 7735[open,refpage='VkImageFormatConstraintsFlagsFUCHSIA',desc='Reserved for future use',type='flags'] 7736-- 7737include::{generated}/api/flags/VkImageFormatConstraintsFlagsFUCHSIA.txt[] 7738 7739tname:VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a 7740mask, but is currently reserved for future use. 7741-- 7742 7743[open,refpage='VkBufferCollectionConstraintsInfoFUCHSIA',desc='Structure of general buffer collection constraints',type='structs'] 7744-- 7745The sname:VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as: 7746 7747include::{generated}/api/structs/VkBufferCollectionConstraintsInfoFUCHSIA.txt[] 7748 7749 * pname:sType is the type of this structure 7750 * pname:pNext is `NULL` or a pointer to a structure extending this 7751 structure 7752 * pname:minBufferCount is the minimum number of buffers available in the 7753 collection 7754 * pname:maxBufferCount is the maximum number of buffers allowed in the 7755 collection 7756 * pname:minBufferCountForCamping is the per-participant minimum buffers 7757 for camping 7758 * pname:minBufferCountForDedicatedSlack is the per-participant minimum 7759 buffers for dedicated slack 7760 * pname:minBufferCountForSharedSlack is the per-participant minimum 7761 buffers for shared slack 7762 7763Sysmem uses all buffer count parameters in combination to determine the 7764number of buffers it will allocate. 7765Sysmem defines buffer count constraints in 7766`fuchsia.sysmem/constraints.fidl`. 7767 7768_Camping_ as referred to by pname:minBufferCountForCamping, is the number of 7769buffers that should be available for the participant that are not for 7770transient use. 7771This number of buffers is required for the participant to logically operate. 7772 7773_Slack_ as referred to by pname:minBufferCountForDedicatedSlack and 7774pname:minBufferCountForSharedSlack, refers to the number of buffers desired 7775by participants for optimal performance. 7776pname:minBufferCountForDedicatedSlack refers to the current participant. 7777pname:minBufferCountForSharedSlack refers to buffer slack for all 7778participants in the collection. 7779 7780include::{generated}/validity/structs/VkBufferCollectionConstraintsInfoFUCHSIA.txt[] 7781-- 7782 7783[open,refpage='VkSysmemColorSpaceFUCHSIA',desc='Structure describing the buffer collections color space',type='structs'] 7784-- 7785 7786The sname:VkSysmemColorSpaceFUCHSIA structure is defined as: 7787 7788include::{generated}/api/structs/VkSysmemColorSpaceFUCHSIA.txt[] 7789 7790 * pname:sType is the type of this structure 7791 * pname:pNext is `NULL` or a pointer to a structure extending this 7792 structure 7793 * pname:colorSpace value of the Sysmem code:ColorSpaceType 7794 7795.Valid Usage 7796**** 7797 * [[VUID-VkSysmemColorSpaceFUCHSIA-colorSpace-06402]] 7798 pname:colorSpace must: be a code:ColorSpaceType as defined in 7799 `fuchsia.sysmem/image_formats.fidl` 7800**** 7801 7802include::{generated}/validity/structs/VkSysmemColorSpaceFUCHSIA.txt[] 7803-- 7804 7805 7806==== Set buffer-based buffer collection constraints 7807 7808[open,refpage='vkSetBufferCollectionBufferConstraintsFUCHSIA',desc='Set buffer-based constraints for a buffer collection',type='protos'] 7809-- 7810To set the constraints on a slink:VkBuffer buffer collection, call: 7811 7812include::{generated}/api/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.txt[] 7813 7814 * pname:device is the logical device 7815 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 7816 * pname:pBufferConstraintsInfo is a pointer to a 7817 slink:VkBufferConstraintsInfoFUCHSIA structure 7818 7819fname:vkSetBufferCollectionBufferConstraintsFUCHSIA may: fail if the 7820implementation does not support the constraints specified in the 7821pname:bufferCollectionConstraints structure. 7822If that occurs, flink:vkSetBufferCollectionBufferConstraintsFUCHSIA will 7823return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 7824 7825.Valid Usage 7826**** 7827 * [[VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-06403]] 7828 fname:vkSetBufferCollectionImageConstraintsFUCHSIA or 7829 fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have 7830 already been called on pname:collection 7831**** 7832 7833include::{generated}/validity/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.txt[] 7834-- 7835 7836[open,refpage='VkBufferConstraintsInfoFUCHSIA',desc='Structure buffer-based buffer collection constraints',type='structs'] 7837-- 7838The sname:VkBufferConstraintsInfoFUCHSIA structure is defined as: 7839 7840include::{generated}/api/structs/VkBufferConstraintsInfoFUCHSIA.txt[] 7841 7842 * pname:sType is the type of this structure 7843 * pname:pNext is `NULL` or a pointer to a structure extending this 7844 structure 7845 * pname:pBufferCreateInfo a pointer to a slink:VkBufferCreateInfo struct 7846 describing the buffer attributes for the buffer collection 7847 * pname:requiredFormatFeatures bitmask of ename:VkFormatFeatureFlagBits 7848 required features of the buffers in the buffer collection 7849 * pname:bufferCollectionConstraints is used to supply parameters for the 7850 negotiation and allocation of the buffer collection 7851 7852.Valid Usage 7853**** 7854 * [[VUID-VkBufferConstraintsInfoFUCHSIA-requiredFormatFeatures-06404]] 7855 The pname:requiredFormatFeatures bitmask of 7856 ename:VkFormatFeatureFlagBits must: be chosen from among the buffer 7857 compatible format features listed in 7858 <<buffer-compatible-format-features,buffer compatible format features>> 7859**** 7860 7861include::{generated}/validity/structs/VkBufferConstraintsInfoFUCHSIA.txt[] 7862-- 7863 7864 7865=== Retrieve buffer collection properties 7866 7867[open,refpage='vkGetBufferCollectionPropertiesFUCHSIA',desc='Retrieve properties from a buffer collection',type='protos'] 7868-- 7869After constraints have been set on the buffer collection by calling 7870flink:vkSetBufferCollectionImageConstraintsFUCHSIA or 7871flink:vkSetBufferCollectionBufferConstraintsFUCHSIA, call 7872fname:vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and 7873finalized properties of the buffer collection. 7874 7875The call to fname:vkGetBufferCollectionPropertiesFUCHSIA is synchronous. 7876It waits for the Sysmem format negotiation and buffer collection allocation 7877to complete before returning. 7878 7879include::{generated}/api/protos/vkGetBufferCollectionPropertiesFUCHSIA.txt[] 7880 7881 * pname:device is the logical device handle 7882 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 7883 * pname:pProperties is a pointer to the retrieved 7884 slink:VkBufferCollectionPropertiesFUCHSIA struct 7885 7886[[sysmem-chosen-create-infos]] 7887For image-based buffer collections, upon calling 7888fname:vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element 7889of the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos 7890established by the preceding call to 7891flink:vkSetBufferCollectionImageConstraintsFUCHSIA. 7892The index of the element chosen is stored in and can be retrieved from 7893slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex. 7894 7895For buffer-based buffer collections, a single slink:VkBufferCreateInfo is 7896specified as slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo. 7897slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex will 7898therefore always be zero. 7899 7900fname:vkGetBufferCollectionPropertiesFUCHSIA may: fail if Sysmem is unable 7901to resolve the constraints of all of the participants in the buffer 7902collection. 7903If that occurs, fname:vkGetBufferCollectionPropertiesFUCHSIA will return 7904ename:VK_ERROR_INITIALIZATION_FAILED. 7905 7906.Valid Usage 7907**** 7908 * [[VUID-vkGetBufferCollectionPropertiesFUCHSIA-None-06405]] 7909 Prior to calling flink:vkGetBufferCollectionPropertiesFUCHSIA, the 7910 constraints on the buffer collection must: have been set by either 7911 flink:vkSetBufferCollectionImageConstraintsFUCHSIA or 7912 flink:vkSetBufferCollectionBufferConstraintsFUCHSIA. 7913**** 7914 7915include::{generated}/validity/protos/vkGetBufferCollectionPropertiesFUCHSIA.txt[] 7916-- 7917 7918[open,refpage='VkBufferCollectionPropertiesFUCHSIA',desc='Structure specifying the negotiated format chosen by Sysmem',type='structs'] 7919-- 7920 7921The sname:VkBufferCollectionPropertiesFUCHSIA structure is defined as: 7922 7923include::{generated}/api/structs/VkBufferCollectionPropertiesFUCHSIA.txt[] 7924 7925 * pname:sType is the type of this structure 7926 * pname:pNext is `NULL` or a pointer to a structure extending this 7927 structure 7928 * pname:memoryTypeBits is a bitmask containing one bit set for every 7929 memory type which the buffer collection can be imported as buffer 7930 collection 7931 * pname:bufferCount is the number of buffers in the collection 7932 * pname:createInfoIndex as described in <<sysmem-chosen-create-infos, 7933 Sysmem chosen create infos>> 7934 * pname:sysmemPixelFormat is the Sysmem code:PixelFormatType as defined in 7935 `fuchsia.sysmem/image_formats.fidl` 7936 * pname:formatFeatures is a bitmask of elink:VkFormatFeatureFlagBits 7937 shared by the buffer collection 7938 * pname:sysmemColorSpaceIndex is a slink:VkSysmemColorSpaceFUCHSIA struct 7939 specifying the color space 7940 * pname:samplerYcbcrConversionComponents is a slink:VkComponentMapping 7941 struct specifying the component mapping 7942 * pname:suggestedYcbcrModel is a elink:VkSamplerYcbcrModelConversion value 7943 specifying the suggested {YCbCr} model 7944 * pname:suggestedYcbcrRange is a elink:VkSamplerYcbcrRange value 7945 specifying the suggested {YCbCr} range 7946 * pname:suggestedXChromaOffset is a elink:VkChromaLocation value 7947 specifying the suggested X chroma offset 7948 * pname:suggestedYChromaOffset is a elink:VkChromaLocation value 7949 specifying the suggested Y chroma offset 7950 7951pname:sysmemColorSpace is only set for image-based buffer collections where 7952the constraints were specified using slink:VkImageConstraintsInfoFUCHSIA in 7953a call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA. 7954 7955For image-based buffer collections, pname:createInfoIndex will identify both 7956the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos element and 7957the slink:VkImageConstraintsInfoFUCHSIA::pname:pFormatConstraints element 7958chosen by Sysmem when flink:vkSetBufferCollectionImageConstraintsFUCHSIA was 7959called. 7960The value of pname:sysmemColorSpaceIndex will be an index to one of the 7961color spaces provided in the 7962slink:VkImageFormatConstraintsInfoFUCHSIA::pname:pColorSpaces array. 7963 7964The implementation must have pname:formatFeatures with all bits set that 7965were set in 7966slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures, by 7967the call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA, at 7968pname:createInfoIndex (other bits could be set as well). 7969 7970include::{generated}/validity/structs/VkBufferCollectionPropertiesFUCHSIA.txt[] 7971-- 7972 7973 7974=== Memory allocation 7975 7976To import memory from a buffer collection into a slink:VkImage or a 7977slink:VkBuffer, chain a slink:VkImportMemoryBufferCollectionFUCHSIA 7978structure to the pname:pNext member of the slink:VkMemoryAllocateInfo in the 7979call to flink:vkAllocateMemory. 7980 7981[open,refpage='VkImportMemoryBufferCollectionFUCHSIA',desc='Structure to specify the Sysmem buffer to import',type='structs'] 7982-- 7983The sname:VkImportMemoryBufferCollectionFUCHSIA structure is defined as: 7984 7985include::{generated}/api/structs/VkImportMemoryBufferCollectionFUCHSIA.txt[] 7986 7987 * pname:sType is the type of this structure 7988 * pname:pNext is `NULL` or a pointer to a structure extending this 7989 structure 7990 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 7991 * pname:index the index of the buffer to import from pname:collection 7992 7993.Valid Usage 7994**** 7995 * [[VUID-VkImportMemoryBufferCollectionFUCHSIA-index-06406]] 7996 pname:index must: be less than the value retrieved as 7997 slink:VkBufferCollectionPropertiesFUCHSIA:bufferCount 7998**** 7999 8000include::{generated}/validity/structs/VkImportMemoryBufferCollectionFUCHSIA.txt[] 8001-- 8002 8003[open,refpage='vkDestroyBufferCollectionFUCHSIA',desc='Destroy a buffer collection',type='protos'] 8004-- 8005To release a slink:VkBufferCollectionFUCHSIA: 8006 8007include::{generated}/api/protos/vkDestroyBufferCollectionFUCHSIA.txt[] 8008 8009 * pname:device is the logical device that creates the 8010 sname:VkBufferCollectionFUCHSIA 8011 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 8012 * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure 8013 controlling host memory allocation as described in the 8014 <<memory-allocation, Memory Allocation>> chapter 8015 8016.Valid Usage 8017**** 8018 * [[VUID-vkDestroyBufferCollectionFUCHSIA-collection-06407]] 8019 slink:VkImage and slink:VkBuffer objects that referenced 8020 pname:collection upon creation by inclusion of a 8021 slink:VkBufferCollectionImageCreateInfoFUCHSIA or 8022 slink:VkBufferCollectionBufferCreateInfoFUCHSIA chained to their 8023 slink:VkImageCreateInfo or slink:VkBufferCreateInfo structures 8024 respectively, may: outlive pname:collection. 8025**** 8026 8027include::{generated}/validity/protos/vkDestroyBufferCollectionFUCHSIA.txt[] 8028-- 8029endif::VK_FUCHSIA_buffer_collection[] 8030