1// Copyright 2015-2024 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 provide access to raw arrays of bytes, whereas images can: be 11multidimensional and may: have associated metadata. 12 13ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 14Other resource types, such as <<resources-acceleration-structures, 15acceleration structures>> 16ifdef::VK_EXT_opacity_micromap[] 17and <<resources-micromaps, micromaps>> 18endif::VK_EXT_opacity_micromap[] 19use buffers as the backing store for opaque data structures. 20endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 21 22 23[[resources-buffers]] 24== Buffers 25 26[open,refpage='VkBuffer',desc='Opaque handle to a buffer object',type='handles'] 27-- 28Buffers represent linear arrays of data which are used for various purposes 29by binding them to a graphics or compute pipeline via descriptor sets or 30certain commands, or by directly specifying them as parameters to certain 31commands. 32 33Buffers are represented by sname:VkBuffer handles: 34 35include::{generated}/api/handles/VkBuffer.adoc[] 36-- 37 38[open,refpage='vkCreateBuffer',desc='Create a new buffer object',type='protos'] 39-- 40:refpage: vkCreateBuffer 41:objectnameplural: buffers 42:objectnamecamelcase: buffer 43:objectcount: 1 44 45To create buffers, call: 46 47include::{generated}/api/protos/vkCreateBuffer.adoc[] 48 49 * pname:device is the logical device that creates the buffer object. 50 * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure 51 containing parameters affecting creation of the buffer. 52 * pname:pAllocator controls host memory allocation as described in the 53 <<memory-allocation, Memory Allocation>> chapter. 54 * pname:pBuffer is a pointer to a slink:VkBuffer handle in which the 55 resulting buffer object is returned. 56 57include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 58 59.Valid Usage 60**** 61ifndef::VKSC_VERSION_1_0[] 62 * [[VUID-vkCreateBuffer-flags-00911]] 63 If the pname:flags member of pname:pCreateInfo includes 64 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 65ifdef::VK_NV_extended_sparse_address_space[] 66 and the <<features-extendedSparseAddressSpace, 67 pname:extendedSparseAddressSpace>> feature is not enabled, 68endif::VK_NV_extended_sparse_address_space[] 69 creating this sname:VkBuffer must: not cause the total required sparse 70 memory for all currently valid sparse resources on the device to exceed 71 sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 72ifdef::VK_NV_extended_sparse_address_space[] 73 * [[VUID-vkCreateBuffer-flags-09383]] 74 If the pname:flags member of pname:pCreateInfo includes 75 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, the 76 <<features-extendedSparseAddressSpace, 77 pname:extendedSparseAddressSpace>> feature is enabled, and the 78 pname:usage member of pname:pCreateInfo contains bits not in 79 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseBufferUsageFlags, 80 creating this sname:VkBuffer must: not cause the total required sparse 81 memory for all currently valid sparse resources on the device, excluding 82 sname:VkBuffer created with pname:usage member of pname:pCreateInfo 83 containing bits in 84 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseBufferUsageFlags 85 and sname:VkImage created with pname:usage member of pname:pCreateInfo 86 containing bits in 87 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseImageUsageFlags, 88 to exceed sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 89 * [[VUID-vkCreateBuffer-flags-09384]] 90 If the pname:flags member of pname:pCreateInfo includes 91 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT and the 92 <<features-extendedSparseAddressSpace, 93 pname:extendedSparseAddressSpace>> feature is enabled, creating this 94 sname:VkBuffer must: not cause the total required sparse memory for all 95 currently valid sparse resources on the device to exceed 96 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseAddressSpaceSize 97endif::VK_NV_extended_sparse_address_space[] 98endif::VKSC_VERSION_1_0[] 99include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 100ifdef::VK_FUCHSIA_buffer_collection[] 101 * [[VUID-vkCreateBuffer-pNext-06387]] 102 If using the slink:VkBuffer for an import operation from a 103 slink:VkBufferCollectionFUCHSIA where a 104 slink:VkBufferCollectionBufferCreateInfoFUCHSIA has been chained to 105 pname:pNext, pname:pCreateInfo must: match the 106 slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo used when setting 107 the constraints on the buffer collection with 108 flink:vkSetBufferCollectionBufferConstraintsFUCHSIA 109endif::VK_FUCHSIA_buffer_collection[] 110**** 111 112include::{generated}/validity/protos/vkCreateBuffer.adoc[] 113-- 114 115[open,refpage='VkBufferCreateInfo',desc='Structure specifying the parameters of a newly created buffer object',type='structs'] 116-- 117:refpage: VkBufferCreateInfo 118 119The sname:VkBufferCreateInfo structure is defined as: 120 121include::{generated}/api/structs/VkBufferCreateInfo.adoc[] 122 123 * pname:sType is a elink:VkStructureType value identifying this structure. 124 * pname:pNext is `NULL` or a pointer to a structure extending this 125 structure. 126 * pname:flags is a bitmask of elink:VkBufferCreateFlagBits specifying 127 additional parameters of the buffer. 128 * pname:size is the size in bytes of the buffer to be created. 129 * pname:usage is a bitmask of elink:VkBufferUsageFlagBits specifying 130 allowed usages of the buffer. 131 * pname:sharingMode is a elink:VkSharingMode value specifying the sharing 132 mode of the buffer when it will be accessed by multiple queue families. 133 * pname:queueFamilyIndexCount is the number of entries in the 134 pname:pQueueFamilyIndices array. 135 * pname:pQueueFamilyIndices is a pointer to an array of queue families 136 that will access this buffer. 137 It is ignored if pname:sharingMode is not 138 ename:VK_SHARING_MODE_CONCURRENT. 139 140ifdef::VK_KHR_maintenance5[] 141If a slink:VkBufferUsageFlags2CreateInfoKHR structure is present in the 142pname:pNext chain, slink:VkBufferUsageFlags2CreateInfoKHR::pname:usage from 143that structure is used instead of pname:usage from this structure. 144endif::VK_KHR_maintenance5[] 145 146.Valid Usage 147**** 148include::{chapters}/commonvalidity/buffer_usage_flags_common.adoc[] 149 * [[VUID-VkBufferCreateInfo-size-00912]] 150 pname:size must: be greater than `0` 151 * [[VUID-VkBufferCreateInfo-sharingMode-00913]] 152 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 153 pname:pQueueFamilyIndices must: be a valid pointer to an array of 154 pname:queueFamilyIndexCount code:uint32_t values 155 * [[VUID-VkBufferCreateInfo-sharingMode-00914]] 156 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 157 pname:queueFamilyIndexCount must: be greater than `1` 158 * [[VUID-VkBufferCreateInfo-sharingMode-01419]] 159 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 160 of pname:pQueueFamilyIndices must: be unique and must: be less than 161 pname:pQueueFamilyPropertyCount returned by 162ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 163 either flink:vkGetPhysicalDeviceQueueFamilyProperties2 or 164endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 165 flink:vkGetPhysicalDeviceQueueFamilyProperties for the 166 pname:physicalDevice that was used to create pname:device 167 * [[VUID-VkBufferCreateInfo-flags-00915]] 168ifndef::VKSC_VERSION_1_0[] 169 If the <<features-sparseBinding, pname:sparseBinding>> feature is not 170 enabled, 171endif::VKSC_VERSION_1_0[] 172 pname:flags must: not contain ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT 173 * [[VUID-VkBufferCreateInfo-flags-00916]] 174ifndef::VKSC_VERSION_1_0[] 175 If the <<features-sparseResidencyBuffer, pname:sparseResidencyBuffer>> 176 feature is not enabled, 177endif::VKSC_VERSION_1_0[] 178 pname:flags must: not contain 179 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT 180 * [[VUID-VkBufferCreateInfo-flags-00917]] 181ifndef::VKSC_VERSION_1_0[] 182 If the <<features-sparseResidencyAliased, pname:sparseResidencyAliased>> 183 feature is not enabled, 184endif::VKSC_VERSION_1_0[] 185 pname:flags must: not contain ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT 186ifndef::VKSC_VERSION_1_0[] 187 * [[VUID-VkBufferCreateInfo-flags-00918]] 188 If pname:flags contains ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or 189 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT, it must: also contain 190 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT 191endif::VKSC_VERSION_1_0[] 192ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 193 * [[VUID-VkBufferCreateInfo-pNext-00920]] 194 If the pname:pNext chain includes a 195 slink:VkExternalMemoryBufferCreateInfo structure, its pname:handleTypes 196 member must: only contain bits that are also in 197 slink:VkExternalBufferProperties::pname:externalMemoryProperties.compatibleHandleTypes, 198 as returned by flink:vkGetPhysicalDeviceExternalBufferProperties with 199 pname:pExternalBufferInfo->handleType equal to any one of the handle 200 types specified in 201 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes 202endif::VK_VERSION_1_1,VK_KHR_external_memory[] 203ifdef::VK_VERSION_1_1[] 204 * [[VUID-VkBufferCreateInfo-flags-01887]] 205 If the <<features-protectedMemory, pname:protectedMemory>> feature is 206 not enabled, pname:flags must: not contain 207 ename:VK_BUFFER_CREATE_PROTECTED_BIT 208ifndef::VKSC_VERSION_1_0[] 209 * [[VUID-VkBufferCreateInfo-None-01888]] 210 If any of the bits ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 211 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or 212 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set, 213 ename:VK_BUFFER_CREATE_PROTECTED_BIT must: not also be set 214endif::VKSC_VERSION_1_0[] 215endif::VK_VERSION_1_1[] 216ifdef::VK_NV_dedicated_allocation[] 217 * [[VUID-VkBufferCreateInfo-pNext-01571]] 218 If the pname:pNext chain includes a 219 slink:VkDedicatedAllocationBufferCreateInfoNV structure, and the 220 pname:dedicatedAllocation member of the chained structure is 221 ename:VK_TRUE, then pname:flags must: not include 222 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 223 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or 224 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT 225endif::VK_NV_dedicated_allocation[] 226ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 227ifdef::VK_EXT_buffer_device_address[] 228 * [[VUID-VkBufferCreateInfo-deviceAddress-02604]] 229 If slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress is not 230 zero, pname:flags must: include 231 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT 232endif::VK_EXT_buffer_device_address[] 233ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 234 * [[VUID-VkBufferCreateInfo-opaqueCaptureAddress-03337]] 235 If 236 slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 237 is not zero, pname:flags must: include 238 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT 239endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 240 * [[VUID-VkBufferCreateInfo-flags-03338]] 241 If pname:flags includes 242 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the 243ifndef::VK_EXT_buffer_device_address[] 244 <<features-bufferDeviceAddressCaptureReplay, 245 pname:bufferDeviceAddressCaptureReplay>> feature 246endif::VK_EXT_buffer_device_address[] 247ifdef::VK_EXT_buffer_device_address[] 248 <<features-bufferDeviceAddressCaptureReplayEXT, 249 pname:bufferDeviceAddressCaptureReplay>> feature 250endif::VK_EXT_buffer_device_address[] 251 must: be enabled 252endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 253ifdef::VK_KHR_video_decode_queue[] 254 * [[VUID-VkBufferCreateInfo-usage-04813]] 255 If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR 256 or ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, 257ifdef::VK_KHR_video_maintenance1[] 258 and pname:flags does not include 259 ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, 260endif::VK_KHR_video_maintenance1[] 261 then the pname:pNext chain must: include a 262 slink:VkVideoProfileListInfoKHR structure with pname:profileCount 263 greater than `0` and pname:pProfiles including at least one 264 slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation 265 member specifying a decode operation 266endif::VK_KHR_video_decode_queue[] 267ifdef::VK_KHR_video_encode_queue[] 268 * [[VUID-VkBufferCreateInfo-usage-04814]] 269 If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR 270 or ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 271ifdef::VK_KHR_video_maintenance1[] 272 and pname:flags does not include 273 ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, 274endif::VK_KHR_video_maintenance1[] 275 then the pname:pNext chain must: include a 276 slink:VkVideoProfileListInfoKHR structure with pname:profileCount 277 greater than `0` and pname:pProfiles including at least one 278 slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation 279 member specifying an encode operation 280endif::VK_KHR_video_encode_queue[] 281ifdef::VK_KHR_video_maintenance1[] 282 * [[VUID-VkBufferCreateInfo-flags-08325]] 283 If pname:flags includes 284 ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then 285 <<features-videoMaintenance1,pname:videoMaintenance1>> must: be enabled 286endif::VK_KHR_video_maintenance1[] 287ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 288 * [[VUID-VkBufferCreateInfo-size-06409]] 289 pname:size must: be less than or equal to 290 slink:VkPhysicalDeviceMaintenance4Properties::pname:maxBufferSize 291endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 292ifdef::VK_EXT_descriptor_buffer[] 293 * [[VUID-VkBufferCreateInfo-usage-08097]] 294 If pname:usage includes 295 ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT, creating this 296 sname:VkBuffer must: not cause the total required space for all 297 currently valid buffers using this flag on the device to exceed 298 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:samplerDescriptorBufferAddressSpaceSize 299 or 300 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferAddressSpaceSize 301 * [[VUID-VkBufferCreateInfo-usage-08098]] 302 If pname:usage includes 303 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT, creating this 304 sname:VkBuffer must: not cause the total required space for all 305 currently valid buffers using this flag on the device to exceed 306 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:resourceDescriptorBufferAddressSpaceSize 307 or 308 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferAddressSpaceSize 309 * [[VUID-VkBufferCreateInfo-flags-08099]] 310 If pname:flags includes 311 ename:VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the 312 <<features-descriptorBufferCaptureReplay, 313 pname:descriptorBufferCaptureReplay>> feature must: be enabled 314 * [[VUID-VkBufferCreateInfo-pNext-08100]] 315 If the pname:pNext chain includes a 316 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, pname:flags 317 must: contain 318 ename:VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 319 * [[VUID-VkBufferCreateInfo-usage-08101]] 320 If pname:usage includes 321 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, the 322 <<features-descriptorBufferPushDescriptors, 323 pname:descriptorBufferPushDescriptors>> feature must: be enabled 324 * [[VUID-VkBufferCreateInfo-usage-08102]] 325 If pname:usage includes 326 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT 327 <<limits-bufferlessPushDescriptors, 328 sname:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferlessPushDescriptors>> 329 must: be ename:VK_FALSE 330 * [[VUID-VkBufferCreateInfo-usage-08103]] 331 If pname:usage includes 332 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, 333 pname:usage must: contain at least one of 334 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT or 335 ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT 336endif::VK_EXT_descriptor_buffer[] 337**** 338ifdef::VKSC_VERSION_1_0[] 339ifdef::hidden[] 340// tag::scdeviation[] 341 * slink:VkBufferCreateInfo::pname:flags must: not contain any of the 342 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, 343 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or 344 ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT flags <<SCID-8>>. 345// end::scdeviation[] 346endif::hidden[] 347endif::VKSC_VERSION_1_0[] 348 349include::{generated}/validity/structs/VkBufferCreateInfo.adoc[] 350-- 351 352ifdef::VK_KHR_maintenance5[] 353[open,refpage='VkBufferUsageFlags2CreateInfoKHR',desc='Extended buffer usage flags',type='structs'] 354-- 355The sname:VkBufferUsageFlags2CreateInfoKHR structure is defined as: 356 357include::{generated}/api/structs/VkBufferUsageFlags2CreateInfoKHR.adoc[] 358 359 * pname:sType is a elink:VkStructureType value identifying this structure. 360 * pname:pNext is `NULL` or a pointer to a structure extending this 361 structure. 362 * pname:usage is a bitmask of elink:VkBufferUsageFlagBits2KHR specifying 363 allowed usages of the buffer. 364 365If this structure is included in the pname:pNext chain of a buffer creation 366structure, pname:usage is used instead of the corresponding pname:usage 367value passed in that creation structure, allowing additional usage flags to 368be specified. 369If this structure is included in the pname:pNext chain of a buffer query 370structure, the usage flags of the buffer are returned in pname:usage of this 371structure, and the usage flags representable in pname:usage of the buffer 372query structure are also returned in that field. 373 374include::{generated}/validity/structs/VkBufferUsageFlags2CreateInfoKHR.adoc[] 375-- 376 377[open,refpage='VkBufferUsageFlagBits2KHR',desc='Bitmask controlling how a pipeline is created',type='enums'] 378-- 379Bits which can: be set in 380slink:VkBufferUsageFlags2CreateInfoKHR::pname:usage, specifying usage 381behavior of a buffer, are: 382 383include::{generated}/api/enums/VkBufferUsageFlagBits2KHR.adoc[] 384 385// Note - when editing this section, make sure that any relevant changes 386// are mirrored in VkBufferUsageFlagBits2KHR/VkBufferUsageFlagBits 387 388 * ename:VK_BUFFER_USAGE_2_TRANSFER_SRC_BIT_KHR specifies that the buffer 389 can: be used as the source of a _transfer command_ (see the definition 390 of <<synchronization-pipeline-stages-transfer, 391 ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). 392 * ename:VK_BUFFER_USAGE_2_TRANSFER_DST_BIT_KHR specifies that the buffer 393 can: be used as the destination of a transfer command. 394 * ename:VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR specifies that the 395 buffer can: be used to create a sname:VkBufferView suitable for 396 occupying a sname:VkDescriptorSet slot of type 397 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. 398 * ename:VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR specifies that the 399 buffer can: be used to create a sname:VkBufferView suitable for 400 occupying a sname:VkDescriptorSet slot of type 401 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. 402 * ename:VK_BUFFER_USAGE_2_UNIFORM_BUFFER_BIT_KHR specifies that the buffer 403 can: be used in a sname:VkDescriptorBufferInfo suitable for occupying a 404 sname:VkDescriptorSet slot either of type 405 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 406 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. 407 * ename:VK_BUFFER_USAGE_2_STORAGE_BUFFER_BIT_KHR specifies that the buffer 408 can: be used in a sname:VkDescriptorBufferInfo suitable for occupying a 409 sname:VkDescriptorSet slot either of type 410 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 411 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. 412 * ename:VK_BUFFER_USAGE_2_INDEX_BUFFER_BIT_KHR specifies that the buffer 413 is suitable for passing as the pname:buffer parameter to 414ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR and] 415 flink:vkCmdBindIndexBuffer. 416 * ename:VK_BUFFER_USAGE_2_VERTEX_BUFFER_BIT_KHR specifies that the buffer 417 is suitable for passing as an element of the pname:pBuffers array to 418 flink:vkCmdBindVertexBuffers. 419 * ename:VK_BUFFER_USAGE_2_INDIRECT_BUFFER_BIT_KHR specifies that the 420 buffer is suitable for passing as the pname:buffer parameter to 421 flink:vkCmdDrawIndirect, flink:vkCmdDrawIndexedIndirect, 422ifdef::VK_NV_mesh_shader[] 423 flink:vkCmdDrawMeshTasksIndirectNV, 424 flink:vkCmdDrawMeshTasksIndirectCountNV, 425endif::VK_NV_mesh_shader[] 426ifdef::VK_EXT_mesh_shader[] 427 fname:vkCmdDrawMeshTasksIndirectEXT, 428 fname:vkCmdDrawMeshTasksIndirectCountEXT, 429endif::VK_EXT_mesh_shader[] 430ifdef::VK_HUAWEI_cluster_culling_shader[] 431 flink:vkCmdDrawClusterIndirectHUAWEI, 432endif::VK_HUAWEI_cluster_culling_shader[] 433 or flink:vkCmdDispatchIndirect. 434ifdef::VK_NV_device_generated_commands[] 435 It is also suitable for passing as the pname:buffer member of 436 sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or 437 pname:sequencesIndexBuffer or pname:preprocessedBuffer member of 438 sname:VkGeneratedCommandsInfoNV 439endif::VK_NV_device_generated_commands[] 440ifdef::VK_EXT_conditional_rendering[] 441 * ename:VK_BUFFER_USAGE_2_CONDITIONAL_RENDERING_BIT_EXT specifies that the 442 buffer is suitable for passing as the pname:buffer parameter to 443 flink:vkCmdBeginConditionalRenderingEXT. 444endif::VK_EXT_conditional_rendering[] 445ifdef::VK_EXT_transform_feedback[] 446 * ename:VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that 447 the buffer is suitable for using for binding as a transform feedback 448 buffer with flink:vkCmdBindTransformFeedbackBuffersEXT. 449 * ename:VK_BUFFER_USAGE_2_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT 450 specifies that the buffer is suitable for using as a counter buffer with 451 flink:vkCmdBeginTransformFeedbackEXT and 452 flink:vkCmdEndTransformFeedbackEXT. 453endif::VK_EXT_transform_feedback[] 454ifdef::VK_EXT_descriptor_buffer[] 455 * ename:VK_BUFFER_USAGE_2_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT specifies that 456 the buffer is suitable to contain sampler and combined image sampler 457 descriptors when bound as a descriptor buffer. 458 Buffers containing combined image sampler descriptors must: also specify 459 ename:VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. 460 * ename:VK_BUFFER_USAGE_2_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT specifies 461 that the buffer is suitable to contain resource descriptors when bound 462 as a descriptor buffer. 463 * ename:VK_BUFFER_USAGE_2_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT 464 specifies that the buffer, when bound, can: be used by the 465 implementation to support push descriptors when using descriptor 466 buffers. 467endif::VK_EXT_descriptor_buffer[] 468ifdef::VK_NV_ray_tracing[] 469 * ename:VK_BUFFER_USAGE_2_RAY_TRACING_BIT_NV specifies that the buffer is 470 suitable for use in flink:vkCmdTraceRaysNV. 471endif::VK_NV_ray_tracing[] 472ifdef::VK_KHR_ray_tracing_pipeline[] 473 * ename:VK_BUFFER_USAGE_2_SHADER_BINDING_TABLE_BIT_KHR specifies that the 474 buffer is suitable for use as a <<shader-binding-table,Shader Binding 475 Table>>. 476endif::VK_KHR_ray_tracing_pipeline[] 477ifdef::VK_KHR_acceleration_structure[] 478 * ename:VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR 479 specifies that the buffer is suitable for use as a read-only input to an 480 <<acceleration-structure-building,acceleration structure build>>. 481 * ename:VK_BUFFER_USAGE_2_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies 482 that the buffer is suitable for storage space for a 483 slink:VkAccelerationStructureKHR. 484endif::VK_KHR_acceleration_structure[] 485ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 486 * ename:VK_BUFFER_USAGE_2_SHADER_DEVICE_ADDRESS_BIT_KHR specifies that the 487 buffer can: be used to retrieve a buffer device address via 488 flink:vkGetBufferDeviceAddress and use that address to access the 489 buffer's memory from a shader. 490endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 491ifdef::VK_KHR_video_decode_queue[] 492 * ename:VK_BUFFER_USAGE_2_VIDEO_DECODE_SRC_BIT_KHR specifies that the 493 buffer can: be used as the source video bitstream buffer in a 494 <<video-decode-operations, video decode operation>>. 495 * ename:VK_BUFFER_USAGE_2_VIDEO_DECODE_DST_BIT_KHR is reserved for future 496 use. 497endif::VK_KHR_video_decode_queue[] 498ifdef::VK_KHR_video_encode_queue[] 499 * ename:VK_BUFFER_USAGE_2_VIDEO_ENCODE_DST_BIT_KHR specifies that the 500 buffer can: be used as the destination video bitstream buffer in a 501 <<video-encode-operations, video encode operation>>. 502 * ename:VK_BUFFER_USAGE_2_VIDEO_ENCODE_SRC_BIT_KHR is reserved for future 503 use. 504endif::VK_KHR_video_encode_queue[] 505ifdef::VK_AMDX_shader_enqueue[] 506 * ename:VK_BUFFER_USAGE_2_EXECUTION_GRAPH_SCRATCH_BIT_AMDX specifies that 507 the buffer can: be used for as scratch memory for 508 <<executiongraphs,execution graph dispatch>>. 509endif::VK_AMDX_shader_enqueue[] 510-- 511 512[open,refpage='VkBufferUsageFlags2KHR',desc='Bitmask of VkBufferUsageFlagBits2KHR',type='flags'] 513-- 514include::{generated}/api/flags/VkBufferUsageFlags2KHR.adoc[] 515 516tname:VkBufferUsageFlags2KHR is a bitmask type for setting a mask of zero or 517more elink:VkBufferUsageFlagBits2KHR. 518-- 519endif::VK_KHR_maintenance5[] 520 521[open,refpage='VkBufferUsageFlagBits',desc='Bitmask specifying allowed usage of a buffer',type='enums'] 522-- 523Bits which can: be set in slink:VkBufferCreateInfo::pname:usage, specifying 524usage behavior of a buffer, are: 525 526include::{generated}/api/enums/VkBufferUsageFlagBits.adoc[] 527 528// Note - when editing this section, make sure that any relevant changes 529// are mirrored in VkBufferUsageFlagBits2KHR/VkBufferUsageFlagBits 530 531 * ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT specifies that the buffer can: be 532 used as the source of a _transfer command_ (see the definition of 533 <<synchronization-pipeline-stages-transfer, 534 ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). 535 * ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT specifies that the buffer can: be 536 used as the destination of a transfer command. 537 * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT specifies that the buffer 538 can: be used to create a sname:VkBufferView suitable for occupying a 539 sname:VkDescriptorSet slot of type 540 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. 541 * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT specifies that the buffer 542 can: be used to create a sname:VkBufferView suitable for occupying a 543 sname:VkDescriptorSet slot of type 544 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. 545 * ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT specifies that the buffer can: 546 be used in a sname:VkDescriptorBufferInfo suitable for occupying a 547 sname:VkDescriptorSet slot either of type 548 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 549 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. 550 * ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT specifies that the buffer can: 551 be used in a sname:VkDescriptorBufferInfo suitable for occupying a 552 sname:VkDescriptorSet slot either of type 553 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 554 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. 555 * ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT specifies that the buffer is 556 suitable for passing as the pname:buffer parameter to 557ifdef::VK_KHR_maintenance5[flink:vkCmdBindIndexBuffer2KHR and] 558 flink:vkCmdBindIndexBuffer. 559 * ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT specifies that the buffer is 560 suitable for passing as an element of the pname:pBuffers array to 561 flink:vkCmdBindVertexBuffers. 562 * ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is 563 suitable for passing as the pname:buffer parameter to 564 flink:vkCmdDrawIndirect, flink:vkCmdDrawIndexedIndirect, 565ifdef::VK_NV_mesh_shader[] 566 flink:vkCmdDrawMeshTasksIndirectNV, 567 flink:vkCmdDrawMeshTasksIndirectCountNV, 568endif::VK_NV_mesh_shader[] 569ifdef::VK_EXT_mesh_shader[] 570 fname:vkCmdDrawMeshTasksIndirectEXT, 571 fname:vkCmdDrawMeshTasksIndirectCountEXT, 572endif::VK_EXT_mesh_shader[] 573ifdef::VK_HUAWEI_cluster_culling_shader[] 574 flink:vkCmdDrawClusterIndirectHUAWEI, 575endif::VK_HUAWEI_cluster_culling_shader[] 576 or flink:vkCmdDispatchIndirect. 577ifdef::VK_NV_device_generated_commands[] 578 It is also suitable for passing as the pname:buffer member of 579 sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or 580 pname:sequencesIndexBuffer or pname:preprocessedBuffer member of 581 sname:VkGeneratedCommandsInfoNV 582endif::VK_NV_device_generated_commands[] 583ifdef::VK_EXT_conditional_rendering[] 584 * ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the 585 buffer is suitable for passing as the pname:buffer parameter to 586 flink:vkCmdBeginConditionalRenderingEXT. 587endif::VK_EXT_conditional_rendering[] 588ifdef::VK_EXT_transform_feedback[] 589 * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that 590 the buffer is suitable for using for binding as a transform feedback 591 buffer with flink:vkCmdBindTransformFeedbackBuffersEXT. 592 * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT 593 specifies that the buffer is suitable for using as a counter buffer with 594 flink:vkCmdBeginTransformFeedbackEXT and 595 flink:vkCmdEndTransformFeedbackEXT. 596endif::VK_EXT_transform_feedback[] 597ifdef::VK_EXT_descriptor_buffer[] 598 * ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT specifies that 599 the buffer is suitable to contain sampler and combined image sampler 600 descriptors when bound as a descriptor buffer. 601 Buffers containing combined image sampler descriptors must: also specify 602 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT. 603 * ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT specifies that 604 the buffer is suitable to contain resource descriptors when bound as a 605 descriptor buffer. 606 * ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT 607 specifies that the buffer, when bound, can: be used by the 608 implementation to support push descriptors when using descriptor 609 buffers. 610endif::VK_EXT_descriptor_buffer[] 611ifdef::VK_NV_ray_tracing[] 612 * ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV specifies that the buffer is 613 suitable for use in flink:vkCmdTraceRaysNV. 614endif::VK_NV_ray_tracing[] 615ifdef::VK_KHR_ray_tracing_pipeline[] 616 * ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR specifies that the 617 buffer is suitable for use as a <<shader-binding-table,Shader Binding 618 Table>>. 619endif::VK_KHR_ray_tracing_pipeline[] 620ifdef::VK_KHR_acceleration_structure[] 621 * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR 622 specifies that the buffer is suitable for use as a read-only input to an 623 <<acceleration-structure-building,acceleration structure build>>. 624 * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies 625 that the buffer is suitable for storage space for a 626 slink:VkAccelerationStructureKHR. 627endif::VK_KHR_acceleration_structure[] 628ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 629 * ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT specifies that the 630 buffer can: be used to retrieve a buffer device address via 631 flink:vkGetBufferDeviceAddress and use that address to access the 632 buffer's memory from a shader. 633endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 634ifdef::VK_KHR_video_decode_queue[] 635 * ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer 636 can: be used as the source video bitstream buffer in a 637 <<video-decode-operations, video decode operation>>. 638 * ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR is reserved for future 639 use. 640endif::VK_KHR_video_decode_queue[] 641ifdef::VK_KHR_video_encode_queue[] 642 * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer 643 can: be used as the destination video bitstream buffer in a 644 <<video-encode-operations, video encode operation>>. 645 * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR is reserved for future 646 use. 647endif::VK_KHR_video_encode_queue[] 648ifdef::VK_AMDX_shader_enqueue[] 649 * ename:VK_BUFFER_USAGE_EXECUTION_GRAPH_SCRATCH_BIT_AMDX specifies that 650 the buffer can: be used for as scratch memory for 651 <<executiongraphs,execution graph dispatch>>. 652endif::VK_AMDX_shader_enqueue[] 653-- 654 655[open,refpage='VkBufferUsageFlags',desc='Bitmask of VkBufferUsageFlagBits',type='flags'] 656-- 657include::{generated}/api/flags/VkBufferUsageFlags.adoc[] 658 659tname:VkBufferUsageFlags is a bitmask type for setting a mask of zero or 660more elink:VkBufferUsageFlagBits. 661-- 662 663[open,refpage='VkBufferCreateFlagBits',desc='Bitmask specifying additional parameters of a buffer',type='enums'] 664-- 665Bits which can: be set in slink:VkBufferCreateInfo::pname:flags, specifying 666additional parameters of a buffer, are: 667 668include::{generated}/api/enums/VkBufferCreateFlagBits.adoc[] 669 670 * ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will 671 be backed using sparse memory binding. 672ifdef::VKSC_VERSION_1_0[] 673 This flag is not supported in Vulkan SC <<SCID-8>>. 674endif::VKSC_VERSION_1_0[] 675 * ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer 676 can: be partially backed using sparse memory binding. 677 Buffers created with this flag must: also be created with the 678 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. 679ifdef::VKSC_VERSION_1_0[] 680 This flag is not supported in Vulkan SC <<SCID-8>>. 681endif::VKSC_VERSION_1_0[] 682 * ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will 683 be backed using sparse memory binding with memory ranges that might also 684 simultaneously be backing another buffer (or another portion of the same 685 buffer). 686 Buffers created with this flag must: also be created with the 687 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. 688ifdef::VKSC_VERSION_1_0[] 689 This flag is not supported in Vulkan SC <<SCID-8>>. 690endif::VKSC_VERSION_1_0[] 691ifdef::VK_VERSION_1_1[] 692 * ename:VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a 693 protected buffer. 694endif::VK_VERSION_1_1[] 695ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 696 * ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that 697 the buffer's address can: be saved and reused on a subsequent run (e.g. 698 for trace capture and replay), see 699 slink:VkBufferOpaqueCaptureAddressCreateInfo for more detail. 700endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 701ifdef::VK_EXT_descriptor_buffer[] 702 * ename:VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 703 specifies that the buffer can: be used with descriptor buffers when 704 capturing and replaying (e.g. for trace capture and replay), see 705 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. 706endif::VK_EXT_descriptor_buffer[] 707ifdef::VK_KHR_video_maintenance1[] 708 * ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that 709 the buffer can: be used in <<video-coding,video coding operations>> 710 without having to specify at buffer creation time the set of video 711 profiles the buffer will be used with. 712endif::VK_KHR_video_maintenance1[] 713 714See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and 715<<features, Physical Device Features>> for details of the sparse memory 716features supported on a device. 717-- 718 719[open,refpage='VkBufferCreateFlags',desc='Bitmask of VkBufferCreateFlagBits',type='flags'] 720-- 721include::{generated}/api/flags/VkBufferCreateFlags.adoc[] 722 723tname:VkBufferCreateFlags is a bitmask type for setting a mask of zero or 724more elink:VkBufferCreateFlagBits. 725-- 726 727ifdef::VK_NV_dedicated_allocation[] 728[open,refpage='VkDedicatedAllocationBufferCreateInfoNV',desc='Specify that a buffer is bound to a dedicated memory resource',type='structs'] 729-- 730If the pname:pNext chain includes a 731sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure 732includes an enable controlling whether the buffer will have a dedicated 733memory allocation bound to it. 734 735The sname:VkDedicatedAllocationBufferCreateInfoNV structure is defined as: 736 737include::{generated}/api/structs/VkDedicatedAllocationBufferCreateInfoNV.adoc[] 738 739 * pname:sType is a elink:VkStructureType value identifying this structure. 740 * pname:pNext is `NULL` or a pointer to a structure extending this 741 structure. 742 * pname:dedicatedAllocation specifies whether the buffer will have a 743 dedicated allocation bound to it. 744 745include::{generated}/validity/structs/VkDedicatedAllocationBufferCreateInfoNV.adoc[] 746-- 747endif::VK_NV_dedicated_allocation[] 748 749ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 750[open,refpage='VkExternalMemoryBufferCreateInfo',desc='Specify that a buffer may be backed by external memory',type='structs'] 751-- 752To define a set of external memory handle types that may: be used as backing 753store for a buffer, add a slink:VkExternalMemoryBufferCreateInfo structure 754to the pname:pNext chain of the slink:VkBufferCreateInfo structure. 755The sname:VkExternalMemoryBufferCreateInfo structure is defined as: 756 757include::{generated}/api/structs/VkExternalMemoryBufferCreateInfo.adoc[] 758 759ifdef::VK_KHR_external_memory[] 760or the equivalent 761 762include::{generated}/api/structs/VkExternalMemoryBufferCreateInfoKHR.adoc[] 763endif::VK_KHR_external_memory[] 764 765[NOTE] 766.Note 767==== 768A sname:VkExternalMemoryBufferCreateInfo structure with a non-zero 769pname:handleTypes field must be included in the creation parameters for a 770buffer that will be bound to memory that is either exported or imported. 771==== 772 773 * pname:sType is a elink:VkStructureType value identifying this structure. 774 * pname:pNext is `NULL` or a pointer to a structure extending this 775 structure. 776 * pname:handleTypes is zero or a bitmask of 777 elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external 778 memory handle types. 779 780include::{generated}/validity/structs/VkExternalMemoryBufferCreateInfo.adoc[] 781-- 782endif::VK_VERSION_1_1,VK_KHR_external_memory[] 783 784ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 785[open,refpage='VkBufferOpaqueCaptureAddressCreateInfo',desc='Request a specific address for a buffer',type='structs',alias='VkBufferOpaqueCaptureAddressCreateInfoKHR'] 786-- 787To request a specific device address for a buffer, add a 788slink:VkBufferOpaqueCaptureAddressCreateInfo structure to the pname:pNext 789chain of the slink:VkBufferCreateInfo structure. 790The sname:VkBufferOpaqueCaptureAddressCreateInfo structure is defined as: 791 792include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfo.adoc[] 793 794ifdef::VK_KHR_buffer_device_address[] 795or the equivalent 796 797include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfoKHR.adoc[] 798endif::VK_KHR_buffer_device_address[] 799 800 * pname:sType is a elink:VkStructureType value identifying this structure. 801 * pname:pNext is `NULL` or a pointer to a structure extending this 802 structure. 803 * pname:opaqueCaptureAddress is the opaque capture address requested for 804 the buffer. 805 806If pname:opaqueCaptureAddress is zero, no specific address is requested. 807 808If pname:opaqueCaptureAddress is not zero, then it should: be an address 809retrieved from flink:vkGetBufferOpaqueCaptureAddress for an identically 810created buffer on the same implementation. 811 812If this structure is not present, it is as if pname:opaqueCaptureAddress is 813zero. 814 815Apps should: avoid creating buffers with app-provided addresses and 816implementation-provided addresses in the same process, to reduce the 817likelihood of ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors. 818 819[NOTE] 820.Note 821==== 822The expected usage for this is that a trace capture/replay tool will add the 823ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers 824that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and during capture 825will save the queried opaque device addresses in the trace. 826During replay, the buffers will be created specifying the original address 827so any address values stored in the trace data will remain valid. 828 829Implementations are expected to separate such buffers in the GPU address 830space so normal allocations will avoid using these addresses. 831Apps/tools should avoid mixing app-provided and implementation-provided 832addresses for buffers created with 833ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address 834space allocation conflicts. 835==== 836 837include::{generated}/validity/structs/VkBufferOpaqueCaptureAddressCreateInfo.adoc[] 838-- 839endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 840 841ifdef::VK_EXT_buffer_device_address[] 842[open,refpage='VkBufferDeviceAddressCreateInfoEXT',desc='Request a specific address for a buffer',type='structs'] 843-- 844ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 845Alternatively, to 846endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 847ifndef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 848To 849endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 850request a specific device address for a buffer, add a 851slink:VkBufferDeviceAddressCreateInfoEXT structure to the pname:pNext chain 852of the slink:VkBufferCreateInfo structure. 853The sname:VkBufferDeviceAddressCreateInfoEXT structure is defined as: 854 855include::{generated}/api/structs/VkBufferDeviceAddressCreateInfoEXT.adoc[] 856 857 * pname:sType is a elink:VkStructureType value identifying this structure. 858 * pname:pNext is `NULL` or a pointer to a structure extending this 859 structure. 860 * pname:deviceAddress is the device address requested for the buffer. 861 862If pname:deviceAddress is zero, no specific address is requested. 863 864If pname:deviceAddress is not zero, then it must: be an address retrieved 865from an identically created buffer on the same implementation. 866The buffer must: also be bound to an identically created 867sname:VkDeviceMemory object. 868 869If this structure is not present, it is as if pname:deviceAddress is zero. 870 871Apps should: avoid creating buffers with app-provided addresses and 872implementation-provided addresses in the same process, to reduce the 873likelihood of ename:VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors. 874 875include::{generated}/validity/structs/VkBufferDeviceAddressCreateInfoEXT.adoc[] 876-- 877endif::VK_EXT_buffer_device_address[] 878 879 880ifdef::VK_FUCHSIA_buffer_collection[] 881[open,refpage='VkBufferCollectionBufferCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkBuffer',type='structs'] 882-- 883The sname:VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as: 884 885include::{generated}/api/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.adoc[] 886 887 * pname:sType is a elink:VkStructureType value identifying this structure. 888 * pname:pNext is `NULL` or a pointer to a structure extending this 889 structure 890 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 891 * pname:index is the index of the buffer in the buffer collection from 892 which the memory will be imported 893 894.Valid Usage 895**** 896 * [[VUID-VkBufferCollectionBufferCreateInfoFUCHSIA-index-06388]] 897 pname:index must: be less than 898 slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount 899**** 900 901include::{generated}/validity/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.adoc[] 902-- 903endif::VK_FUCHSIA_buffer_collection[] 904 905[open,refpage='vkDestroyBuffer',desc='Destroy a buffer object',type='protos'] 906-- 907To destroy a buffer, call: 908 909include::{generated}/api/protos/vkDestroyBuffer.adoc[] 910 911 * pname:device is the logical device that destroys the buffer. 912 * pname:buffer is the buffer to destroy. 913 * pname:pAllocator controls host memory allocation as described in the 914 <<memory-allocation, Memory Allocation>> chapter. 915 916.Valid Usage 917**** 918 * [[VUID-vkDestroyBuffer-buffer-00922]] 919 All submitted commands that refer to pname:buffer, either directly or 920 via a sname:VkBufferView, must: have completed execution 921ifndef::VKSC_VERSION_1_0[] 922 * [[VUID-vkDestroyBuffer-buffer-00923]] 923 If sname:VkAllocationCallbacks were provided when pname:buffer was 924 created, a compatible set of callbacks must: be provided here 925 * [[VUID-vkDestroyBuffer-buffer-00924]] 926 If no sname:VkAllocationCallbacks were provided when pname:buffer was 927 created, pname:pAllocator must: be `NULL` 928endif::VKSC_VERSION_1_0[] 929**** 930 931include::{generated}/validity/protos/vkDestroyBuffer.adoc[] 932-- 933 934 935[[resources-buffer-views]] 936== Buffer Views 937 938[open,refpage='VkBufferView',desc='Opaque handle to a buffer view object',type='handles'] 939-- 940A _buffer view_ represents a contiguous range of a buffer and a specific 941format to be used to interpret the data. 942Buffer views are used to enable shaders to access buffer contents using 943<<textures,image operations>>. 944In order to create a valid buffer view, the buffer must: have been created 945with at least one of the following usage flags: 946 947 * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT 948 * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT 949 950Buffer views are represented by sname:VkBufferView handles: 951 952include::{generated}/api/handles/VkBufferView.adoc[] 953-- 954 955[open,refpage='vkCreateBufferView',desc='Create a new buffer view object',type='protos'] 956-- 957:refpage: vkCreateBufferView 958:objectnameplural: buffer views 959:objectnamecamelcase: bufferView 960:objectcount: 1 961 962To create a buffer view, call: 963 964include::{generated}/api/protos/vkCreateBufferView.adoc[] 965 966 * pname:device is the logical device that creates the buffer view. 967 * pname:pCreateInfo is a pointer to a slink:VkBufferViewCreateInfo 968 structure containing parameters to be used to create the buffer view. 969 * pname:pAllocator controls host memory allocation as described in the 970 <<memory-allocation, Memory Allocation>> chapter. 971 * pname:pView is a pointer to a slink:VkBufferView handle in which the 972 resulting buffer view object is returned. 973 974include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 975 976ifdef::VKSC_VERSION_1_0[] 977.Valid Usage 978**** 979include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 980**** 981endif::VKSC_VERSION_1_0[] 982 983include::{generated}/validity/protos/vkCreateBufferView.adoc[] 984-- 985 986[open,refpage='VkBufferViewCreateInfo',desc='Structure specifying parameters of a newly created buffer view',type='structs'] 987-- 988The sname:VkBufferViewCreateInfo structure is defined as: 989 990include::{generated}/api/structs/VkBufferViewCreateInfo.adoc[] 991 992 * pname:sType is a elink:VkStructureType value identifying this structure. 993 * pname:pNext is `NULL` or a pointer to a structure extending this 994 structure. 995 * pname:flags is reserved for future use. 996 * pname:buffer is a slink:VkBuffer on which the view will be created. 997 * pname:format is a elink:VkFormat describing the format of the data 998 elements in the buffer. 999 * pname:offset is an offset in bytes from the base address of the buffer. 1000 Accesses to the buffer view from shaders use addressing that is relative 1001 to this starting offset. 1002 * pname:range is a size in bytes of the buffer view. 1003 If pname:range is equal to ename:VK_WHOLE_SIZE, the range from 1004 pname:offset to the end of the buffer is used. 1005 If ename:VK_WHOLE_SIZE is used and the remaining size of the buffer is 1006 not a multiple of the <<texel-block-size, texel block size>> of 1007 pname:format, the nearest smaller multiple is used. 1008 1009[[resources-buffer-views-usage]] 1010The buffer view has a _buffer view usage_ identifying which descriptor types 1011can be created from it. 1012This usage 1013ifdef::VK_KHR_maintenance5[] 1014can: be defined by including the slink:VkBufferUsageFlags2CreateInfoKHR 1015structure in the pname:pNext chain, and specifying the pname:usage value 1016there. 1017If this structure is not included, it 1018endif::VK_KHR_maintenance5[] 1019is equal to the slink:VkBufferCreateInfo::pname:usage value used to create 1020pname:buffer. 1021 1022.Valid Usage 1023**** 1024 * [[VUID-VkBufferViewCreateInfo-offset-00925]] 1025 pname:offset must: be less than the size of pname:buffer 1026 * [[VUID-VkBufferViewCreateInfo-range-00928]] 1027 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 1028 greater than `0` 1029 * [[VUID-VkBufferViewCreateInfo-range-00929]] 1030 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 1031 an integer multiple of the texel block size of pname:format 1032 * [[VUID-VkBufferViewCreateInfo-range-00930]] 1033 If pname:range is not equal to ename:VK_WHOLE_SIZE, the number of texel 1034 buffer elements given by [eq]#({lfloor}pname:range / (texel block 1035 size){rfloor} {times} (texels per block))# where texel block size and 1036 texels per block are as defined in the <<formats-compatibility, 1037 Compatible Formats>> table for pname:format, must: be less than or equal 1038 to sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements 1039 * [[VUID-VkBufferViewCreateInfo-offset-00931]] 1040 If pname:range is not equal to ename:VK_WHOLE_SIZE, the sum of 1041 pname:offset and pname:range must: be less than or equal to the size of 1042 pname:buffer 1043 * [[VUID-VkBufferViewCreateInfo-range-04059]] 1044 If pname:range is equal to ename:VK_WHOLE_SIZE, the number of texel 1045 buffer elements given by [eq]#({lfloor}(size - pname:offset) / (texel 1046 block size){rfloor} {times} (texels per block))# where size is the size 1047 of pname:buffer, and texel block size and texels per block are as 1048 defined in the <<formats-compatibility, Compatible Formats>> table for 1049 pname:format, must: be less than or equal to 1050 sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements 1051 * [[VUID-VkBufferViewCreateInfo-buffer-00932]] 1052 pname:buffer must: have been created with a pname:usage value containing 1053 at least one of ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or 1054 ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT 1055 * [[VUID-VkBufferViewCreateInfo-format-08778]] 1056 If the <<resources-buffer-views-usage, buffer view usage>> contains 1057 ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, then 1058 <<resources-buffer-view-format-features,format features>> of 1059 pname:format must: contain 1060 ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT 1061 * [[VUID-VkBufferViewCreateInfo-format-08779]] 1062 If the <<resources-buffer-views-usage, buffer view usage>> contains 1063 ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, then 1064 <<resources-buffer-view-format-features,format features>> of 1065 pname:format must: contain 1066 ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT 1067 * [[VUID-VkBufferViewCreateInfo-buffer-00935]] 1068 If pname:buffer is non-sparse then it must: be bound completely and 1069 contiguously to a single sname:VkDeviceMemory object 1070 * [[VUID-VkBufferViewCreateInfo-offset-02749]] 1071ifdef::VK_VERSION_1_3,VK_EXT_texel_buffer_alignment[] 1072 If the <<features-texelBufferAlignment, pname:texelBufferAlignment>> 1073 feature is not enabled, 1074endif::VK_VERSION_1_3,VK_EXT_texel_buffer_alignment[] 1075 pname:offset must: be a multiple of 1076 sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment 1077ifdef::VK_VERSION_1_3,VK_EXT_texel_buffer_alignment[] 1078 * [[VUID-VkBufferViewCreateInfo-buffer-02750]] 1079 If the <<features-texelBufferAlignment, pname:texelBufferAlignment>> 1080 feature is enabled and if pname:buffer was created with pname:usage 1081 containing ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:offset 1082 must: be a multiple of the lesser of 1083 slink:VkPhysicalDeviceTexelBufferAlignmentProperties::pname:storageTexelBufferOffsetAlignmentBytes 1084 or, if 1085 slink:VkPhysicalDeviceTexelBufferAlignmentProperties::pname:storageTexelBufferOffsetSingleTexelAlignment 1086 is ename:VK_TRUE, the size of a texel of the requested pname:format. 1087 If the size of a texel is a multiple of three bytes, then the size of a 1088 single component of pname:format is used instead 1089 * [[VUID-VkBufferViewCreateInfo-buffer-02751]] 1090 If the <<features-texelBufferAlignment, pname:texelBufferAlignment>> 1091 feature is enabled and if pname:buffer was created with pname:usage 1092 containing ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:offset 1093 must: be a multiple of the lesser of 1094 slink:VkPhysicalDeviceTexelBufferAlignmentProperties::pname:uniformTexelBufferOffsetAlignmentBytes 1095 or, if 1096 slink:VkPhysicalDeviceTexelBufferAlignmentProperties::pname:uniformTexelBufferOffsetSingleTexelAlignment 1097 is ename:VK_TRUE, the size of a texel of the requested pname:format. 1098 If the size of a texel is a multiple of three bytes, then the size of a 1099 single component of pname:format is used instead 1100endif::VK_VERSION_1_3,VK_EXT_texel_buffer_alignment[] 1101ifdef::VK_EXT_metal_objects[] 1102 * [[VUID-VkBufferViewCreateInfo-pNext-06782]] 1103 If the pname:pNext chain includes a 1104 slink:VkExportMetalObjectCreateInfoEXT structure, its 1105 pname:exportObjectType member must: be 1106 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT 1107endif::VK_EXT_metal_objects[] 1108ifdef::VK_KHR_maintenance5[] 1109 * [[VUID-VkBufferViewCreateInfo-pNext-08780]] 1110 If the pname:pNext chain includes a 1111 slink:VkBufferUsageFlags2CreateInfoKHR, its pname:usage must: not 1112 contain any other bit than 1113 ename:VK_BUFFER_USAGE_2_UNIFORM_TEXEL_BUFFER_BIT_KHR or 1114 ename:VK_BUFFER_USAGE_2_STORAGE_TEXEL_BUFFER_BIT_KHR 1115 * [[VUID-VkBufferViewCreateInfo-pNext-08781]] 1116 If the pname:pNext chain includes a 1117 slink:VkBufferUsageFlags2CreateInfoKHR, its pname:usage must: be a 1118 subset of the slink:VkBufferCreateInfo::pname:usage specified or 1119 slink:VkBufferUsageFlags2CreateInfoKHR::pname:usage from 1120 slink:VkBufferCreateInfo::pname:pNext when creating pname:buffer 1121endif::VK_KHR_maintenance5[] 1122**** 1123 1124include::{generated}/validity/structs/VkBufferViewCreateInfo.adoc[] 1125-- 1126 1127[open,refpage='VkBufferViewCreateFlags',desc='Reserved for future use',type='flags'] 1128-- 1129include::{generated}/api/flags/VkBufferViewCreateFlags.adoc[] 1130 1131tname:VkBufferViewCreateFlags is a bitmask type for setting a mask, but is 1132currently reserved for future use. 1133-- 1134 1135[open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos'] 1136-- 1137To destroy a buffer view, call: 1138 1139include::{generated}/api/protos/vkDestroyBufferView.adoc[] 1140 1141 * pname:device is the logical device that destroys the buffer view. 1142 * pname:bufferView is the buffer view to destroy. 1143 * pname:pAllocator controls host memory allocation as described in the 1144 <<memory-allocation, Memory Allocation>> chapter. 1145 1146.Valid Usage 1147**** 1148 * [[VUID-vkDestroyBufferView-bufferView-00936]] 1149 All submitted commands that refer to pname:bufferView must: have 1150 completed execution 1151ifndef::VKSC_VERSION_1_0[] 1152 * [[VUID-vkDestroyBufferView-bufferView-00937]] 1153 If sname:VkAllocationCallbacks were provided when pname:bufferView was 1154 created, a compatible set of callbacks must: be provided here 1155 * [[VUID-vkDestroyBufferView-bufferView-00938]] 1156 If no sname:VkAllocationCallbacks were provided when pname:bufferView 1157 was created, pname:pAllocator must: be `NULL` 1158endif::VKSC_VERSION_1_0[] 1159**** 1160 1161include::{generated}/validity/protos/vkDestroyBufferView.adoc[] 1162-- 1163 1164[[resources-buffer-view-format-features]] 1165=== Buffer View Format Features 1166 1167Valid uses of a slink:VkBufferView may: depend on the buffer view's _format 1168features_, defined below. 1169Such constraints are documented in the affected valid usage statement. 1170 1171ifndef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 1172 * The buffer view's set of _format features_ is the value of 1173 slink:VkFormatProperties::pname:bufferFeatures found by calling 1174 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 1175 slink:VkBufferViewCreateInfo::pname:format. 1176endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 1177ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 1178 * If Vulkan 1.3 is supported or the `apiext:VK_KHR_format_feature_flags2` 1179 extension is supported, then the buffer view's set of _format features_ 1180 is the value of slink:VkFormatProperties3::pname:bufferFeatures found by 1181 calling flink:vkGetPhysicalDeviceFormatProperties2 on the same 1182 pname:format as slink:VkBufferViewCreateInfo::pname:format. 1183endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 1184 1185[[resources-images]] 1186== Images 1187 1188[open,refpage='VkImage',desc='Opaque handle to an image object',type='handles'] 1189-- 1190Images represent multidimensional - up to 3 - arrays of data which can: be 1191used for various purposes (e.g. attachments, textures), by binding them to a 1192graphics or compute pipeline via descriptor sets, or by directly specifying 1193them as parameters to certain commands. 1194 1195Images are represented by sname:VkImage handles: 1196 1197include::{generated}/api/handles/VkImage.adoc[] 1198-- 1199 1200[open,refpage='vkCreateImage',desc='Create a new image object',type='protos'] 1201-- 1202:refpage: vkCreateImage 1203:objectnameplural: images 1204:objectnamecamelcase: image 1205:objectcount: 1 1206 1207To create images, call: 1208 1209include::{generated}/api/protos/vkCreateImage.adoc[] 1210 1211 * pname:device is the logical device that creates the image. 1212 * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure 1213 containing parameters to be used to create the image. 1214 * pname:pAllocator controls host memory allocation as described in the 1215 <<memory-allocation, Memory Allocation>> chapter. 1216 * pname:pImage is a pointer to a slink:VkImage handle in which the 1217 resulting image object is returned. 1218 1219include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1220 1221.Valid Usage 1222**** 1223ifndef::VKSC_VERSION_1_0[] 1224 * [[VUID-vkCreateImage-flags-00939]] 1225 If the pname:flags member of pname:pCreateInfo includes 1226 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1227ifdef::VK_NV_extended_sparse_address_space[] 1228 and the <<features-extendedSparseAddressSpace, 1229 pname:extendedSparseAddressSpace>> feature is not enabled, 1230endif::VK_NV_extended_sparse_address_space[] 1231 creating this sname:VkImage must: not cause the total required sparse 1232 memory for all currently valid sparse resources on the device to exceed 1233 sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 1234ifdef::VK_NV_extended_sparse_address_space[] 1235 * [[VUID-vkCreateImage-flags-09385]] 1236 If the pname:flags member of pname:pCreateInfo includes 1237 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, the 1238 <<features-extendedSparseAddressSpace, 1239 pname:extendedSparseAddressSpace>> feature is enabled, and the 1240 pname:usage member of pname:pCreateInfo contains bits not in 1241 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseImageUsageFlags, 1242 creating this sname:VkImage must: not cause the total required sparse 1243 memory for all currently valid sparse resources on the device, excluding 1244 sname:VkBuffer created with pname:usage member of pname:pCreateInfo 1245 containing bits in 1246 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseBufferUsageFlags 1247 and sname:VkImage created with pname:usage member of pname:pCreateInfo 1248 containing bits in 1249 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseImageUsageFlags, 1250 to exceed sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize 1251 * [[VUID-vkCreateImage-flags-09386]] 1252 If the pname:flags member of pname:pCreateInfo includes 1253 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT and the 1254 <<features-extendedSparseAddressSpace, 1255 pname:extendedSparseAddressSpace>> feature is enabled, creating this 1256 sname:VkImage must: not cause the total required sparse memory for all 1257 currently valid sparse resources on the device to exceed 1258 sname:VkPhysicalDeviceExtendedSparseAddressSpacePropertiesNV::pname:extendedSparseAddressSpaceSize 1259endif::VK_NV_extended_sparse_address_space[] 1260endif::VKSC_VERSION_1_0[] 1261include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 1262ifdef::VK_FUCHSIA_buffer_collection[] 1263 * [[VUID-vkCreateImage-pNext-06389]] 1264 If a slink:VkBufferCollectionImageCreateInfoFUCHSIA has been chained to 1265 pname:pNext, pname:pCreateInfo must: match the 1266 <<sysmem-chosen-create-infos,Sysmem chosen sname:VkImageCreateInfo>> 1267 excepting members slink:VkImageCreateInfo::pname:extent and 1268 slink:VkImageCreateInfo::pname:usage in the match criteria 1269endif::VK_FUCHSIA_buffer_collection[] 1270**** 1271 1272include::{generated}/validity/protos/vkCreateImage.adoc[] 1273-- 1274 1275[open,refpage='VkImageCreateInfo',desc='Structure specifying the parameters of a newly created image object',type='structs'] 1276-- 1277The sname:VkImageCreateInfo structure is defined as: 1278 1279include::{generated}/api/structs/VkImageCreateInfo.adoc[] 1280 1281 * pname:sType is a elink:VkStructureType value identifying this structure. 1282 * pname:pNext is `NULL` or a pointer to a structure extending this 1283 structure. 1284 * pname:flags is a bitmask of elink:VkImageCreateFlagBits describing 1285 additional parameters of the image. 1286 * pname:imageType is a elink:VkImageType value specifying the basic 1287 dimensionality of the image. 1288 Layers in array textures do not count as a dimension for the purposes of 1289 the image type. 1290 * pname:format is a elink:VkFormat describing the format and type of the 1291 texel blocks that will be contained in the image. 1292 * pname:extent is a slink:VkExtent3D describing the number of data 1293 elements in each dimension of the base level. 1294 * pname:mipLevels describes the number of levels of detail available for 1295 minified sampling of the image. 1296 * pname:arrayLayers is the number of layers in the image. 1297 * pname:samples is a elink:VkSampleCountFlagBits value specifying the 1298 number of <<primsrast-multisampling,samples per texel>>. 1299 * pname:tiling is a elink:VkImageTiling value specifying the tiling 1300 arrangement of the texel blocks in memory. 1301 * pname:usage is a bitmask of elink:VkImageUsageFlagBits describing the 1302 intended usage of the image. 1303 * pname:sharingMode is a elink:VkSharingMode value specifying the sharing 1304 mode of the image when it will be accessed by multiple queue families. 1305 * pname:queueFamilyIndexCount is the number of entries in the 1306 pname:pQueueFamilyIndices array. 1307 * pname:pQueueFamilyIndices is a pointer to an array of queue families 1308 that will access this image. 1309 It is ignored if pname:sharingMode is not 1310 ename:VK_SHARING_MODE_CONCURRENT. 1311 * pname:initialLayout is a elink:VkImageLayout value specifying the 1312 initial elink:VkImageLayout of all image subresources of the image. 1313 See <<resources-image-layouts,Image Layouts>>. 1314 1315Images created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR have 1316further restrictions on their limits and capabilities compared to images 1317created with pname:tiling equal to ename:VK_IMAGE_TILING_OPTIMAL. 1318Creation of images with tiling ename:VK_IMAGE_TILING_LINEAR may: not be 1319supported unless other parameters meet all of the constraints: 1320 1321 * pname:imageType is ename:VK_IMAGE_TYPE_2D 1322 * pname:format is not a depth/stencil format 1323 * pname:mipLevels is 1 1324 * pname:arrayLayers is 1 1325 * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT 1326 * pname:usage only includes ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or 1327 ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT 1328 1329ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 1330Images created with one of the <<formats-requiring-sampler-ycbcr-conversion, 1331formats that require a sampler {YCbCr} conversion>>, have further 1332restrictions on their limits and capabilities compared to images created 1333with other formats. 1334Creation of images with a format requiring 1335<<formats-requiring-sampler-ycbcr-conversion, {YCbCr} conversion>> may: not 1336be supported unless other parameters meet all of the constraints: 1337 1338 * pname:imageType is ename:VK_IMAGE_TYPE_2D 1339 * pname:mipLevels is 1 1340 * pname:arrayLayers is 1, unless 1341ifdef::VK_EXT_ycbcr_image_arrays[] 1342 the pname:ycbcrImageArrays feature is enabled, or 1343endif::VK_EXT_ycbcr_image_arrays[] 1344 otherwise indicated by 1345 slink:VkImageFormatProperties::pname:maxArrayLayers, as returned by 1346 flink:vkGetPhysicalDeviceImageFormatProperties 1347 * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT 1348endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 1349 1350Implementations may: support additional limits and capabilities beyond those 1351listed above. 1352 1353To determine the set of valid pname:usage bits for a given format, call 1354flink:vkGetPhysicalDeviceFormatProperties. 1355 1356If the size of the resultant image would exceed pname:maxResourceSize, then 1357flink:vkCreateImage must: fail and return 1358ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1359This failure may: occur even when all image creation parameters satisfy 1360their valid usage requirements. 1361 1362ifdef::VK_EXT_host_image_copy[] 1363If the implementation reports ename:VK_TRUE in 1364slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:identicalMemoryTypeRequirements, 1365usage of ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT must: not affect the 1366memory type requirements of the image as described in 1367ifndef::VKSC_VERSION_1_0[] 1368<<sparsememory-memory-requirements,Sparse Resource Memory Requirements>> and 1369endif::VKSC_VERSION_1_0[] 1370<<resources-association,Resource Memory Association>>. 1371endif::VK_EXT_host_image_copy[] 1372 1373ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1374[NOTE] 1375.Note 1376==== 1377For images created without ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a 1378pname:usage bit is valid if it is supported for the format the image is 1379created with. 1380 1381For images created with ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a 1382pname:usage bit is valid if it is supported for at least one of the formats 1383a sname:VkImageView created from the image can: have (see 1384<<resources-image-views,Image Views>> for more detail). 1385==== 1386endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1387 1388[[resources-image-creation-limits]] 1389.Image Creation Limits 1390**** 1391Valid values for some image creation parameters are limited by a numerical 1392upper bound or by inclusion in a bitset. 1393For example, slink:VkImageCreateInfo::pname:arrayLayers is limited by 1394pname:imageCreateMaxArrayLayers, defined below; and 1395slink:VkImageCreateInfo::pname:samples is limited by 1396pname:imageCreateSampleCounts, also defined below. 1397 1398Several limiting values are defined below, as well as assisting values from 1399which the limiting values are derived. 1400The limiting values are referenced by the relevant valid usage statements of 1401slink:VkImageCreateInfo. 1402 1403ifdef::VK_EXT_image_drm_format_modifier[] 1404 * Let `uint64_t imageCreateDrmFormatModifiers[]` be the set of 1405 <<glossary-drm-format-modifier,Linux DRM format modifiers>> that the 1406 resultant image may: have. 1407 ** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 1408 then pname:imageCreateDrmFormatModifiers is empty. 1409 ** If slink:VkImageCreateInfo::pname:pNext contains 1410 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then 1411 pname:imageCreateDrmFormatModifiers contains exactly one modifier, 1412 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. 1413 ** If slink:VkImageCreateInfo::pname:pNext contains 1414 slink:VkImageDrmFormatModifierListCreateInfoEXT, then 1415 pname:imageCreateDrmFormatModifiers contains the entire array 1416 slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. 1417endif::VK_EXT_image_drm_format_modifier[] 1418 1419 * Let `VkBool32 imageCreateMaybeLinear` indicate if the resultant image 1420 may be <<glossary-linear-resource,linear>>. 1421ifndef::VK_EXT_image_drm_format_modifier[] 1422 (The definition below is trivial because certain extensions are disabled 1423 in this build of the specification). 1424endif::VK_EXT_image_drm_format_modifier[] 1425 ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then 1426 pname:imageCreateMaybeLinear is ename:VK_TRUE. 1427 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, then 1428 pname:imageCreateMaybeLinear is ename:VK_FALSE. 1429ifdef::VK_EXT_image_drm_format_modifier[] 1430 ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 1431 pname:imageCreateMaybeLinear is ename:VK_TRUE if and only if 1432 pname:imageCreateDrmFormatModifiers contains 1433 etext:DRM_FORMAT_MOD_LINEAR. 1434endif::VK_EXT_image_drm_format_modifier[] 1435 1436 * Let `VkFormatFeatureFlags imageCreateFormatFeatures` be the set of valid 1437 _format features_ available during image creation. 1438 ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then 1439 pname:imageCreateFormatFeatures is the value of 1440 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 1441 flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format 1442 equal to slink:VkImageCreateInfo::pname:format. 1443 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, 1444ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 1445 and if the pname:pNext chain includes no 1446ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1447 slink:VkExternalFormatANDROID 1448endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1449ifdef::VK_QNX_external_memory_screen_buffer[] 1450ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1451 or 1452endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1453 slink:VkExternalFormatQNX 1454endif::VK_QNX_external_memory_screen_buffer[] 1455 structure with non-zero pname:externalFormat, 1456endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 1457 then pname:imageCreateFormatFeatures is the value of 1458 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 1459 flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format 1460 equal to slink:VkImageCreateInfo::pname:format. 1461ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1462 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and if the 1463 pname:pNext chain includes a slink:VkExternalFormatANDROID structure 1464 with non-zero pname:externalFormat, then 1465 pname:imageCreateFormatFeatures is the value of 1466 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 1467 obtained by flink:vkGetAndroidHardwareBufferPropertiesANDROID with a 1468 matching pname:externalFormat value. 1469endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1470ifdef::VK_QNX_external_memory_screen_buffer[] 1471 ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and if the 1472 pname:pNext chain includes a slink:VkExternalFormatQNX structure with 1473 non-zero pname:externalFormat, then pname:imageCreateFormatFeatures is 1474 the value of 1475 slink:VkScreenBufferFormatPropertiesQNX::pname:formatFeatures obtained 1476 by flink:vkGetScreenBufferPropertiesQNX with a matching 1477 pname:externalFormat value. 1478endif::VK_QNX_external_memory_screen_buffer[] 1479ifdef::VK_FUCHSIA_buffer_collection[] 1480 ** If the pname:pNext chain includes a 1481 slink:VkBufferCollectionImageCreateInfoFUCHSIA structure, then 1482 pname:imageCreateFormatFeatures is the value of 1483 slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found 1484 by calling flink:vkGetBufferCollectionPropertiesFUCHSIA with a 1485 parameter pname:collection equal to 1486 slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection 1487endif::VK_FUCHSIA_buffer_collection[] 1488ifdef::VK_EXT_image_drm_format_modifier[] 1489 ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 1490 the value of pname:imageCreateFormatFeatures is found by calling 1491 flink:vkGetPhysicalDeviceFormatProperties2 with 1492 slink:VkImageFormatProperties::pname:format equal to 1493 slink:VkImageCreateInfo::pname:format and with 1494 slink:VkDrmFormatModifierPropertiesListEXT chained into 1495 slink:VkFormatProperties2; by collecting all members of the returned 1496 array 1497 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 1498 whose pname:drmFormatModifier belongs to 1499 pname:imageCreateDrmFormatModifiers; and by taking the bitwise 1500 intersection, over the collected array members, of 1501 pname:drmFormatModifierTilingFeatures. 1502 (The resultant pname:imageCreateFormatFeatures may: be empty). 1503endif::VK_EXT_image_drm_format_modifier[] 1504 1505ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1506 * Let `VkImageFormatProperties2 imageCreateImageFormatPropertiesList[]` be 1507ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 1508 defined as follows. 1509 ** If slink:VkImageCreateInfo::pname:pNext contains no 1510ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1511 slink:VkExternalFormatANDROID 1512endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1513ifdef::VK_QNX_external_memory_screen_buffer[] 1514ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1515 or 1516endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1517 slink:VkExternalFormatQNX 1518endif::VK_QNX_external_memory_screen_buffer[] 1519 structure with non-zero pname:externalFormat, then 1520 pname:imageCreateImageFormatPropertiesList is 1521endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 1522 the list of structures obtained by calling 1523 flink:vkGetPhysicalDeviceImageFormatProperties2, possibly multiple 1524 times, as follows: 1525 *** The parameters slink:VkPhysicalDeviceImageFormatInfo2::pname:format, 1526 pname:imageType, pname:tiling, pname:usage, and pname:flags must: be 1527 equal to those in slink:VkImageCreateInfo. 1528 *** If slink:VkImageCreateInfo::pname:pNext contains a 1529 slink:VkExternalMemoryImageCreateInfo structure whose 1530 pname:handleTypes is not `0`, then 1531 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a 1532 slink:VkPhysicalDeviceExternalImageFormatInfo structure whose 1533 pname:handleType is not `0`; and 1534 flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for 1535 each handle type in 1536 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes, successively 1537 setting 1538 slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType on 1539 each call. 1540 *** If slink:VkImageCreateInfo::pname:pNext contains no 1541 slink:VkExternalMemoryImageCreateInfo structure, or contains a 1542 structure whose pname:handleTypes is `0`, then 1543 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: either 1544 contain no slink:VkPhysicalDeviceExternalImageFormatInfo structure, or 1545 contain a structure whose pname:handleType is `0`. 1546ifdef::VK_KHR_video_queue[] 1547 *** If slink:VkImageCreateInfo::pname:pNext contains a 1548 slink:VkVideoProfileListInfoKHR structure then 1549 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: also contain 1550 the same slink:VkVideoProfileListInfoKHR structure on each call. 1551endif::VK_KHR_video_queue[] 1552ifdef::VK_EXT_image_drm_format_modifier[] 1553 *** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 1554 then: 1555 **** slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a 1556 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure where 1557 pname:sharingMode is equal to 1558 slink:VkImageCreateInfo::pname:sharingMode; 1559 **** if pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, then 1560 pname:queueFamilyIndexCount and pname:pQueueFamilyIndices must: be 1561 equal to those in slink:VkImageCreateInfo; 1562 **** if pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, 1563 then the slink:VkImageFormatListCreateInfo structure included in the 1564 pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2 must: be 1565 equivalent to the one included in the pname:pNext chain of 1566 slink:VkImageCreateInfo; 1567ifdef::VK_EXT_image_compression_control[] 1568 **** if slink:VkImageCreateInfo::pname:pNext contains a 1569 slink:VkImageCompressionControlEXT structure, then the 1570 slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext chain must: 1571 contain an equivalent structure; 1572endif::VK_EXT_image_compression_control[] 1573 **** flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for 1574 each modifier in pname:imageCreateDrmFormatModifiers, successively 1575 setting 1576 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT::pname:drmFormatModifier 1577 on each call. 1578 *** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 1579 then slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain 1580 no slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure. 1581endif::VK_EXT_image_drm_format_modifier[] 1582 *** If any call to flink:vkGetPhysicalDeviceImageFormatProperties2 returns 1583 an error, then pname:imageCreateImageFormatPropertiesList is defined 1584 to be the empty list. 1585ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1586 ** If slink:VkImageCreateInfo::pname:pNext contains a 1587 slink:VkExternalFormatANDROID structure with non-zero 1588 pname:externalFormat, then pname:imageCreateImageFormatPropertiesList 1589 contains a single element where: 1590 *** sname:VkImageFormatProperties::pname:maxMipLevels is 1591 [eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height, 1592 pname:extent.depth)){rfloor} {plus} 1#. 1593 *** sname:VkImageFormatProperties::pname:maxArrayLayers is 1594 slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. 1595 *** Each component of sname:VkImageFormatProperties::pname:maxExtent is 1596 slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D. 1597 *** sname:VkImageFormatProperties::pname:sampleCounts contains exactly 1598 ename:VK_SAMPLE_COUNT_1_BIT. 1599endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1600endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1601 1602 * Let `uint32_t imageCreateMaxMipLevels` be 1603ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1604 the value of slink:VkImageFormatProperties::pname:maxMipLevels found by 1605 calling flink:vkGetPhysicalDeviceImageFormatProperties with parameters 1606 pname:format, pname:imageType, pname:tiling, pname:usage, and 1607 pname:flags equal to those in slink:VkImageCreateInfo. 1608 If flink:vkGetPhysicalDeviceFormatProperties returns an error, then the 1609 value of pname:imageCreateMaxMipLevels is undefined:. 1610endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1611ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1612 the minimum value of slink:VkImageFormatProperties::pname:maxMipLevels 1613 in pname:imageCreateImageFormatPropertiesList. 1614 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1615 empty. 1616endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1617 1618 * Let `uint32_t imageCreateMaxArrayLayers` be 1619ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1620 defined analogously to pname:imageCreateMaxMipLevels. 1621endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1622ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1623 the minimum value of slink:VkImageFormatProperties::pname:maxArrayLayers 1624 in pname:imageCreateImageFormatPropertiesList. 1625 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1626 empty. 1627endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1628 1629 * Let `VkExtent3D imageCreateMaxExtent` be 1630ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1631 defined analogously to pname:imageCreateMaxMipLevels. 1632endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1633ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1634 the component-wise minimum over all 1635 slink:VkImageFormatProperties::pname:maxExtent values in 1636 pname:imageCreateImageFormatPropertiesList. 1637 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1638 empty. 1639endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1640 1641 * Let `VkSampleCountFlags imageCreateSampleCounts` be 1642ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 1643 defined analogously to pname:imageCreateMaxMipLevels. 1644endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1645ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1646 the intersection of each 1647 slink:VkImageFormatProperties::pname:sampleCounts in 1648 pname:imageCreateImageFormatPropertiesList. 1649 The value is undefined: if pname:imageCreateImageFormatPropertiesList is 1650 empty. 1651endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1652 1653ifdef::VK_KHR_video_queue[] 1654 * Let `VkVideoFormatPropertiesKHR videoFormatProperties[]` be defined as 1655 follows. 1656 ** If slink:VkImageCreateInfo::pname:pNext contains a 1657 slink:VkVideoProfileListInfoKHR structure, then `videoFormatProperties` 1658 is the list of structures obtained by calling 1659 flink:vkGetPhysicalDeviceVideoFormatPropertiesKHR with 1660 slink:VkPhysicalDeviceVideoFormatInfoKHR::pname:imageUsage equal to the 1661 pname:usage member of slink:VkImageCreateInfo and 1662 slink:VkPhysicalDeviceVideoFormatInfoKHR::pname:pNext containing the 1663 same slink:VkVideoProfileListInfoKHR structure chained to 1664 slink:VkImageCreateInfo. 1665 ** If slink:VkImageCreateInfo::pname:pNext contains no 1666 slink:VkVideoProfileListInfoKHR structure, then `videoFormatProperties` 1667 is an empty list. 1668 * Let `VkBool32 supportedVideoFormat` indicate if the image parameters are 1669 supported by the specified video profiles. 1670 ** `supportedVideoFormat` is ename:VK_TRUE if there exists an element in 1671 the `videoFormatProperties` list for which all of the following 1672 conditions are true: 1673 *** slink:VkImageCreateInfo::pname:format equals 1674 slink:VkVideoFormatPropertiesKHR::pname:format. 1675 *** slink:VkImageCreateInfo::pname:flags only contains bits also set in 1676 slink:VkVideoFormatPropertiesKHR::pname:imageCreateFlags. 1677 *** slink:VkImageCreateInfo::pname:imageType equals 1678 slink:VkVideoFormatPropertiesKHR::pname:imageType. 1679 *** slink:VkImageCreateInfo::pname:tiling equals 1680 slink:VkVideoFormatPropertiesKHR::pname:imageTiling. 1681 *** slink:VkImageCreateInfo::pname:usage only contains bits also set in 1682 slink:VkVideoFormatPropertiesKHR::pname:imageUsageFlags. 1683 ** Otherwise `supportedVideoFormat` is ename:VK_FALSE. 1684endif::VK_KHR_video_queue[] 1685**** 1686 1687.Valid Usage 1688**** 1689 * [[VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251]] 1690 Each of the following values (as described in 1691 <<resources-image-creation-limits,Image Creation Limits>>) must: not be 1692 undefined: : pname:imageCreateMaxMipLevels, 1693 pname:imageCreateMaxArrayLayers, pname:imageCreateMaxExtent, and 1694 pname:imageCreateSampleCounts 1695 * [[VUID-VkImageCreateInfo-sharingMode-00941]] 1696 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 1697 pname:pQueueFamilyIndices must: be a valid pointer to an array of 1698 pname:queueFamilyIndexCount code:uint32_t values 1699 * [[VUID-VkImageCreateInfo-sharingMode-00942]] 1700 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, 1701 pname:queueFamilyIndexCount must: be greater than `1` 1702ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1703 * [[VUID-VkImageCreateInfo-sharingMode-01392]] 1704 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 1705 of pname:pQueueFamilyIndices must: be unique and must: be less than 1706 pname:pQueueFamilyPropertyCount returned by 1707 flink:vkGetPhysicalDeviceQueueFamilyProperties for the 1708 pname:physicalDevice that was used to create pname:device 1709endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1710ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1711 * [[VUID-VkImageCreateInfo-sharingMode-01420]] 1712 If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element 1713 of pname:pQueueFamilyIndices must: be unique and must: be less than 1714 pname:pQueueFamilyPropertyCount returned by either 1715 flink:vkGetPhysicalDeviceQueueFamilyProperties or 1716 flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the 1717 pname:physicalDevice that was used to create pname:device 1718endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1719ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 1720 * [[VUID-VkImageCreateInfo-format-00943]] 1721 pname:format must: not be ename:VK_FORMAT_UNDEFINED 1722endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1723ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 1724 * [[VUID-VkImageCreateInfo-pNext-01974]] 1725 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 1726 structure, and its pname:externalFormat member is non-zero the 1727 pname:format must: be ename:VK_FORMAT_UNDEFINED 1728 * [[VUID-VkImageCreateInfo-pNext-01975]] 1729 If the pname:pNext chain does not include a 1730 slink:VkExternalFormatANDROID structure, or does and its 1731 pname:externalFormat member is `0`, the pname:format must: not be 1732 ename:VK_FORMAT_UNDEFINED 1733endif::VK_ANDROID_external_memory_android_hardware_buffer[] 1734 * [[VUID-VkImageCreateInfo-extent-00944]] 1735 pname:extent.width must: be greater than `0` 1736 * [[VUID-VkImageCreateInfo-extent-00945]] 1737 pname:extent.height must: be greater than `0` 1738 * [[VUID-VkImageCreateInfo-extent-00946]] 1739 pname:extent.depth must: be greater than `0` 1740 * [[VUID-VkImageCreateInfo-mipLevels-00947]] 1741 pname:mipLevels must: be greater than `0` 1742 * [[VUID-VkImageCreateInfo-arrayLayers-00948]] 1743 pname:arrayLayers must: be greater than `0` 1744 * [[VUID-VkImageCreateInfo-flags-00949]] 1745 If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, 1746 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 1747 * [[VUID-VkImageCreateInfo-flags-08865]] 1748 If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, 1749 pname:extent.width and pname:extent.height must: be equal 1750 * [[VUID-VkImageCreateInfo-flags-08866]] 1751 If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, 1752 pname:arrayLayers must: be greater than or equal to 6 1753ifdef::VK_EXT_fragment_density_map[] 1754 * [[VUID-VkImageCreateInfo-flags-02557]] 1755 If pname:flags contains 1756 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:imageType must: 1757 be ename:VK_IMAGE_TYPE_2D 1758endif::VK_EXT_fragment_density_map[] 1759ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1760 * [[VUID-VkImageCreateInfo-flags-00950]] 1761 If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, 1762 pname:imageType must: be ename:VK_IMAGE_TYPE_3D 1763 * [[VUID-VkImageCreateInfo-flags-09403]] 1764 If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, 1765 pname:flags must: not include ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, 1766 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, or 1767 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1768endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1769ifdef::VK_EXT_image_2d_view_of_3d[] 1770 * [[VUID-VkImageCreateInfo-flags-07755]] 1771 If pname:flags contains 1772 ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT, pname:imageType must: 1773 be ename:VK_IMAGE_TYPE_3D 1774endif::VK_EXT_image_2d_view_of_3d[] 1775 * [[VUID-VkImageCreateInfo-extent-02252]] 1776 pname:extent.width must: be less than or equal to 1777 pname:imageCreateMaxExtent.width (as defined in 1778 <<resources-image-creation-limits,Image Creation Limits>>) 1779 * [[VUID-VkImageCreateInfo-extent-02253]] 1780 pname:extent.height must: be less than or equal to 1781 pname:imageCreateMaxExtent.height (as defined in 1782 <<resources-image-creation-limits,Image Creation Limits>>) 1783 * [[VUID-VkImageCreateInfo-extent-02254]] 1784 pname:extent.depth must: be less than or equal to 1785 pname:imageCreateMaxExtent.depth (as defined in 1786 <<resources-image-creation-limits,Image Creation Limits>>) 1787 * [[VUID-VkImageCreateInfo-imageType-00956]] 1788 If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height 1789 and pname:extent.depth must: be `1` 1790 * [[VUID-VkImageCreateInfo-imageType-00957]] 1791 If pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.depth must: 1792 be `1` 1793 * [[VUID-VkImageCreateInfo-mipLevels-00958]] 1794 pname:mipLevels must: be less than or equal to the number of levels in 1795 the complete mipmap chain based on [eq]#pname:extent.width#, 1796 [eq]#pname:extent.height#, and [eq]#pname:extent.depth# 1797 * [[VUID-VkImageCreateInfo-mipLevels-02255]] 1798 pname:mipLevels must: be less than or equal to 1799 pname:imageCreateMaxMipLevels (as defined in 1800 <<resources-image-creation-limits,Image Creation Limits>>) 1801 * [[VUID-VkImageCreateInfo-arrayLayers-02256]] 1802 pname:arrayLayers must: be less than or equal to 1803 pname:imageCreateMaxArrayLayers (as defined in 1804 <<resources-image-creation-limits,Image Creation Limits>>) 1805 * [[VUID-VkImageCreateInfo-imageType-00961]] 1806 If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:arrayLayers must: be 1807 `1` 1808 * [[VUID-VkImageCreateInfo-samples-02257]] 1809 If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, then 1810 pname:imageType must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not 1811 contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:mipLevels must: 1812 be equal to `1`, and pname:imageCreateMaybeLinear (as defined in 1813 <<resources-image-creation-limits,Image Creation Limits>>) must: be 1814 ename:VK_FALSE, 1815ifdef::VK_EXT_fragment_density_map[] 1816 * [[VUID-VkImageCreateInfo-samples-02558]] 1817 If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, pname:usage must: 1818 not contain ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 1819endif::VK_EXT_fragment_density_map[] 1820 * [[VUID-VkImageCreateInfo-usage-00963]] 1821 If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, 1822 then bits other than ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1823 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and 1824 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must: not be set 1825 * [[VUID-VkImageCreateInfo-usage-00964]] 1826 If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1827 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, 1828 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or 1829 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be 1830 less than or equal to 1831 sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth 1832 * [[VUID-VkImageCreateInfo-usage-00965]] 1833 If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1834 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, 1835 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or 1836 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be 1837 less than or equal to 1838 sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight 1839ifdef::VK_EXT_fragment_density_map[] 1840ifndef::VK_QCOM_fragment_density_map_offset[] 1841 * [[VUID-VkImageCreateInfo-usage-02559]] 1842 If pname:usage includes 1843 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.width 1844 must: be less than or equal to 1845 latexmath:[\left\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\right\rceil] 1846 * [[VUID-VkImageCreateInfo-usage-02560]] 1847 If pname:usage includes 1848 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.height 1849 must: be less than or equal to 1850 latexmath:[\left\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\right\rceil] 1851endif::VK_QCOM_fragment_density_map_offset[] 1852ifdef::VK_QCOM_fragment_density_map_offset[] 1853 * [[VUID-VkImageCreateInfo-fragmentDensityMapOffset-06514]] 1854 If the <<features-fragmentDensityMapOffsets, 1855 pname:fragmentDensityMapOffset>> feature is not enabled and pname:usage 1856 includes ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, 1857 pname:extent.width must: be less than or equal to 1858 latexmath:[\left\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\right\rceil] 1859 * [[VUID-VkImageCreateInfo-fragmentDensityMapOffset-06515]] 1860 If the <<features-fragmentDensityMapOffsets, 1861 pname:fragmentDensityMapOffset>> feature is not enabled and pname:usage 1862 includes ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, 1863 pname:extent.height must: be less than or equal to 1864 latexmath:[\left\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\right\rceil] 1865endif::VK_QCOM_fragment_density_map_offset[] 1866endif::VK_EXT_fragment_density_map[] 1867 * [[VUID-VkImageCreateInfo-usage-00966]] 1868 If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, 1869 pname:usage must: also contain at least one of 1870 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, 1871 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or 1872 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 1873 * [[VUID-VkImageCreateInfo-samples-02258]] 1874 pname:samples must: be a valid elink:VkSampleCountFlagBits value that is 1875 set in pname:imageCreateSampleCounts (as defined in 1876 <<resources-image-creation-limits,Image Creation Limits>>) 1877 * [[VUID-VkImageCreateInfo-usage-00968]] 1878 If the <<features-shaderStorageImageMultisample, 1879 pname:shaderStorageImageMultisample>> feature is not enabled, and 1880 pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples 1881 must: be ename:VK_SAMPLE_COUNT_1_BIT 1882ifndef::VKSC_VERSION_1_0[] 1883 * [[VUID-VkImageCreateInfo-flags-00969]] 1884 If the <<features-sparseBinding, pname:sparseBinding>> feature is not 1885 enabled, pname:flags must: not contain 1886 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 1887 * [[VUID-VkImageCreateInfo-flags-01924]] 1888 If the <<features-sparseResidencyAliased, pname:sparseResidencyAliased>> 1889 feature is not enabled, pname:flags must: not contain 1890 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 1891 * [[VUID-VkImageCreateInfo-tiling-04121]] 1892 If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:flags must: not 1893 contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1894 * [[VUID-VkImageCreateInfo-imageType-00970]] 1895 If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:flags must: not 1896 contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1897 * [[VUID-VkImageCreateInfo-imageType-00971]] 1898 If the <<features-sparseResidencyImage2D, pname:sparseResidencyImage2D>> 1899 feature is not enabled, and pname:imageType is ename:VK_IMAGE_TYPE_2D, 1900 pname:flags must: not contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1901 * [[VUID-VkImageCreateInfo-imageType-00972]] 1902 If the <<features-sparseResidencyImage3D, pname:sparseResidencyImage3D>> 1903 feature is not enabled, and pname:imageType is ename:VK_IMAGE_TYPE_3D, 1904 pname:flags must: not contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1905 * [[VUID-VkImageCreateInfo-imageType-00973]] 1906 If the <<features-sparseResidency2Samples, 1907 pname:sparseResidency2Samples>> feature is not enabled, pname:imageType 1908 is ename:VK_IMAGE_TYPE_2D, and pname:samples is 1909 ename:VK_SAMPLE_COUNT_2_BIT, pname:flags must: not contain 1910 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1911 * [[VUID-VkImageCreateInfo-imageType-00974]] 1912 If the <<features-sparseResidency4Samples, 1913 pname:sparseResidency4Samples>> feature is not enabled, pname:imageType 1914 is ename:VK_IMAGE_TYPE_2D, and pname:samples is 1915 ename:VK_SAMPLE_COUNT_4_BIT, pname:flags must: not contain 1916 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1917 * [[VUID-VkImageCreateInfo-imageType-00975]] 1918 If the <<features-sparseResidency8Samples, 1919 pname:sparseResidency8Samples>> feature is not enabled, pname:imageType 1920 is ename:VK_IMAGE_TYPE_2D, and pname:samples is 1921 ename:VK_SAMPLE_COUNT_8_BIT, pname:flags must: not contain 1922 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1923 * [[VUID-VkImageCreateInfo-imageType-00976]] 1924 If the <<features-sparseResidency16Samples, 1925 pname:sparseResidency16Samples>> feature is not enabled, pname:imageType 1926 is ename:VK_IMAGE_TYPE_2D, and pname:samples is 1927 ename:VK_SAMPLE_COUNT_16_BIT, pname:flags must: not contain 1928 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT 1929 * [[VUID-VkImageCreateInfo-flags-00987]] 1930 If pname:flags contains ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or 1931 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must: also contain 1932 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT 1933 * [[VUID-VkImageCreateInfo-None-01925]] 1934 If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1935 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 1936 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, 1937 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must: not also be set 1938endif::VKSC_VERSION_1_0[] 1939ifdef::VKSC_VERSION_1_0[] 1940 * [[VUID-VkImageCreateInfo-flags-05062]] 1941 pname:flags must: not contain ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1942 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, 1943 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, or 1944 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT 1945endif::VKSC_VERSION_1_0[] 1946ifdef::VK_VERSION_1_1[] 1947 * [[VUID-VkImageCreateInfo-flags-01890]] 1948 If the <<features-protectedMemory, pname:protectedMemory>> feature is 1949 not enabled, pname:flags must: not contain 1950 ename:VK_IMAGE_CREATE_PROTECTED_BIT 1951ifndef::VKSC_VERSION_1_0[] 1952 * [[VUID-VkImageCreateInfo-None-01891]] 1953 If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 1954 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 1955 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, 1956 ename:VK_IMAGE_CREATE_PROTECTED_BIT must: not also be set 1957endif::VKSC_VERSION_1_0[] 1958endif::VK_VERSION_1_1[] 1959ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1960ifdef::VK_NV_external_memory[] 1961 * [[VUID-VkImageCreateInfo-pNext-00988]] 1962 If the pname:pNext chain includes a 1963 slink:VkExternalMemoryImageCreateInfoNV structure, it must: not contain 1964 a slink:VkExternalMemoryImageCreateInfo structure 1965endif::VK_NV_external_memory[] 1966 * [[VUID-VkImageCreateInfo-pNext-00990]] 1967 If the pname:pNext chain includes a 1968 slink:VkExternalMemoryImageCreateInfo structure, its pname:handleTypes 1969 member must: only contain bits that are also in 1970 slink:VkExternalImageFormatProperties::pname:externalMemoryProperties.compatibleHandleTypes, 1971 as returned by flink:vkGetPhysicalDeviceImageFormatProperties2 with 1972 pname:format, pname:imageType, pname:tiling, pname:usage, and 1973 pname:flags equal to those in this structure, and with a 1974 slink:VkPhysicalDeviceExternalImageFormatInfo structure included in the 1975 pname:pNext chain, with a pname:handleType equal to any one of the 1976 handle types specified in 1977 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes 1978endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1979ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[] 1980 * [[VUID-VkImageCreateInfo-pNext-00991]] 1981 If the pname:pNext chain includes a 1982 slink:VkExternalMemoryImageCreateInfoNV structure, its pname:handleTypes 1983 member must: only contain bits that are also in 1984 slink:VkExternalImageFormatPropertiesNV::pname:externalMemoryProperties.compatibleHandleTypes, 1985 as returned by flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV 1986 with pname:format, pname:imageType, pname:tiling, pname:usage, and 1987 pname:flags equal to those in this structure, and with 1988 pname:externalHandleType equal to any one of the handle types specified 1989 in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes 1990endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[] 1991ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1992ifndef::VKSC_VERSION_1_0[] 1993 * [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]] 1994 If the logical device was created with 1995 slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to 1996 1, pname:flags must: not contain 1997 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT 1998 * [[VUID-VkImageCreateInfo-flags-02259]] 1999 If pname:flags contains 2000 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then 2001 pname:mipLevels must: be one, pname:arrayLayers must: be one, 2002 pname:imageType must: be ename:VK_IMAGE_TYPE_2D. 2003 and pname:imageCreateMaybeLinear (as defined in 2004 <<resources-image-creation-limits,Image Creation Limits>>) must: be 2005 ename:VK_FALSE 2006endif::VKSC_VERSION_1_0[] 2007endif::VK_VERSION_1_1,VK_KHR_device_group[] 2008ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2009 * [[VUID-VkImageCreateInfo-flags-01572]] 2010 If pname:flags contains 2011 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:format 2012 must: be a <<compressed_image_formats,compressed image format>> 2013 * [[VUID-VkImageCreateInfo-flags-01573]] 2014 If pname:flags contains 2015 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:flags 2016 must: also contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 2017endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2018 * [[VUID-VkImageCreateInfo-initialLayout-00993]] 2019 pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or 2020 ename:VK_IMAGE_LAYOUT_PREINITIALIZED 2021ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 2022 * [[VUID-VkImageCreateInfo-pNext-01443]] 2023 If the pname:pNext chain includes a 2024 slink:VkExternalMemoryImageCreateInfo or 2025 sname:VkExternalMemoryImageCreateInfoNV structure whose 2026 pname:handleTypes member is not `0`, pname:initialLayout must: be 2027 ename:VK_IMAGE_LAYOUT_UNDEFINED 2028endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 2029ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2030 * [[VUID-VkImageCreateInfo-format-06410]] 2031 If the image pname:format is one of the 2032 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 2033 sampler {YCbCr} conversion>>, pname:mipLevels must: be 1 2034 * [[VUID-VkImageCreateInfo-format-06411]] 2035 If the image pname:format is one of the 2036 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 2037 sampler {YCbCr} conversion>>, pname:samples must: be 2038 ename:VK_SAMPLE_COUNT_1_BIT 2039 * [[VUID-VkImageCreateInfo-format-06412]] 2040 If the image pname:format is one of the 2041 <<formats-requiring-sampler-ycbcr-conversion, formats that require a 2042 sampler {YCbCr} conversion>>, pname:imageType must: be 2043 ename:VK_IMAGE_TYPE_2D 2044 * [[VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260]] 2045 If pname:format is a _multi-planar_ format, and if 2046 pname:imageCreateFormatFeatures (as defined in 2047 <<resources-image-creation-limits,Image Creation Limits>>) does not 2048 contain ename:VK_FORMAT_FEATURE_DISJOINT_BIT, then pname:flags must: not 2049 contain ename:VK_IMAGE_CREATE_DISJOINT_BIT 2050 * [[VUID-VkImageCreateInfo-format-01577]] 2051 If pname:format is not a _multi-planar_ format, and pname:flags does not 2052 include ename:VK_IMAGE_CREATE_ALIAS_BIT, pname:flags must: not contain 2053 ename:VK_IMAGE_CREATE_DISJOINT_BIT 2054 * [[VUID-VkImageCreateInfo-format-04712]] 2055 If pname:format has a code:_422 or code:_420 suffix, pname:width must: 2056 be a multiple of 2 2057 * [[VUID-VkImageCreateInfo-format-04713]] 2058 If pname:format has a code:_420 suffix, pname:height must: be a multiple 2059 of 2 2060endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2061ifdef::VK_EXT_image_drm_format_modifier[] 2062 * [[VUID-VkImageCreateInfo-tiling-02261]] 2063 If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 2064 the pname:pNext chain must: include exactly one of 2065 slink:VkImageDrmFormatModifierListCreateInfoEXT or 2066 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structures 2067 * [[VUID-VkImageCreateInfo-pNext-02262]] 2068 If the pname:pNext chain includes a 2069 slink:VkImageDrmFormatModifierListCreateInfoEXT or 2070 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then 2071 pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 2072 * [[VUID-VkImageCreateInfo-tiling-02353]] 2073 If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and 2074 pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the 2075 pname:pNext chain must: include a slink:VkImageFormatListCreateInfo 2076 structure with non-zero pname:viewFormatCount 2077endif::VK_EXT_image_drm_format_modifier[] 2078ifdef::VK_EXT_sample_locations[] 2079 * [[VUID-VkImageCreateInfo-flags-01533]] 2080 If pname:flags contains 2081 ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 2082 pname:format must: be a depth or depth/stencil format 2083endif::VK_EXT_sample_locations[] 2084ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2085 * [[VUID-VkImageCreateInfo-pNext-02393]] 2086 If the pname:pNext chain includes a 2087 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 2088 member includes 2089 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, 2090 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 2091 * [[VUID-VkImageCreateInfo-pNext-02394]] 2092 If the pname:pNext chain includes a 2093 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 2094 member includes 2095 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, 2096 pname:mipLevels must: either be `1` or equal to the number of levels in 2097 the complete mipmap chain based on [eq]#pname:extent.width#, 2098 [eq]#pname:extent.height#, and [eq]#pname:extent.depth# 2099 * [[VUID-VkImageCreateInfo-pNext-02396]] 2100 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 2101 structure whose pname:externalFormat member is not `0`, pname:flags 2102 must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 2103 * [[VUID-VkImageCreateInfo-pNext-02397]] 2104 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 2105 structure whose pname:externalFormat member is not `0`, pname:usage 2106 must: not include any usages except 2107ifdef::VK_ANDROID_external_format_resolve[] 2108 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, 2109 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or 2110endif::VK_ANDROID_external_format_resolve[] 2111 ename:VK_IMAGE_USAGE_SAMPLED_BIT 2112ifdef::VK_ANDROID_external_format_resolve[] 2113 * [[VUID-VkImageCreateInfo-pNext-09457]] 2114 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 2115 structure whose pname:externalFormat member is not `0`, and 2116 <<features-externalFormatResolve, pname:externalFormatResolve>> feature 2117 is not enabled, pname:usage must: not include 2118 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or 2119 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 2120endif::VK_ANDROID_external_format_resolve[] 2121 * [[VUID-VkImageCreateInfo-pNext-02398]] 2122 If the pname:pNext chain includes a slink:VkExternalFormatANDROID 2123 structure whose pname:externalFormat member is not `0`, pname:tiling 2124 must: be ename:VK_IMAGE_TILING_OPTIMAL 2125endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2126ifdef::VK_QNX_external_memory_screen_buffer[] 2127 * [[VUID-VkImageCreateInfo-pNext-08951]] 2128 If the pname:pNext chain includes a 2129 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 2130 member includes 2131 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, 2132 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 2133 * [[VUID-VkImageCreateInfo-pNext-08952]] 2134 If the pname:pNext chain includes a 2135 slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes 2136 member includes 2137 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX, 2138 pname:mipLevels must: either be `1` or equal to the number of levels in 2139 the complete mipmap chain based on [eq]#pname:extent.width#, 2140 [eq]#pname:extent.height#, and [eq]#pname:extent.depth# 2141 * [[VUID-VkImageCreateInfo-pNext-08953]] 2142 If the pname:pNext chain includes a slink:VkExternalFormatQNX structure 2143 whose pname:externalFormat member is not `0`, pname:flags must: not 2144 include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 2145 * [[VUID-VkImageCreateInfo-pNext-08954]] 2146 If the pname:pNext chain includes a slink:VkExternalFormatQNX structure 2147 whose pname:externalFormat member is not `0`, pname:usage must: not 2148 include any usages except ename:VK_IMAGE_USAGE_SAMPLED_BIT 2149 * [[VUID-VkImageCreateInfo-pNext-08955]] 2150 If the pname:pNext chain includes a slink:VkExternalFormatQNX structure 2151 whose pname:externalFormat member is not `0`, pname:tiling must: be 2152 ename:VK_IMAGE_TILING_OPTIMAL 2153endif::VK_QNX_external_memory_screen_buffer[] 2154ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2155 * [[VUID-VkImageCreateInfo-format-02795]] 2156 If pname:format is a depth-stencil format, pname:usage includes 2157 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext 2158 chain includes a slink:VkImageStencilUsageCreateInfo structure, then its 2159 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 2160 also include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 2161 * [[VUID-VkImageCreateInfo-format-02796]] 2162 If pname:format is a depth-stencil format, pname:usage does not include 2163 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext 2164 chain includes a slink:VkImageStencilUsageCreateInfo structure, then its 2165 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 2166 also not include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 2167 * [[VUID-VkImageCreateInfo-format-02797]] 2168 If pname:format is a depth-stencil format, pname:usage includes 2169 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain 2170 includes a slink:VkImageStencilUsageCreateInfo structure, then its 2171 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 2172 also include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 2173 * [[VUID-VkImageCreateInfo-format-02798]] 2174 If pname:format is a depth-stencil format, pname:usage does not include 2175 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain 2176 includes a slink:VkImageStencilUsageCreateInfo structure, then its 2177 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: 2178 also not include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 2179 * [[VUID-VkImageCreateInfo-Format-02536]] 2180 If pname:Format is a depth-stencil format and the pname:pNext chain 2181 includes a slink:VkImageStencilUsageCreateInfo structure with its 2182 pname:stencilUsage member including 2183 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be 2184 less than or equal to 2185 sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth 2186 * [[VUID-VkImageCreateInfo-format-02537]] 2187 If pname:format is a depth-stencil format and the pname:pNext chain 2188 includes a slink:VkImageStencilUsageCreateInfo structure with its 2189 pname:stencilUsage member including 2190 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be 2191 less than or equal to 2192 sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight 2193 * [[VUID-VkImageCreateInfo-format-02538]] 2194 If the <<features-shaderStorageImageMultisample, 2195 pname:shaderStorageImageMultisample>> feature is not enabled, 2196 pname:format is a depth-stencil format and the pname:pNext chain 2197 includes a slink:VkImageStencilUsageCreateInfo structure with its 2198 pname:stencilUsage including ename:VK_IMAGE_USAGE_STORAGE_BIT, 2199 pname:samples must: be ename:VK_SAMPLE_COUNT_1_BIT 2200endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2201ifdef::VK_NV_corner_sampled_image[] 2202 * [[VUID-VkImageCreateInfo-flags-02050]] 2203 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, 2204 pname:imageType must: be ename:VK_IMAGE_TYPE_2D or 2205 ename:VK_IMAGE_TYPE_3D 2206 * [[VUID-VkImageCreateInfo-flags-02051]] 2207 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, it 2208 must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT and the 2209 pname:format must: not be a depth/stencil format 2210 * [[VUID-VkImageCreateInfo-flags-02052]] 2211 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and 2212 pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.width and 2213 pname:extent.height must: be greater than `1` 2214 * [[VUID-VkImageCreateInfo-flags-02053]] 2215 If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and 2216 pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width, 2217 pname:extent.height, and pname:extent.depth must: be greater than `1` 2218endif::VK_NV_corner_sampled_image[] 2219ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 2220 * [[VUID-VkImageCreateInfo-imageType-02082]] 2221 If pname:usage includes 2222 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 2223 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 2224 * [[VUID-VkImageCreateInfo-samples-02083]] 2225 If pname:usage includes 2226 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 2227 pname:samples must: be ename:VK_SAMPLE_COUNT_1_BIT 2228endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 2229ifdef::VK_NV_shading_rate_image[] 2230 * [[VUID-VkImageCreateInfo-shadingRateImage-07727]] 2231 If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 2232 enabled and pname:usage includes 2233 ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, pname:tiling must: be 2234 ename:VK_IMAGE_TILING_OPTIMAL 2235endif::VK_NV_shading_rate_image[] 2236ifdef::VK_EXT_fragment_density_map[] 2237 * [[VUID-VkImageCreateInfo-flags-02565]] 2238 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 2239 pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL 2240 * [[VUID-VkImageCreateInfo-flags-02566]] 2241 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 2242 pname:imageType must: be ename:VK_IMAGE_TYPE_2D 2243 * [[VUID-VkImageCreateInfo-flags-02567]] 2244 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 2245 pname:flags must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT 2246 * [[VUID-VkImageCreateInfo-flags-02568]] 2247 If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, 2248 pname:mipLevels must: be `1` 2249endif::VK_EXT_fragment_density_map[] 2250ifdef::VK_HUAWEI_invocation_mask[] 2251 * [[VUID-VkImageCreateInfo-usage-04992]] 2252 If pname:usage includes ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, 2253 pname:tiling must: be ename:VK_IMAGE_TILING_LINEAR 2254endif::VK_HUAWEI_invocation_mask[] 2255ifdef::VK_KHR_portability_subset[] 2256 * [[VUID-VkImageCreateInfo-imageView2DOn3DImage-04459]] 2257 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 2258 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageView2DOn3DImage 2259 is ename:VK_FALSE, pname:flags must: not contain 2260 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT 2261 * [[VUID-VkImageCreateInfo-multisampleArrayImage-04460]] 2262 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 2263 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:multisampleArrayImage 2264 is ename:VK_FALSE, and pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, 2265 then pname:arrayLayers must: be `1` 2266endif::VK_KHR_portability_subset[] 2267ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 2268 * [[VUID-VkImageCreateInfo-pNext-06722]] 2269 If a slink:VkImageFormatListCreateInfo structure was included in the 2270 pname:pNext chain and 2271 slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero, 2272 then each format in 2273 slink:VkImageFormatListCreateInfo::pname:pViewFormats must: either be 2274 compatible with the pname:format as described in the 2275 <<formats-compatibility,compatibility table>> or, if pname:flags 2276 contains ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, be an 2277 uncompressed format that is size-compatible with pname:format 2278 * [[VUID-VkImageCreateInfo-flags-04738]] 2279 If pname:flags does not contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 2280 and the pname:pNext chain includes a slink:VkImageFormatListCreateInfo 2281 structure, then slink:VkImageFormatListCreateInfo::pname:viewFormatCount 2282 must: be `0` or `1` 2283endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 2284ifdef::VK_KHR_video_decode_queue[] 2285 * [[VUID-VkImageCreateInfo-usage-04815]] 2286 If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, 2287 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, or 2288 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, 2289ifdef::VK_KHR_video_maintenance1[] 2290 and pname:flags does not include 2291 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, 2292endif::VK_KHR_video_maintenance1[] 2293 then the pname:pNext chain must: include a 2294 slink:VkVideoProfileListInfoKHR structure with pname:profileCount 2295 greater than `0` and pname:pProfiles including at least one 2296 slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation 2297 member specifying a decode operation 2298endif::VK_KHR_video_decode_queue[] 2299ifdef::VK_KHR_video_encode_queue[] 2300 * [[VUID-VkImageCreateInfo-usage-04816]] 2301 If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, 2302 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, or 2303 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, 2304ifdef::VK_KHR_video_maintenance1[] 2305 and pname:flags does not include 2306 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, 2307endif::VK_KHR_video_maintenance1[] 2308 then the pname:pNext chain must: include a 2309 slink:VkVideoProfileListInfoKHR structure with pname:profileCount 2310 greater than `0` and pname:pProfiles including at least one 2311 slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation 2312 member specifying an encode operation 2313endif::VK_KHR_video_encode_queue[] 2314ifdef::VK_KHR_video_maintenance1[] 2315 * [[VUID-VkImageCreateInfo-flags-08328]] 2316 If pname:flags includes 2317 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then 2318 <<features-videoMaintenance1,pname:videoMaintenance1>> must: be enabled 2319ifdef::VK_KHR_video_decode_queue[] 2320 * [[VUID-VkImageCreateInfo-flags-08329]] 2321 If pname:flags includes 2322 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage 2323 does not include ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then 2324 pname:usage must: not include 2325 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR 2326endif::VK_KHR_video_decode_queue[] 2327ifdef::VK_KHR_video_encode_queue[] 2328 * [[VUID-VkImageCreateInfo-flags-08331]] 2329 If pname:flags includes 2330 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then 2331 pname:usage must: not include 2332 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR 2333endif::VK_KHR_video_encode_queue[] 2334endif::VK_KHR_video_maintenance1[] 2335ifdef::VK_KHR_video_queue[] 2336 * [[VUID-VkImageCreateInfo-pNext-06811]] 2337 If the pname:pNext chain includes a slink:VkVideoProfileListInfoKHR 2338 structure with pname:profileCount greater than `0`, then 2339 pname:supportedVideoFormat must: be ename:VK_TRUE 2340endif::VK_KHR_video_queue[] 2341ifdef::VK_FUCHSIA_buffer_collection[] 2342 * [[VUID-VkImageCreateInfo-pNext-06390]] 2343 If the slink:VkImage is to be used to import memory from a 2344 slink:VkBufferCollectionFUCHSIA, a 2345 slink:VkBufferCollectionImageCreateInfoFUCHSIA structure must: be 2346 chained to pname:pNext 2347endif::VK_FUCHSIA_buffer_collection[] 2348ifdef::VK_EXT_multisampled_render_to_single_sampled[] 2349 * [[VUID-VkImageCreateInfo-multisampledRenderToSingleSampled-06882]] 2350 If the <<features-multisampledRenderToSingleSampled, 2351 pname:multisampledRenderToSingleSampled>> feature is not enabled, 2352 pname:flags must: not contain 2353 ename:VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT 2354 * [[VUID-VkImageCreateInfo-flags-06883]] 2355 If pname:flags contains 2356 ename:VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT, 2357 pname:samples must: be ename:VK_SAMPLE_COUNT_1_BIT 2358endif::VK_EXT_multisampled_render_to_single_sampled[] 2359ifdef::VK_EXT_image_compression_control[] 2360ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2361 * [[VUID-VkImageCreateInfo-pNext-06743]] 2362 If the pname:pNext chain includes a slink:VkImageCompressionControlEXT 2363 structure, pname:format is a 2364 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and 2365 slink:VkImageCompressionControlEXT::pname:flags includes 2366 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then 2367 slink:VkImageCompressionControlEXT::pname:compressionControlPlaneCount 2368 must: be equal to the number of planes in pname:format 2369 * [[VUID-VkImageCreateInfo-pNext-06744]] 2370 If the pname:pNext chain includes a slink:VkImageCompressionControlEXT 2371 structure, pname:format is not a 2372 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and 2373 slink:VkImageCompressionControlEXT::pname:flags includes 2374 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then 2375 slink:VkImageCompressionControlEXT::pname:compressionControlPlaneCount 2376 must: be 1 2377endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2378ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2379 * [[VUID-VkImageCreateInfo-pNext-06745]] 2380 If the pname:pNext chain includes a slink:VkImageCompressionControlEXT 2381 structure, and slink:VkImageCompressionControlEXT::pname:flags includes 2382 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then 2383 slink:VkImageCompressionControlEXT::pname:compressionControlPlaneCount 2384 must: be 1 2385endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2386ifdef::VK_EXT_image_drm_format_modifier[] 2387 * [[VUID-VkImageCreateInfo-pNext-06746]] 2388 If the pname:pNext chain includes a slink:VkImageCompressionControlEXT 2389 structure, it must: not contain a 2390 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure 2391endif::VK_EXT_image_drm_format_modifier[] 2392endif::VK_EXT_image_compression_control[] 2393ifdef::VK_EXT_descriptor_buffer[] 2394 * [[VUID-VkImageCreateInfo-flags-08104]] 2395 If pname:flags includes 2396 ename:VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the 2397 <<features-descriptorBufferCaptureReplay, 2398 pname:descriptorBufferCaptureReplay>> feature must: be enabled 2399 * [[VUID-VkImageCreateInfo-pNext-08105]] 2400 If the pname:pNext chain includes a 2401 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, pname:flags 2402 must: contain 2403 ename:VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 2404endif::VK_EXT_descriptor_buffer[] 2405ifdef::VK_EXT_metal_objects[] 2406 * [[VUID-VkImageCreateInfo-pNext-06783]] 2407 If the pname:pNext chain includes a 2408 slink:VkExportMetalObjectCreateInfoEXT structure, its 2409 pname:exportObjectType member must: be either 2410 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT or 2411 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_IOSURFACE_BIT_EXT 2412 * [[VUID-VkImageCreateInfo-pNext-06784]] 2413 If the pname:pNext chain includes a slink:VkImportMetalTextureInfoEXT 2414 structure its pname:plane member must: be 2415 ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 2416 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 2417 * [[VUID-VkImageCreateInfo-pNext-06785]] 2418 If the pname:pNext chain includes a slink:VkImportMetalTextureInfoEXT 2419 structure and the image does not have a multi-planar format, then 2420 slink:VkImportMetalTextureInfoEXT::pname:plane must: be 2421 ename:VK_IMAGE_ASPECT_PLANE_0_BIT 2422 * [[VUID-VkImageCreateInfo-pNext-06786]] 2423 If the pname:pNext chain includes a slink:VkImportMetalTextureInfoEXT 2424 structure and the image has a multi-planar format with only two planes, 2425 then slink:VkImportMetalTextureInfoEXT::pname:plane must: not be 2426 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 2427endif::VK_EXT_metal_objects[] 2428ifdef::VK_EXT_host_image_copy[] 2429 * [[VUID-VkImageCreateInfo-imageCreateFormatFeatures-09048]] 2430 If pname:imageCreateFormatFeatures (as defined in 2431 <<resources-image-creation-limits,Image Creation Limits>>) does not 2432 contain ename:VK_FORMAT_FEATURE_2_HOST_IMAGE_TRANSFER_BIT_EXT, then 2433 pname:usage must: not contain ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT 2434endif::VK_EXT_host_image_copy[] 2435**** 2436ifdef::VKSC_VERSION_1_0[] 2437ifdef::hidden[] 2438// tag::scdeviation[] 2439 * slink:VkImageCreateInfo::pname:flags must: not contain any of the 2440 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 2441 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, 2442 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, or 2443 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT flags <<SCID-8>>. 2444// end::scdeviation[] 2445endif::hidden[] 2446endif::VKSC_VERSION_1_0[] 2447 2448include::{generated}/validity/structs/VkImageCreateInfo.adoc[] 2449-- 2450 2451ifdef::VK_FUCHSIA_buffer_collection[] 2452[open,refpage='VkBufferCollectionImageCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkImage',type='structs'] 2453-- 2454The sname:VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as: 2455 2456include::{generated}/api/structs/VkBufferCollectionImageCreateInfoFUCHSIA.adoc[] 2457 2458 * pname:sType is a elink:VkStructureType value identifying this structure. 2459 * pname:pNext is `NULL` or a pointer to a structure extending this 2460 structure 2461 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 2462 * pname:index is the index of the buffer in the buffer collection from 2463 which the memory will be imported 2464 2465.Valid Usage 2466**** 2467 * [[VUID-VkBufferCollectionImageCreateInfoFUCHSIA-index-06391]] 2468 pname:index must: be less than 2469 slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount 2470**** 2471 2472include::{generated}/validity/structs/VkBufferCollectionImageCreateInfoFUCHSIA.adoc[] 2473-- 2474endif::VK_FUCHSIA_buffer_collection[] 2475 2476ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2477[open,refpage='VkImageStencilUsageCreateInfo',desc='Specify separate usage flags for the stencil aspect of a depth-stencil image',type='structs',alias='VkImageStencilUsageCreateInfoEXT'] 2478-- 2479The sname:VkImageStencilUsageCreateInfo structure is defined as: 2480 2481include::{generated}/api/structs/VkImageStencilUsageCreateInfo.adoc[] 2482 2483ifdef::VK_EXT_separate_stencil_usage[] 2484or the equivalent 2485 2486include::{generated}/api/structs/VkImageStencilUsageCreateInfoEXT.adoc[] 2487endif::VK_EXT_separate_stencil_usage[] 2488 2489 * pname:sType is a elink:VkStructureType value identifying this structure. 2490 * pname:pNext is `NULL` or a pointer to a structure extending this 2491 structure. 2492 * pname:stencilUsage is a bitmask of elink:VkImageUsageFlagBits describing 2493 the intended usage of the stencil aspect of the image. 2494 2495If the pname:pNext chain of slink:VkImageCreateInfo includes a 2496sname:VkImageStencilUsageCreateInfo structure, then that structure includes 2497the usage flags specific to the stencil aspect of the image for an image 2498with a depth-stencil format. 2499 2500This structure specifies image usages which only apply to the stencil aspect 2501of a depth/stencil format image. 2502When this structure is included in the pname:pNext chain of 2503slink:VkImageCreateInfo, the stencil aspect of the image must: only be used 2504as specified by pname:stencilUsage. 2505When this structure is not included in the pname:pNext chain of 2506slink:VkImageCreateInfo, the stencil aspect of an image must: only be used 2507as specified by slink:VkImageCreateInfo::pname:usage. 2508Use of other aspects of an image are unaffected by this structure. 2509 2510This structure can: also be included in the pname:pNext chain of 2511slink:VkPhysicalDeviceImageFormatInfo2 to query additional capabilities 2512specific to image creation parameter combinations including a separate set 2513of usage flags for the stencil aspect of the image using 2514flink:vkGetPhysicalDeviceImageFormatProperties2. 2515When this structure is not included in the pname:pNext chain of 2516sname:VkPhysicalDeviceImageFormatInfo2 then the implicit value of 2517pname:stencilUsage matches that of 2518sname:VkPhysicalDeviceImageFormatInfo2::pname:usage. 2519 2520.Valid Usage 2521**** 2522 * [[VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539]] 2523 If pname:stencilUsage includes 2524 ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, it must: not include bits 2525 other than ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT or 2526 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 2527**** 2528 2529include::{generated}/validity/structs/VkImageStencilUsageCreateInfo.adoc[] 2530-- 2531endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 2532 2533ifdef::VK_NV_dedicated_allocation[] 2534[open,refpage='VkDedicatedAllocationImageCreateInfoNV',desc='Specify that an image is bound to a dedicated memory resource',type='structs'] 2535-- 2536If the pname:pNext chain includes a 2537sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure 2538includes an enable controlling whether the image will have a dedicated 2539memory allocation bound to it. 2540 2541The sname:VkDedicatedAllocationImageCreateInfoNV structure is defined as: 2542 2543include::{generated}/api/structs/VkDedicatedAllocationImageCreateInfoNV.adoc[] 2544 2545 * pname:sType is a elink:VkStructureType value identifying this structure. 2546 * pname:pNext is `NULL` or a pointer to a structure extending this 2547 structure. 2548 * pname:dedicatedAllocation specifies whether the image will have a 2549 dedicated allocation bound to it. 2550 2551[NOTE] 2552.Note 2553==== 2554Using a dedicated allocation for color and depth/stencil attachments or 2555other large images may: improve performance on some devices. 2556==== 2557 2558.Valid Usage 2559**** 2560 * [[VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994]] 2561 If pname:dedicatedAllocation is ename:VK_TRUE, 2562 slink:VkImageCreateInfo::pname:flags must: not include 2563 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 2564 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 2565 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 2566**** 2567 2568include::{generated}/validity/structs/VkDedicatedAllocationImageCreateInfoNV.adoc[] 2569-- 2570endif::VK_NV_dedicated_allocation[] 2571 2572ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 2573[open,refpage='VkExternalMemoryImageCreateInfo',desc='Specify that an image may be backed by external memory',type='structs'] 2574-- 2575To define a set of external memory handle types that may: be used as backing 2576store for an image, add a slink:VkExternalMemoryImageCreateInfo structure to 2577the pname:pNext chain of the slink:VkImageCreateInfo structure. 2578The sname:VkExternalMemoryImageCreateInfo structure is defined as: 2579 2580include::{generated}/api/structs/VkExternalMemoryImageCreateInfo.adoc[] 2581 2582ifdef::VK_KHR_external_memory[] 2583or the equivalent 2584 2585include::{generated}/api/structs/VkExternalMemoryImageCreateInfoKHR.adoc[] 2586endif::VK_KHR_external_memory[] 2587 2588[NOTE] 2589.Note 2590==== 2591A sname:VkExternalMemoryImageCreateInfo structure with a non-zero 2592pname:handleTypes field must be included in the creation parameters for an 2593image that will be bound to memory that is either exported or imported. 2594==== 2595 2596 * pname:sType is a elink:VkStructureType value identifying this structure. 2597 * pname:pNext is `NULL` or a pointer to a structure extending this 2598 structure. 2599 * pname:handleTypes is zero or a bitmask of 2600 elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external 2601 memory handle types. 2602 2603include::{generated}/validity/structs/VkExternalMemoryImageCreateInfo.adoc[] 2604-- 2605endif::VK_VERSION_1_1,VK_KHR_external_memory[] 2606 2607ifdef::VK_NV_external_memory[] 2608[open,refpage='VkExternalMemoryImageCreateInfoNV',desc='Specify that an image may be backed by external memory',type='structs'] 2609-- 2610If the pname:pNext chain includes a sname:VkExternalMemoryImageCreateInfoNV 2611structure, then that structure defines a set of external memory handle types 2612that may: be used as backing store for the image. 2613 2614The sname:VkExternalMemoryImageCreateInfoNV structure is defined as: 2615 2616include::{generated}/api/structs/VkExternalMemoryImageCreateInfoNV.adoc[] 2617 2618 * pname:sType is a elink:VkStructureType value identifying this structure. 2619 * pname:pNext is `NULL` or a pointer to a structure extending this 2620 structure. 2621 * pname:handleTypes is zero or a bitmask of 2622 elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more 2623 external memory handle types. 2624 2625include::{generated}/validity/structs/VkExternalMemoryImageCreateInfoNV.adoc[] 2626-- 2627endif::VK_NV_external_memory[] 2628 2629ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 2630[open,refpage='VkExternalFormatANDROID',desc='Structure containing an Android hardware buffer external format',type='structs'] 2631-- 2632sname:VkExternalFormatANDROID is defined as: 2633 2634include::{generated}/api/structs/VkExternalFormatANDROID.adoc[] 2635 2636 * pname:sType is a elink:VkStructureType value identifying this structure. 2637 * pname:pNext is `NULL` or a pointer to a structure extending this 2638 structure. 2639 * pname:externalFormat is an implementation-defined identifier for the 2640 external format 2641 2642When included in the pname:pNext chain of another structure, it indicates 2643<<memory-external-android-hardware-buffer-external-formats, additional 2644format information>> beyond what is provided by ename:VkFormat values for an 2645Android hardware buffer. 2646If pname:externalFormat is zero, it indicates that no external format is 2647used, and implementations should rely only on other format information. 2648If this structure is not present, it is equivalent to setting 2649pname:externalFormat to zero. 2650 2651.Valid Usage 2652**** 2653 * [[VUID-VkExternalFormatANDROID-externalFormat-01894]] 2654 pname:externalFormat must: be `0` or a value returned in the 2655 pname:externalFormat member of 2656 slink:VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call 2657 to flink:vkGetAndroidHardwareBufferPropertiesANDROID 2658**** 2659 2660include::{generated}/validity/structs/VkExternalFormatANDROID.adoc[] 2661-- 2662endif::VK_ANDROID_external_memory_android_hardware_buffer[] 2663 2664ifdef::VK_QNX_external_memory_screen_buffer[] 2665[open,refpage='VkExternalFormatQNX',desc='Structure containing a QNX Screen buffer external format',type='structs'] 2666-- 2667To create an image with an 2668<<memory-external-screen-buffer-external-formats,QNX Screen external 2669format>>, add a sname:VkExternalFormatQNX structure in the pname:pNext chain 2670of slink:VkImageCreateInfo. 2671sname:VkExternalFormatQNX is defined as: 2672 2673include::{generated}/api/structs/VkExternalFormatQNX.adoc[] 2674 2675 * pname:sType is a elink:VkStructureType value identifying this structure. 2676 * pname:pNext is `NULL` or a pointer to a structure extending this 2677 structure. 2678 * pname:externalFormat is an implementation-defined identifier for the 2679 external format 2680 2681If pname:externalFormat is zero, the effect is as if the 2682sname:VkExternalFormatQNX structure was not present. 2683Otherwise, the pname:image will have the specified external format. 2684 2685.Valid Usage 2686**** 2687 * [[VUID-VkExternalFormatQNX-externalFormat-08956]] 2688 pname:externalFormat must: be `0` or a value returned in the 2689 pname:externalFormat member of slink:VkScreenBufferFormatPropertiesQNX 2690 by an earlier call to flink:vkGetScreenBufferPropertiesQNX 2691**** 2692 2693include::{generated}/validity/structs/VkExternalFormatQNX.adoc[] 2694-- 2695endif::VK_QNX_external_memory_screen_buffer[] 2696 2697ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 2698ifdef::VK_KHR_swapchain[] 2699[open,refpage='VkImageSwapchainCreateInfoKHR',desc='Specify that an image will be bound to swapchain memory',type='structs'] 2700-- 2701If the pname:pNext chain of slink:VkImageCreateInfo includes a 2702sname:VkImageSwapchainCreateInfoKHR structure, then that structure includes 2703a swapchain handle indicating that the image will be bound to memory from 2704that swapchain. 2705 2706The sname:VkImageSwapchainCreateInfoKHR structure is defined as: 2707 2708include::{generated}/api/structs/VkImageSwapchainCreateInfoKHR.adoc[] 2709 2710 * pname:sType is a elink:VkStructureType value identifying this structure. 2711 * pname:pNext is `NULL` or a pointer to a structure extending this 2712 structure. 2713 * pname:swapchain is dlink:VK_NULL_HANDLE or a handle of a swapchain that 2714 the image will be bound to. 2715 2716.Valid Usage 2717**** 2718 * [[VUID-VkImageSwapchainCreateInfoKHR-swapchain-00995]] 2719 If pname:swapchain is not dlink:VK_NULL_HANDLE, the fields of 2720 slink:VkImageCreateInfo must: match the 2721 <<swapchain-wsi-image-create-info, implied image creation parameters>> 2722 of the swapchain 2723**** 2724 2725include::{generated}/validity/structs/VkImageSwapchainCreateInfoKHR.adoc[] 2726-- 2727endif::VK_KHR_swapchain[] 2728endif::VK_VERSION_1_1,VK_KHR_device_group[] 2729 2730ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 2731[open,refpage='VkImageFormatListCreateInfo',desc='Specify that an image can: be used with a particular set of formats',type='structs',alias='VkImageFormatListCreateInfoKHR'] 2732-- 2733If the pname:pNext chain of slink:VkImageCreateInfo includes a 2734sname:VkImageFormatListCreateInfo structure, then that structure contains a 2735list of all formats that can: be used when creating views of this image. 2736 2737The sname:VkImageFormatListCreateInfo structure is defined as: 2738 2739include::{generated}/api/structs/VkImageFormatListCreateInfo.adoc[] 2740 2741ifdef::VK_KHR_image_format_list[] 2742or the equivalent 2743 2744include::{generated}/api/structs/VkImageFormatListCreateInfoKHR.adoc[] 2745endif::VK_KHR_image_format_list[] 2746 2747 * pname:sType is a elink:VkStructureType value identifying this structure. 2748 * pname:pNext is `NULL` or a pointer to a structure extending this 2749 structure. 2750 * pname:viewFormatCount is the number of entries in the pname:pViewFormats 2751 array. 2752 * pname:pViewFormats is a pointer to an array of elink:VkFormat values 2753 specifying all formats which can: be used when creating views of this 2754 image. 2755 2756If pname:viewFormatCount is zero, pname:pViewFormats is ignored and the 2757image is created as if the sname:VkImageFormatListCreateInfo structure were 2758not included in the pname:pNext chain of slink:VkImageCreateInfo. 2759 2760include::{generated}/validity/structs/VkImageFormatListCreateInfo.adoc[] 2761-- 2762endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 2763 2764ifdef::VK_EXT_image_drm_format_modifier[] 2765[open,refpage='VkImageDrmFormatModifierListCreateInfoEXT',desc='Specify that an image must be created with a DRM format modifier from the provided list',type='structs'] 2766-- 2767If the pname:pNext chain of slink:VkImageCreateInfo includes a 2768slink:VkImageDrmFormatModifierListCreateInfoEXT structure, then the image 2769will be created with one of the <<glossary-drm-format-modifier,Linux DRM 2770format modifiers>> listed in the structure. 2771The choice of modifier is implementation-dependent. 2772 2773The slink:VkImageDrmFormatModifierListCreateInfoEXT structure is defined as: 2774 2775include::{generated}/api/structs/VkImageDrmFormatModifierListCreateInfoEXT.adoc[] 2776 2777 * pname:sType is a elink:VkStructureType value identifying this structure. 2778 * pname:pNext is `NULL` or a pointer to a structure extending this 2779 structure. 2780 * pname:drmFormatModifierCount is the length of the 2781 pname:pDrmFormatModifiers array. 2782 * pname:pDrmFormatModifiers is a pointer to an array of _Linux DRM format 2783 modifiers_. 2784 2785.Valid Usage 2786**** 2787 * [[VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-02263]] 2788 Each _modifier_ in pname:pDrmFormatModifiers must: be compatible with 2789 the parameters in slink:VkImageCreateInfo and its pname:pNext chain, as 2790 determined by querying slink:VkPhysicalDeviceImageFormatInfo2 extended 2791 with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 2792**** 2793 2794include::{generated}/validity/structs/VkImageDrmFormatModifierListCreateInfoEXT.adoc[] 2795-- 2796 2797[open,refpage='VkImageDrmFormatModifierExplicitCreateInfoEXT',desc='Specify that an image be created with the provided DRM format modifier and explicit memory layout',type='structs'] 2798-- 2799If the pname:pNext chain of slink:VkImageCreateInfo includes a 2800slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the 2801image will be created with the <<glossary-drm-format-modifier,Linux DRM 2802format modifier>> and memory layout defined by the structure. 2803 2804The slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined 2805as: 2806 2807include::{generated}/api/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.adoc[] 2808 2809 * pname:sType is a elink:VkStructureType value identifying this structure. 2810 * pname:pNext is `NULL` or a pointer to a structure extending this 2811 structure. 2812 * pname:drmFormatModifier is the _Linux DRM format modifier_ with which 2813 the image will be created. 2814 * pname:drmFormatModifierPlaneCount is the number of _memory planes_ in 2815 the image (as reported by slink:VkDrmFormatModifierPropertiesEXT) as 2816 well as the length of the pname:pPlaneLayouts array. 2817 * pname:pPlaneLayouts is a pointer to an array of 2818 slink:VkSubresourceLayout structures describing the image's _memory 2819 planes_. 2820 2821The etext:i^th^ member of pname:pPlaneLayouts describes the layout of the 2822image's etext:i^th^ _memory plane_ (that is, 2823`VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`). 2824In each element of pname:pPlaneLayouts, the implementation must: ignore 2825pname:size. 2826The implementation calculates the size of each plane, which the application 2827can: query with flink:vkGetImageSubresourceLayout. 2828 2829When creating an image with 2830slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application's 2831responsibility to satisfy all valid usage requirements. 2832However, the implementation must: validate that the provided 2833pname:pPlaneLayouts, when combined with the provided pname:drmFormatModifier 2834and other creation parameters in slink:VkImageCreateInfo and its pname:pNext 2835chain, produce a valid image. 2836(This validation is necessarily implementation-dependent and outside the 2837scope of Vulkan, and therefore not described by valid usage requirements). 2838If this validation fails, then flink:vkCreateImage returns 2839ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. 2840 2841.Valid Usage 2842**** 2843 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifier-02264]] 2844 pname:drmFormatModifier must: be compatible with the parameters in 2845 slink:VkImageCreateInfo and its pname:pNext chain, as determined by 2846 querying slink:VkPhysicalDeviceImageFormatInfo2 extended with 2847 slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 2848 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-02265]] 2849 pname:drmFormatModifierPlaneCount must: be equal to the 2850 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 2851 associated with slink:VkImageCreateInfo::pname:format and 2852 pname:drmFormatModifier, as found by querying 2853 slink:VkDrmFormatModifierPropertiesListEXT 2854 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-size-02267]] 2855 For each element of pname:pPlaneLayouts, pname:size must: be 0 2856 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-arrayPitch-02268]] 2857 For each element of pname:pPlaneLayouts, pname:arrayPitch must: be 0 if 2858 slink:VkImageCreateInfo::pname:arrayLayers is 1 2859 * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-depthPitch-02269]] 2860 For each element of pname:pPlaneLayouts, pname:depthPitch must: be 0 if 2861 slink:VkImageCreateInfo::pname:extent.depth is 1 2862**** 2863 2864include::{generated}/validity/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.adoc[] 2865-- 2866endif::VK_EXT_image_drm_format_modifier[] 2867 2868ifdef::VK_EXT_image_compression_control[] 2869[open,refpage='VkImageCompressionControlEXT',desc='Specify image compression properties',type='structs'] 2870-- 2871If the pname:pNext list of slink:VkImageCreateInfo includes a 2872sname:VkImageCompressionControlEXT structure, then that structure describes 2873compression controls for this image. 2874 2875The sname:VkImageCompressionControlEXT structure is defined as: 2876 2877include::{generated}/api/structs/VkImageCompressionControlEXT.adoc[] 2878 2879 * pname:sType is a elink:VkStructureType value identifying this structure. 2880 * pname:pNext is `NULL` or a pointer to a structure extending this 2881 structure. 2882 * pname:flags is a bitmask of elink:VkImageCompressionFlagBitsEXT 2883 describing compression controls for the image. 2884 * pname:compressionControlPlaneCount is the number of entries in the 2885 pname:pFixedRateFlags array. 2886 * pname:pFixedRateFlags is `NULL` or a pointer to an array of 2887 tlink:VkImageCompressionFixedRateFlagsEXT bitfields describing allowed 2888 fixed-rate compression rates of each image plane. 2889 It is ignored if pname:flags does not include 2890 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT. 2891 2892If enabled, fixed-rate compression is done in an implementation-defined 2893manner and may: be applied at block granularity. 2894In that case, a write to an individual texel may: modify the value of other 2895texels in the same block. 2896 2897.Valid Usage 2898**** 2899 * [[VUID-VkImageCompressionControlEXT-flags-06747]] 2900 pname:flags must: be one of ename:VK_IMAGE_COMPRESSION_DEFAULT_EXT, 2901 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT, 2902 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, or 2903 ename:VK_IMAGE_COMPRESSION_DISABLED_EXT 2904 * [[VUID-VkImageCompressionControlEXT-flags-06748]] 2905 If pname:flags includes 2906 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, 2907 pname:pFixedRateFlags must: not be `NULL` 2908**** 2909 2910include::{generated}/validity/structs/VkImageCompressionControlEXT.adoc[] 2911 2912[NOTE] 2913.Note 2914==== 2915Some combinations of compression properties may not be supported. 2916For example, some implementations may not support different fixed-rate 2917compression rates per plane of a multi-planar format and will not be able to 2918enable fixed-rate compression for any plane if the requested rates differ. 2919==== 2920-- 2921 2922[open,refpage='VkImageCompressionFlagBitsEXT',desc='Bitmask specifying image compression controls',type='enums'] 2923-- 2924Possible values of slink:VkImageCompressionControlEXT::pname:flags, 2925specifying compression controls for an image, are: 2926 2927include::{generated}/api/enums/VkImageCompressionFlagBitsEXT.adoc[] 2928 2929 * ename:VK_IMAGE_COMPRESSION_DEFAULT_EXT specifies that the default image 2930 compression setting is used. 2931 Implementations must: not apply fixed-rate compression. 2932 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_DEFAULT_EXT specifies that the 2933 implementation may: choose any supported fixed-rate compression setting 2934 in an implementation-defined manner based on the properties of the 2935 image. 2936 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT specifies that 2937 fixed-rate compression may: be used and that the allowed compression 2938 rates are specified by 2939 slink:VkImageCompressionControlEXT::pname:pFixedRateFlags. 2940 * ename:VK_IMAGE_COMPRESSION_DISABLED_EXT specifies that all lossless and 2941 fixed-rate compression should: be disabled. 2942 2943If slink:VkImageCompressionControlEXT::pname:flags is 2944ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, then the etext:i^th^ 2945member of the pname:pFixedRateFlags array specifies the allowed compression 2946rates for the image's etext:i^th^ plane. 2947 2948[NOTE] 2949.Note 2950==== 2951If ename:VK_IMAGE_COMPRESSION_DISABLED_EXT is included in 2952slink:VkImageCompressionControlEXT::pname:flags, both lossless and 2953fixed-rate compression will be disabled. 2954This is likely to have a negative impact on performance and is only intended 2955to be used for debugging purposes. 2956==== 2957-- 2958 2959[open,refpage='VkImageCompressionFlagsEXT',desc='Bitmask of VkImageCompressionFlagBitsEXT', type='flags'] 2960-- 2961include::{generated}/api/flags/VkImageCompressionFlagsEXT.adoc[] 2962 2963tname:VkImageCompressionFlagsEXT is a bitmask type for setting a mask of 2964zero or more elink:VkImageCompressionFlagBitsEXT. 2965-- 2966 2967[open,refpage='VkImageCompressionFixedRateFlagsEXT',desc='Bitmask of VkImageCompressionFixedRateFlagBitsEXT',type='flags'] 2968-- 2969include::{generated}/api/flags/VkImageCompressionFixedRateFlagsEXT.adoc[] 2970 2971tname:VkImageCompressionFixedRateFlagsEXT is a bitmask type for setting a 2972mask of zero or more elink:VkImageCompressionFixedRateFlagBitsEXT. 2973-- 2974 2975[open,refpage='VkImageCompressionFixedRateFlagBitsEXT',desc='Bitmask specifying fixed rate image compression rates',type='enums'] 2976-- 2977Bits which can: be set in 2978slink:VkImageCompressionControlEXT::pname:pFixedRateFlags, specifying 2979allowed compression rates for an image plane, are: 2980 2981include::{generated}/api/enums/VkImageCompressionFixedRateFlagBitsEXT.adoc[] 2982 2983 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_NONE_EXT specifies that fixed-rate 2984 compression must: not be used. 2985 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_1BPC_BIT_EXT specifies that 2986 fixed-rate compression with a bitrate of [eq]#[1,2)# bits per component 2987 may: be used. 2988 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT specifies that 2989 fixed-rate compression with a bitrate of [eq]#[2,3)# bits per component 2990 may: be used. 2991 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_3BPC_BIT_EXT specifies that 2992 fixed-rate compression with a bitrate of [eq]#[3,4)# bits per component 2993 may: be used. 2994 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT specifies that 2995 fixed-rate compression with a bitrate of [eq]#[4,5)# bits per component 2996 may: be used. 2997 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_5BPC_BIT_EXT specifies that 2998 fixed-rate compression with a bitrate of [eq]#[5,6)# bits per component 2999 may: be used. 3000 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_6BPC_BIT_EXT specifies that 3001 fixed-rate compression with a bitrate of [eq]#[6,7)# bits per component 3002 may: be used. 3003 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_7BPC_BIT_EXT specifies that 3004 fixed-rate compression with a bitrate of [eq]#[7,8)# bits per component 3005 may: be used. 3006 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_8BPC_BIT_EXT specifies that 3007 fixed-rate compression with a bitrate of [eq]#[8,9)# bits per component 3008 may: be used. 3009 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_9BPC_BIT_EXT specifies that 3010 fixed-rate compression with a bitrate of [eq]#[9,10)# bits per component 3011 may: be used. 3012 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_10BPC_BIT_EXT specifies that 3013 fixed-rate compression with a bitrate of [eq]#[10,11)# bits per 3014 component may: be used. 3015 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_11BPC_BIT_EXT specifies that 3016 fixed-rate compression with a bitrate of [eq]#[11,12)# bits per 3017 component may: be used. 3018 * ename:VK_IMAGE_COMPRESSION_FIXED_RATE_12BPC_BIT_EXT specifies that 3019 fixed-rate compression with a bitrate of at least 12 bits per component 3020 may: be used. 3021 3022If the format has a different bit rate for different components, 3023slink:VkImageCompressionControlEXT::pname:pFixedRateFlags describes the rate 3024of the component with the largest number of bits assigned to it, scaled pro 3025rata. 3026For example, to request that a ename:VK_FORMAT_A2R10G10B10_UNORM_PACK32 3027format be stored at a rate of 8 bits per pixel, use 3028ename:VK_IMAGE_COMPRESSION_FIXED_RATE_2BPC_BIT_EXT (10 bits for the largest 3029component, stored at quarter the original size, 2.5 bits, rounded down). 3030 3031If pname:flags includes ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT, 3032and multiple bits are set in 3033slink:VkImageCompressionControlEXT::pname:pFixedRateFlags for a plane, 3034implementations should: apply the lowest allowed bitrate that is supported. 3035 3036[NOTE] 3037.Note 3038==== 3039The choice of "`bits per component`" terminology was chosen so that the same 3040compression rate describes the same degree of compression applied to formats 3041that differ only in the number of components. 3042For example, ename:VK_FORMAT_R8G8_UNORM compressed to half its original size 3043is a rate of 4 bits per component, 8 bits per pixel. 3044ename:VK_FORMAT_R8G8B8A8_UNORM compressed to half _its_ original size is 4 3045bits per component, 16 bits per pixel. 3046Both of these cases can be requested with 3047ename:VK_IMAGE_COMPRESSION_FIXED_RATE_4BPC_BIT_EXT. 3048==== 3049-- 3050 3051[open,refpage='VkImageCompressionPropertiesEXT',desc='Compression properties of an image',type='structs'] 3052-- 3053To query the compression properties of an image, add a 3054slink:VkImageCompressionPropertiesEXT structure to the pname:pNext chain of 3055the slink:VkSubresourceLayout2EXT structure in a call to 3056ifdef::VK_KHR_maintenance5[flink:vkGetImageSubresourceLayout2KHR or] 3057flink:vkGetImageSubresourceLayout2EXT. 3058 3059To determine the compression rates that are supported for a given image 3060format, add a slink:VkImageCompressionPropertiesEXT structure to the 3061pname:pNext chain of the slink:VkImageFormatProperties2 structure in a call 3062to flink:vkGetPhysicalDeviceImageFormatProperties2. 3063 3064[NOTE] 3065.Note 3066==== 3067Since fixed-rate compression is disabled by default, the 3068slink:VkImageCompressionPropertiesEXT structure passed to 3069flink:vkGetPhysicalDeviceImageFormatProperties2 will not indicate any 3070fixed-rate compression support unless a slink:VkImageCompressionControlEXT 3071structure is also included in the pname:pNext chain of the 3072slink:VkPhysicalDeviceImageFormatInfo2 structure passed to the same command. 3073==== 3074 3075The sname:VkImageCompressionPropertiesEXT structure is defined as: 3076 3077include::{generated}/api/structs/VkImageCompressionPropertiesEXT.adoc[] 3078 3079 * pname:sType is a elink:VkStructureType value identifying this structure. 3080 * pname:pNext is `NULL` or a pointer to a structure extending this 3081 structure. 3082 * pname:imageCompressionFlags returns a value describing the compression 3083 controls that apply to the image. 3084 The value will be either ename:VK_IMAGE_COMPRESSION_DEFAULT_EXT to 3085 indicate no fixed-rate compression, 3086 ename:VK_IMAGE_COMPRESSION_FIXED_RATE_EXPLICIT_EXT to indicate 3087 fixed-rate compression, or ename:VK_IMAGE_COMPRESSION_DISABLED_EXT to 3088 indicate no compression. 3089 * pname:imageCompressionFixedRateFlags returns a 3090 tlink:VkImageCompressionFixedRateFlagsEXT value describing the 3091 compression rates that apply to the specified aspect of the image. 3092 3093include::{generated}/validity/structs/VkImageCompressionPropertiesEXT.adoc[] 3094-- 3095endif::VK_EXT_image_compression_control[] 3096 3097[open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums'] 3098-- 3099Bits which can: be set in 3100 3101ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3102 * slink:VkImageViewUsageCreateInfo::pname:usage 3103endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3104ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3105 * slink:VkImageStencilUsageCreateInfo::pname:stencilUsage 3106endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 3107 * slink:VkImageCreateInfo::pname:usage 3108 3109specify intended usage of an image, and are: 3110 3111include::{generated}/api/enums/VkImageUsageFlagBits.adoc[] 3112 3113 * ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can: be 3114 used as the source of a transfer command. 3115 * ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can: be 3116 used as the destination of a transfer command. 3117 * ename:VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can: be used 3118 to create a sname:VkImageView suitable for occupying a 3119 sname:VkDescriptorSet slot either of type 3120 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 3121 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a 3122 shader. 3123 * ename:VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can: be used 3124 to create a sname:VkImageView suitable for occupying a 3125 sname:VkDescriptorSet slot of type 3126 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. 3127 * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can: 3128 be used to create a sname:VkImageView suitable for use as a color or 3129 resolve attachment in a sname:VkFramebuffer. 3130 * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the 3131 image can: be used to create a sname:VkImageView suitable for use as a 3132 depth/stencil 3133ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 3134 or depth/stencil resolve 3135endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] 3136 attachment in a sname:VkFramebuffer. 3137 * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that 3138 implementations may: support using <<memory, memory allocations>> with 3139 the ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT to back an image with 3140 this usage. 3141 This bit can: be set for any image that can: be used to create a 3142 sname:VkImageView suitable for use as a color, resolve, depth/stencil, 3143 or input attachment. 3144 * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can: 3145 be used to create a sname:VkImageView suitable for occupying 3146 sname:VkDescriptorSet slot of type 3147 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an 3148 input attachment; and be used as an input attachment in a framebuffer. 3149ifdef::VK_EXT_fragment_density_map[] 3150 * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT specifies that the 3151 image can: be used to create a sname:VkImageView suitable for use as a 3152 <<fragmentdensitymapops, fragment density map image>>. 3153endif::VK_EXT_fragment_density_map[] 3154ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3155 * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies 3156 that the image can: be used to create a sname:VkImageView suitable for 3157 use as a 3158ifdef::VK_KHR_fragment_shading_rate[] 3159 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 3160 attachment>> 3161endif::VK_KHR_fragment_shading_rate[] 3162ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] 3163ifdef::VK_NV_shading_rate_image[] 3164 <<primsrast-shading-rate-image, shading rate image>> 3165endif::VK_NV_shading_rate_image[] 3166endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 3167ifdef::VK_KHR_video_decode_queue[] 3168 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that the image 3169 can: be used as a <<decode-output-picture,decode output picture>> in a 3170 <<video-decode-operations,video decode operation>>. 3171 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR is reserved for future 3172 use. 3173 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR specifies that the image 3174 can: be used as an output <<reconstructed-picture,reconstructed 3175 picture>> or an input <<reference-picture,reference picture>> in a 3176 <<video-decode-operations,video decode operation>>. 3177endif::VK_KHR_video_decode_queue[] 3178ifdef::VK_KHR_video_encode_queue[] 3179 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR is reserved for future 3180 use. 3181 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR specifies that the image 3182 can: be used as an <<encode-input-picture,encode input picture>> in a 3183 <<video-encode-operations,video encode operation>>. 3184 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR specifies that the image 3185 can: be used as an output <<reconstructed-picture,reconstructed 3186 picture>> or an input <<reference-picture,reference picture>> in a 3187 <<video-encode-operations,video encode operation>>. 3188endif::VK_KHR_video_encode_queue[] 3189ifdef::VK_EXT_attachment_feedback_loop_layout[] 3190 * ename:VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the 3191 image can: be transitioned to the 3192 ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT layout to be 3193 used as a color or depth/stencil attachment in a sname:VkFramebuffer 3194 and/or as a read-only input resource in a shader (sampled image, 3195 combined image sampler or input attachment) in the same render pass. 3196endif::VK_EXT_attachment_feedback_loop_layout[] 3197ifdef::VK_EXT_host_image_copy[] 3198 * ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT specifies that the image can: 3199 be used with host copy commands and host layout transitions. 3200endif::VK_EXT_host_image_copy[] 3201-- 3202 3203[open,refpage='VkImageUsageFlags',desc='Bitmask of VkImageUsageFlagBits',type='flags'] 3204-- 3205include::{generated}/api/flags/VkImageUsageFlags.adoc[] 3206 3207tname:VkImageUsageFlags is a bitmask type for setting a mask of zero or more 3208elink:VkImageUsageFlagBits. 3209 3210[[valid-imageview-imageusage]] 3211When creating a sname:VkImageView one of the following 3212elink:VkImageUsageFlagBits must: be set: 3213 3214 * ename:VK_IMAGE_USAGE_SAMPLED_BIT 3215 * ename:VK_IMAGE_USAGE_STORAGE_BIT 3216 * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT 3217 * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 3218 * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT 3219 * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT 3220ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 3221 * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 3222endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] 3223ifdef::VK_EXT_fragment_density_map[] 3224 * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT 3225endif::VK_EXT_fragment_density_map[] 3226ifdef::VK_KHR_video_decode_queue[] 3227 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR 3228 * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR 3229endif::VK_KHR_video_decode_queue[] 3230ifdef::VK_KHR_video_encode_queue[] 3231 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR 3232 * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR 3233endif::VK_KHR_video_encode_queue[] 3234ifdef::VK_QCOM_image_processing[] 3235 * ename:VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM 3236 * ename:VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM 3237endif::VK_QCOM_image_processing[] 3238-- 3239 3240[open,refpage='VkImageCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] 3241-- 3242Bits which can: be set in slink:VkImageCreateInfo::pname:flags, specifying 3243additional parameters of an image, are: 3244 3245include::{generated}/api/enums/VkImageCreateFlagBits.adoc[] 3246 3247 * ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will 3248 be backed using sparse memory binding. 3249ifdef::VKSC_VERSION_1_0[] 3250 This flag is not supported in Vulkan SC <<SCID-8>>. 3251endif::VKSC_VERSION_1_0[] 3252 * ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can: 3253 be partially backed using sparse memory binding. 3254 Images created with this flag must: also be created with the 3255 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. 3256ifdef::VKSC_VERSION_1_0[] 3257 This flag is not supported in Vulkan SC <<SCID-8>>. 3258endif::VKSC_VERSION_1_0[] 3259 * ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will 3260 be backed using sparse memory binding with memory ranges that might also 3261 simultaneously be backing another image (or another portion of the same 3262 image). 3263 Images created with this flag must: also be created with the 3264 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. 3265ifdef::VKSC_VERSION_1_0[] 3266 This flag is not supported in Vulkan SC <<SCID-8>>. 3267endif::VKSC_VERSION_1_0[] 3268 * ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can: 3269 be used to create a sname:VkImageView with a different format from the 3270 image. 3271ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3272 For <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> formats, 3273 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a 3274 sname:VkImageView can be created of a _plane_ of the image. 3275endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3276 * ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can: 3277 be used to create a sname:VkImageView of type 3278 ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY. 3279ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3280 * ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image 3281 can: be used to create a sname:VkImageView of type 3282 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY. 3283endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3284ifdef::VK_EXT_image_2d_view_of_3d[] 3285 * ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT specifies that the 3286 image can: be used to create a sname:VkImageView of type 3287 ename:VK_IMAGE_VIEW_TYPE_2D. 3288endif::VK_EXT_image_2d_view_of_3d[] 3289ifdef::VK_VERSION_1_1[] 3290 * ename:VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a 3291 protected image. 3292endif::VK_VERSION_1_1[] 3293ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 3294 * ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the 3295 image can: be used with a non-zero value of the 3296 pname:splitInstanceBindRegionCount member of a 3297 slink:VkBindImageMemoryDeviceGroupInfo structure passed into 3298 flink:vkBindImageMemory2. 3299 This flag also has the effect of making the image use the standard 3300 sparse image block dimensions. 3301ifdef::VKSC_VERSION_1_0[] 3302 This flag is not supported in Vulkan SC <<SCID-8>>. 3303endif::VKSC_VERSION_1_0[] 3304endif::VK_VERSION_1_1,VK_KHR_device_group[] 3305ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 3306 * ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the 3307 image having a compressed format can: be used to create a 3308 sname:VkImageView with an uncompressed format where each texel in the 3309 image view corresponds to a compressed texel block of the image. 3310 * ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can: 3311 be created with usage flags that are not supported for the format the 3312 image is created with but are supported for at least one format a 3313 sname:VkImageView created from the image can: have. 3314endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 3315ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3316 * ename:VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a 3317 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> must: 3318 have each plane separately bound to memory, rather than having a single 3319 memory binding for the whole image; the presence of this bit 3320 distinguishes a _disjoint image_ from an image without this bit set. 3321endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3322ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 3323 * ename:VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with 3324 the same creation parameters and aliased to the same memory can: 3325 interpret the contents of the memory consistently with each other, 3326 subject to the rules described in the <<resources-memory-aliasing,Memory 3327 Aliasing>> section. 3328ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3329 This flag further specifies that each plane of a _disjoint_ image can: 3330 share an in-memory non-linear representation with single-plane images, 3331 and that a single-plane image can: share an in-memory non-linear 3332 representation with a plane of a multi-planar disjoint image, according 3333 to the rules in <<formats-compatible-planes>>. 3334endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3335ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 3336 If the pname:pNext chain includes a 3337ifdef::VK_VERSION_1_1,VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfo] 3338// Jon: logic needs to incorporate VK_VERSION_1_1 3339ifdef::VK_KHR_external_memory+VK_NV_external_memory[or] 3340ifdef::VK_NV_external_memory[slink:VkExternalMemoryImageCreateInfoNV] 3341 structure whose pname:handleTypes member is not `0`, it is as if 3342 ename:VK_IMAGE_CREATE_ALIAS_BIT is set. 3343endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] 3344endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 3345ifdef::VK_EXT_sample_locations[] 3346 * ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT 3347 specifies that an image with a depth or depth/stencil format can: be 3348 used with custom sample locations when used as a depth/stencil 3349 attachment. 3350endif::VK_EXT_sample_locations[] 3351ifdef::VK_NV_corner_sampled_image[] 3352 * ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV specifies that the image is 3353 a <<resources-images-corner-sampled,corner-sampled image>>. 3354endif::VK_NV_corner_sampled_image[] 3355ifdef::VK_EXT_fragment_density_map[] 3356 * ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT specifies that an image can: be 3357 in a subsampled format which may: be more optimal when written as an 3358 attachment by a render pass that has a fragment density map attachment. 3359 Accessing a subsampled image has additional considerations: 3360 ** Image data read as an image sampler will have undefined: values if the 3361 sampler was not created with pname:flags containing 3362 ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or was not sampled through 3363 the use of a combined image sampler with an immutable sampler in 3364 sname:VkDescriptorSetLayoutBinding. 3365 ** Image data read with an input attachment will have undefined: values if 3366 the contents were not written as an attachment in an earlier subpass of 3367 the same render pass. 3368ifdef::VK_EXT_fragment_density_map2[] 3369 ** Image data read as an image sampler in the fragment shader will be 3370 additionally be read by the device during 3371 ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT if 3372 <<limits-subsampledCoarseReconstructionEarlyAccess, 3373 sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledCoarseReconstructionEarlyAccess>> 3374 is ename:VK_TRUE and the sampler was created with pname:flags 3375 containing 3376 ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT. 3377 ** Image data read with load operations are resampled to the fragment 3378 density of the render pass if <<limits-subsampledLoads, 3379 sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledLoads>> 3380 is ename:VK_TRUE. 3381 Otherwise, values of image data are undefined:. 3382endif::VK_EXT_fragment_density_map2[] 3383ifndef::VK_EXT_fragment_density_map2[] 3384 ** Image data read with load operations may: be resampled to the fragment 3385 density of the render pass. 3386endif::VK_EXT_fragment_density_map2[] 3387 ** Image contents outside of the render area take on undefined: values if 3388 the image is stored as a render pass attachment. 3389ifdef::VK_QCOM_fragment_density_map_offset[] 3390 * ename:VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM specifies 3391 that an image can: be used in a render pass with non-zero 3392 <<renderpass-fragmentdensitymapoffsets,fragment density map offsets>>. 3393 In a render pass with non-zero offsets, fragment density map 3394 attachments, input attachments, color attachments, depth/stencil 3395 attachment, resolve attachments, and preserve attachments must: be 3396 created with ename:VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM. 3397endif::VK_QCOM_fragment_density_map_offset[] 3398endif::VK_EXT_fragment_density_map[] 3399ifdef::VK_EXT_descriptor_buffer[] 3400 * ename:VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies 3401 that the image can: be used with descriptor buffers when capturing and 3402 replaying (e.g. for trace capture and replay), see 3403 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. 3404endif::VK_EXT_descriptor_buffer[] 3405ifdef::VK_EXT_multisampled_render_to_single_sampled[] 3406 * ename:VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT 3407 specifies that an image can: be used with 3408 <<multisampled-render-to-single-sampled,multisampled rendering as a 3409 single-sampled framebuffer attachment>> 3410endif::VK_EXT_multisampled_render_to_single_sampled[] 3411ifdef::VK_KHR_video_maintenance1[] 3412 * ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that 3413 the image can: be used in <<video-coding,video coding operations>> 3414 without having to specify at image creation time the set of video 3415 profiles the image will be used with, except for images used only as 3416 <<dpb,DPB>> pictures, as long as the image is otherwise 3417 <<video-profile-compatibility,compatible>> with the video profile in 3418 question. 3419+ 3420[NOTE] 3421.Note 3422==== 3423This enables exchanging video picture data without additional copies or 3424conversions when used as: 3425 3426ifdef::VK_KHR_video_decode_queue[] 3427 * <<decode-output-picture,Decode output pictures>>, indifferent of the 3428 video profile used to produce them. 3429endif::VK_KHR_video_decode_queue[] 3430ifdef::VK_KHR_video_encode_queue[] 3431 * <<encode-input-picture,Encode input pictures>>, indifferent of the video 3432 profile used to consume them. 3433endif::VK_KHR_video_encode_queue[] 3434 3435ifdef::VK_KHR_video_decode_queue[] 3436This includes images created with both 3437ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR and 3438ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, which is necessary to use the 3439same video picture as the <<reconstructed-picture,reconstructed picture>> 3440and <<decode-output-picture,decode output picture>> in a video decode 3441operation on implementations supporting 3442ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR. 3443endif::VK_KHR_video_decode_queue[] 3444 3445However, images with only DPB usage remain tied to the video profiles the 3446image was created with, as the data layout of such DPB-only images may: be 3447implementation- and codec-dependent. 3448 3449If an application would like to share or reuse the device memory backing 3450such images (e.g. for the purposes of temporal aliasing), then it should: 3451create separate image objects for each video profile and bind them to the 3452same underlying device memory range, similar to how memory resources can: be 3453shared across separate video sessions or any other memory-backed resource. 3454==== 3455endif::VK_KHR_video_maintenance1[] 3456 3457See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and 3458<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more 3459details. 3460-- 3461 3462[open,refpage='VkImageCreateFlags',desc='Bitmask of VkImageCreateFlagBits',type='flags'] 3463-- 3464include::{generated}/api/flags/VkImageCreateFlags.adoc[] 3465 3466tname:VkImageCreateFlags is a bitmask type for setting a mask of zero or 3467more elink:VkImageCreateFlagBits. 3468-- 3469 3470[open,refpage='VkImageType',desc='Specifies the type of an image object',type='enums'] 3471-- 3472Possible values of slink:VkImageCreateInfo::pname:imageType, specifying the 3473basic dimensionality of an image, are: 3474 3475include::{generated}/api/enums/VkImageType.adoc[] 3476 3477 * ename:VK_IMAGE_TYPE_1D specifies a one-dimensional image. 3478 * ename:VK_IMAGE_TYPE_2D specifies a two-dimensional image. 3479 * ename:VK_IMAGE_TYPE_3D specifies a three-dimensional image. 3480-- 3481 3482[open,refpage='VkImageTiling',desc='Specifies the tiling arrangement of data in an image',type='enums'] 3483-- 3484Possible values of slink:VkImageCreateInfo::pname:tiling, specifying the 3485tiling arrangement of texel blocks in an image, are: 3486 3487include::{generated}/api/enums/VkImageTiling.adoc[] 3488 3489 * ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid 3490 out in an implementation-dependent arrangement, for more efficient 3491 memory access). 3492 * ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid 3493 out in memory in row-major order, possibly with some padding on each 3494 row). 3495ifdef::VK_EXT_image_drm_format_modifier[] 3496 * ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT indicates that the image's 3497 tiling is defined by a <<glossary-drm-format-modifier,Linux DRM format 3498 modifier>>. 3499 The modifier is specified at image creation with 3500 slink:VkImageDrmFormatModifierListCreateInfoEXT or 3501 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, and can: be queried 3502 with flink:vkGetImageDrmFormatModifierPropertiesEXT. 3503endif::VK_EXT_image_drm_format_modifier[] 3504-- 3505 3506[open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos'] 3507-- 3508:refpage: vkGetImageSubresourceLayout 3509 3510To query the memory layout of an image subresource, call: 3511 3512include::{generated}/api/protos/vkGetImageSubresourceLayout.adoc[] 3513 3514 * pname:device is the logical device that owns the image. 3515 * pname:image is the image whose layout is being queried. 3516 * pname:pSubresource is a pointer to a slink:VkImageSubresource structure 3517 selecting a specific image subresource from the image. 3518 * pname:pLayout is a pointer to a slink:VkSubresourceLayout structure in 3519 which the layout is returned. 3520 3521ifndef::VK_EXT_image_drm_format_modifier[] 3522The image must: be <<glossary-linear-resource,linear>>. 3523The 3524endif::VK_EXT_image_drm_format_modifier[] 3525ifdef::VK_EXT_image_drm_format_modifier[] 3526If the image is <<glossary-linear-resource,linear>>, then the 3527endif::VK_EXT_image_drm_format_modifier[] 3528returned layout is valid for <<memory-device-hostaccess, host access>>. 3529 3530ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3531If the image's 3532ifdef::VK_EXT_image_drm_format_modifier[] 3533tiling is ename:VK_IMAGE_TILING_LINEAR and its 3534endif::VK_EXT_image_drm_format_modifier[] 3535format is a <<formats-requiring-sampler-ycbcr-conversion,multi-planar 3536format>>, then fname:vkGetImageSubresourceLayout describes one 3537ifdef::VK_EXT_image_drm_format_modifier[_format plane_] 3538ifndef::VK_EXT_image_drm_format_modifier[plane] 3539of the image. 3540endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3541ifdef::VK_EXT_image_drm_format_modifier[] 3542If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 3543fname:vkGetImageSubresourceLayout describes one _memory plane_ of the image. 3544If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and 3545the image is <<glossary-linear-resource,non-linear>>, then the returned 3546layout has an implementation-dependent meaning; the vendor of the image's 3547<<glossary-drm-format-modifier,DRM format modifier>> may: provide 3548documentation that explains how to interpret the returned layout. 3549endif::VK_EXT_image_drm_format_modifier[] 3550 3551fname:vkGetImageSubresourceLayout is invariant for the lifetime of a single 3552image. 3553ifdef::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 3554However, the subresource layout of images in Android hardware buffer or QNX 3555Screen buffer external memory is not known until the image has been bound to 3556memory, so applications must: not call flink:vkGetImageSubresourceLayout for 3557such an image before it has been bound. 3558endif::VK_ANDROID_external_memory_android_hardware_buffer,VK_QNX_external_memory_screen_buffer[] 3559 3560:imageparam: image 3561 3562.Valid Usage 3563**** 3564ifndef::VK_EXT_image_drm_format_modifier[] 3565 * [[VUID-vkGetImageSubresourceLayout-image-07789]] 3566 pname:image must: have been created with pname:tiling equal to 3567 ename:VK_IMAGE_TILING_LINEAR 3568endif::VK_EXT_image_drm_format_modifier[] 3569ifdef::VK_EXT_image_drm_format_modifier[] 3570 * [[VUID-vkGetImageSubresourceLayout-image-07790]] 3571 pname:image must: have been created with pname:tiling equal to 3572 ename:VK_IMAGE_TILING_LINEAR or 3573 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 3574endif::VK_EXT_image_drm_format_modifier[] 3575include::{chapters}/commonvalidity/get_image_subresource_layout_common.adoc[] 3576ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 3577 * [[VUID-vkGetImageSubresourceLayout-image-09432]] 3578 If pname:image was created with the 3579 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 3580 external memory handle type, then pname:image must: be bound to memory 3581endif::VK_ANDROID_external_memory_android_hardware_buffer[] 3582ifdef::VK_EXT_image_drm_format_modifier[] 3583 * [[VUID-vkGetImageSubresourceLayout-tiling-09433]] 3584 If the pname:tiling of the pname:image is 3585 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pname:aspectMask 3586 member of pname:pSubresource must: be 3587 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` and the index _i_ must: 3588 be less than the 3589 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 3590 associated with the image's pname:format and 3591 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier 3592endif::VK_EXT_image_drm_format_modifier[] 3593**** 3594 3595include::{generated}/validity/protos/vkGetImageSubresourceLayout.adoc[] 3596-- 3597 3598[open,refpage='VkImageSubresource',desc='Structure specifying an image subresource',type='structs'] 3599-- 3600The sname:VkImageSubresource structure is defined as: 3601 3602include::{generated}/api/structs/VkImageSubresource.adoc[] 3603 3604 * pname:aspectMask is a tlink:VkImageAspectFlags value selecting the image 3605 _aspect_. 3606 * pname:mipLevel selects the mipmap level. 3607 * pname:arrayLayer selects the array layer. 3608 3609include::{generated}/validity/structs/VkImageSubresource.adoc[] 3610-- 3611 3612[open,refpage='VkSubresourceLayout',desc='Structure specifying subresource layout',type='structs'] 3613-- 3614Information about the layout of the image subresource is returned in a 3615sname:VkSubresourceLayout structure: 3616 3617include::{generated}/api/structs/VkSubresourceLayout.adoc[] 3618 3619 * pname:offset is the byte offset from the start of the image 3620ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3621 or the plane 3622endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3623 where the image subresource begins. 3624 * pname:size is the size in bytes of the image subresource. 3625 pname:size includes any extra memory that is required based on 3626 pname:rowPitch. 3627 * pname:rowPitch describes the number of bytes between each row of texels 3628 in an image. 3629 * pname:arrayPitch describes the number of bytes between each array layer 3630 of an image. 3631 * pname:depthPitch describes the number of bytes between each slice of 3D 3632 image. 3633 3634If the image is <<glossary-linear-resource,linear>>, then pname:rowPitch, 3635pname:arrayPitch and pname:depthPitch describe the layout of the image 3636subresource in linear memory. 3637For uncompressed formats, pname:rowPitch is the number of bytes between 3638texels with the same x coordinate in adjacent rows (y coordinates differ by 3639one). 3640pname:arrayPitch is the number of bytes between texels with the same x and y 3641coordinate in adjacent array layers of the image (array layer values differ 3642by one). 3643pname:depthPitch is the number of bytes between texels with the same x and y 3644coordinate in adjacent slices of a 3D image (z coordinates differ by one). 3645Expressed as an addressing formula, the starting byte of a texel in the 3646image subresource has address: 3647 3648[source,c] 3649---- 3650// (x,y,z,layer) are in texel coordinates 3651address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset 3652---- 3653 3654For compressed formats, the pname:rowPitch is the number of bytes between 3655compressed texel blocks in adjacent rows. 3656pname:arrayPitch is the number of bytes between compressed texel blocks in 3657adjacent array layers. 3658pname:depthPitch is the number of bytes between compressed texel blocks in 3659adjacent slices of a 3D image. 3660 3661[source,c] 3662---- 3663// (x,y,z,layer) are in compressed texel block coordinates 3664address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset; 3665---- 3666 3667The value of pname:arrayPitch is undefined: for images that were not created 3668as arrays. 3669pname:depthPitch is defined only for 3D images. 3670 3671If the image has a 3672ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3673_single-plane_ 3674endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3675color format 3676ifdef::VK_EXT_image_drm_format_modifier[] 3677and its tiling is ename:VK_IMAGE_TILING_LINEAR 3678endif::VK_EXT_image_drm_format_modifier[] 3679, then the pname:aspectMask member of sname:VkImageSubresource must: be 3680ename:VK_IMAGE_ASPECT_COLOR_BIT. 3681 3682If the image has a depth/stencil format 3683ifdef::VK_EXT_image_drm_format_modifier[] 3684and its tiling is ename:VK_IMAGE_TILING_LINEAR 3685endif::VK_EXT_image_drm_format_modifier[] 3686, then pname:aspectMask must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or 3687ename:VK_IMAGE_ASPECT_STENCIL_BIT. 3688On implementations that store depth and stencil aspects separately, querying 3689each of these image subresource layouts will return a different pname:offset 3690and pname:size representing the region of memory used for that aspect. 3691On implementations that store depth and stencil aspects interleaved, the 3692same pname:offset and pname:size are returned and represent the interleaved 3693memory allocation. 3694 3695ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3696If the image has a <<formats-requiring-sampler-ycbcr-conversion,multi-planar 3697format>> 3698ifdef::VK_EXT_image_drm_format_modifier[] 3699and its tiling is ename:VK_IMAGE_TILING_LINEAR 3700endif::VK_EXT_image_drm_format_modifier[] 3701, then the pname:aspectMask member of sname:VkImageSubresource must: be 3702ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 3703(for 3-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 3704Querying each of these image subresource layouts will return a different 3705pname:offset and pname:size representing the region of memory used for that 3706plane. 3707If the image is _disjoint_, then the pname:offset is relative to the base 3708address of the plane. 3709If the image is _non-disjoint_, then the pname:offset is relative to the 3710base address of the image. 3711endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3712 3713ifdef::VK_EXT_image_drm_format_modifier[] 3714If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then 3715the pname:aspectMask member of sname:VkImageSubresource must: be one of 3716`VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`, where the maximum allowed 3717plane index _i_ is defined by the 3718slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 3719associated with the image's slink:VkImageCreateInfo::pname:format and 3720<<glossary-drm-format-modifier,modifier>>. 3721The memory range used by the subresource is described by pname:offset and 3722pname:size. 3723If the image is _disjoint_, then the pname:offset is relative to the base 3724address of the _memory plane_. 3725If the image is _non-disjoint_, then the pname:offset is relative to the 3726base address of the image. 3727If the image is <<glossary-linear-resource,non-linear>>, then 3728pname:rowPitch, pname:arrayPitch, and pname:depthPitch have an 3729implementation-dependent meaning. 3730endif::VK_EXT_image_drm_format_modifier[] 3731 3732include::{generated}/validity/structs/VkSubresourceLayout.adoc[] 3733-- 3734 3735ifdef::VK_KHR_maintenance5,VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3736[open,refpage='vkGetImageSubresourceLayout2KHR',desc='Retrieve information about an image subresource',type='protos'] 3737-- 3738:refpage: vkGetImageSubresourceLayout2KHR 3739 3740To query the memory layout of an image subresource, call: 3741 3742ifdef::VK_KHR_maintenance5[] 3743include::{generated}/api/protos/vkGetImageSubresourceLayout2KHR.adoc[] 3744endif::VK_KHR_maintenance5[] 3745 3746ifdef::VK_KHR_maintenance5[] 3747ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[or the equivalent command] 3748endif::VK_KHR_maintenance5[] 3749 3750ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3751include::{generated}/api/protos/vkGetImageSubresourceLayout2EXT.adoc[] 3752endif::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3753 3754 * pname:device is the logical device that owns the image. 3755 * pname:image is the image whose layout is being queried. 3756 * pname:pSubresource is a pointer to a slink:VkImageSubresource2KHR 3757 structure selecting a specific image for the image subresource. 3758 * pname:pLayout is a pointer to a slink:VkSubresourceLayout2KHR structure 3759 in which the layout is returned. 3760 3761fname:vkGetImageSubresourceLayout2KHR behaves similarly to 3762flink:vkGetImageSubresourceLayout, with the ability to specify extended 3763inputs via chained input structures, and to return extended information via 3764chained output structures. 3765 3766It is legal to call fname:vkGetImageSubresourceLayout2KHR with a pname:image 3767created with pname:tiling equal to ename:VK_IMAGE_TILING_OPTIMAL, but the 3768members of slink:VkSubresourceLayout2KHR::pname:subresourceLayout will have 3769undefined: values in this case. 3770 3771[NOTE] 3772.Note 3773==== 3774Structures chained from slink:VkImageSubresource2KHR::pname:pNext will also 3775be updated when pname:tiling is equal to ename:VK_IMAGE_TILING_OPTIMAL. 3776==== 3777 3778:imageparam: image 3779 3780.Valid Usage 3781**** 3782include::{chapters}/commonvalidity/get_image_subresource_layout_common.adoc[] 3783ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 3784 * [[VUID-vkGetImageSubresourceLayout2KHR-image-09434]] 3785 If pname:image was created with the 3786 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 3787 external memory handle type, then pname:image must: be bound to memory 3788endif::VK_ANDROID_external_memory_android_hardware_buffer[] 3789ifdef::VK_EXT_image_drm_format_modifier[] 3790 * [[VUID-vkGetImageSubresourceLayout2KHR-tiling-09435]] 3791 If the pname:tiling of the pname:image is 3792 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pname:aspectMask 3793 member of pname:pSubresource must: be 3794 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` and the index _i_ must: 3795 be less than the 3796 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 3797 associated with the image's pname:format and 3798 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier 3799endif::VK_EXT_image_drm_format_modifier[] 3800**** 3801 3802include::{generated}/validity/protos/vkGetImageSubresourceLayout2KHR.adoc[] 3803-- 3804 3805[open,refpage='VkImageSubresource2KHR',desc='Structure specifying an image subresource',type='structs',alias='VkImageSubresource2EXT'] 3806-- 3807The sname:VkImageSubresource2KHR structure is defined as: 3808 3809include::{generated}/api/structs/VkImageSubresource2KHR.adoc[] 3810 3811ifdef::VK_KHR_maintenance5[] 3812ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[or the equivalent] 3813endif::VK_KHR_maintenance5[] 3814 3815ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3816include::{generated}/api/structs/VkImageSubresource2EXT.adoc[] 3817endif::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3818 3819 * pname:sType is a elink:VkStructureType value identifying this structure. 3820 * pname:pNext is `NULL` or a pointer to a structure extending this 3821 structure. 3822 * pname:imageSubresource is a slink:VkImageSubresource structure. 3823 3824include::{generated}/validity/structs/VkImageSubresource2KHR.adoc[] 3825-- 3826 3827[open,refpage='VkSubresourceLayout2KHR',desc='Structure specifying subresource layout',type='structs',alias='VkSubresourceLayout2EXT'] 3828-- 3829Information about the layout of the image subresource is returned in a 3830sname:VkSubresourceLayout2KHR structure: 3831 3832ifdef::VK_KHR_maintenance5[] 3833include::{generated}/api/structs/VkSubresourceLayout2KHR.adoc[] 3834endif::VK_KHR_maintenance5[] 3835 3836ifdef::VK_KHR_maintenance5[] 3837ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[or the equivalent] 3838endif::VK_KHR_maintenance5[] 3839 3840ifdef::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3841 3842ifndef::VK_KHR_maintenance5[] 3843Information about the layout of the image subresource is returned in a 3844sname:VkSubresourceLayout2EXT structure: 3845endif::VK_KHR_maintenance5[] 3846 3847include::{generated}/api/structs/VkSubresourceLayout2EXT.adoc[] 3848endif::VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3849 3850 * pname:sType is a elink:VkStructureType value identifying this structure. 3851 * pname:pNext is `NULL` or a pointer to a structure extending this 3852 structure. 3853 * pname:subresourceLayout is a slink:VkSubresourceLayout structure. 3854 3855include::{generated}/validity/structs/VkSubresourceLayout2KHR.adoc[] 3856-- 3857 3858ifdef::VK_EXT_host_image_copy[] 3859[open,refpage='VkSubresourceHostMemcpySizeEXT',desc='Memory size needed to copy to or from an image on the host with VK_HOST_IMAGE_COPY_MEMCPY_EXT',type='structs'] 3860-- 3861To query the memory size needed to copy to or from an image using 3862flink:vkCopyMemoryToImageEXT or flink:vkCopyImageToMemoryEXT when the 3863ename:VK_HOST_IMAGE_COPY_MEMCPY_EXT flag is specified, add a 3864slink:VkSubresourceHostMemcpySizeEXT structure to the pname:pNext chain of 3865the slink:VkSubresourceLayout2EXT structure in a call to 3866flink:vkGetImageSubresourceLayout2EXT. 3867 3868The sname:VkSubresourceHostMemcpySizeEXT structure is defined as: 3869 3870include::{generated}/api/structs/VkSubresourceHostMemcpySizeEXT.adoc[] 3871 3872 * pname:sType is a elink:VkStructureType value identifying this structure. 3873 * pname:pNext is `NULL` or a pointer to a structure extending this 3874 structure. 3875 * pname:size is the size in bytes of the image subresource. 3876 3877include::{generated}/validity/structs/VkSubresourceHostMemcpySizeEXT.adoc[] 3878-- 3879endif::VK_EXT_host_image_copy[] 3880endif::VK_KHR_maintenance5,VK_EXT_image_compression_control,VK_EXT_host_image_copy[] 3881 3882ifdef::VK_KHR_maintenance5[] 3883[open,refpage='vkGetDeviceImageSubresourceLayoutKHR',desc='Retrieve information about an image subresource without an image object',type='protos'] 3884-- 3885To query the memory layout of an image subresource, without an image object, 3886call: 3887 3888include::{generated}/api/protos/vkGetDeviceImageSubresourceLayoutKHR.adoc[] 3889 3890 * pname:device is the logical device that owns the image. 3891 * pname:pInfo is a pointer to a slink:VkDeviceImageSubresourceInfoKHR 3892 structure containing parameters required for the subresource layout 3893 query. 3894 * pname:pLayout is a pointer to a slink:VkSubresourceLayout2KHR structure 3895 in which the layout is returned. 3896 3897fname:vkGetDeviceImageSubresourceLayoutKHR behaves similarly to 3898flink:vkGetImageSubresourceLayout2KHR, but uses a slink:VkImageCreateInfo 3899structure to specify the image rather than a slink:VkImage object. 3900 3901include::{generated}/validity/protos/vkGetDeviceImageSubresourceLayoutKHR.adoc[] 3902-- 3903 3904[open,refpage='VkDeviceImageSubresourceInfoKHR',desc='Image creation information for querying subresource layout',type='structs'] 3905-- 3906:refpage: VkDeviceImageSubresourceInfoKHR 3907 3908The sname:VkDeviceImageSubresourceInfoKHR structure is defined as: 3909 3910include::{generated}/api/structs/VkDeviceImageSubresourceInfoKHR.adoc[] 3911 3912 * pname:sType is a elink:VkStructureType value identifying this structure. 3913 * pname:pNext is `NULL` or a pointer to a structure extending this 3914 structure. 3915 * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure 3916 containing parameters affecting creation of the image to query. 3917 * pname:pSubresource pSubresource is a pointer to a 3918 slink:VkImageSubresource2KHR structure selecting a specific image 3919 subresource for the query. 3920 3921:imageparam: pCreateInfo 3922 3923.Valid Usage 3924**** 3925include::{chapters}/commonvalidity/get_image_subresource_layout_common.adoc[] 3926**** 3927 3928include::{generated}/validity/structs/VkDeviceImageSubresourceInfoKHR.adoc[] 3929-- 3930endif::VK_KHR_maintenance5[] 3931 3932ifdef::VK_EXT_image_drm_format_modifier[] 3933[open,refpage='vkGetImageDrmFormatModifierPropertiesEXT',desc='Returns an image\'s DRM format modifier',type='protos'] 3934-- 3935:refpage: vkGetImageDrmFormatModifierPropertiesEXT 3936 3937If an image was created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 3938then the image has a <<glossary-drm-format-modifier,Linux DRM format 3939modifier>>. 3940To query the _modifier_, call: 3941 3942include::{generated}/api/protos/vkGetImageDrmFormatModifierPropertiesEXT.adoc[] 3943 3944 * pname:device is the logical device that owns the image. 3945 * pname:image is the queried image. 3946 * pname:pProperties is a pointer to a 3947 slink:VkImageDrmFormatModifierPropertiesEXT structure in which 3948 properties of the image's _DRM format modifier_ are returned. 3949 3950include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 3951 3952.Valid Usage 3953**** 3954 * [[VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-02272]] 3955 pname:image must: have been created with <<VkImageCreateInfo, 3956 pname:tiling>> equal to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT 3957**** 3958 3959include::{generated}/validity/protos/vkGetImageDrmFormatModifierPropertiesEXT.adoc[] 3960-- 3961 3962[open,refpage='VkImageDrmFormatModifierPropertiesEXT',desc='Properties of an image\'s Linux DRM format modifier',type='structs'] 3963-- 3964The slink:VkImageDrmFormatModifierPropertiesEXT structure is defined as: 3965 3966include::{generated}/api/structs/VkImageDrmFormatModifierPropertiesEXT.adoc[] 3967 3968 * pname:sType is a elink:VkStructureType value identifying this structure. 3969 * pname:pNext is `NULL` or a pointer to a structure extending this 3970 structure. 3971 * pname:drmFormatModifier returns the image's 3972 <<glossary-drm-format-modifier,Linux DRM format modifier>>. 3973 3974If the pname:image was created with 3975slink:VkImageDrmFormatModifierListCreateInfoEXT, then the returned 3976pname:drmFormatModifier must: belong to the list of modifiers provided at 3977time of image creation in 3978slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. 3979If the pname:image was created with 3980slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned 3981pname:drmFormatModifier must: be the modifier provided at time of image 3982creation in 3983slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. 3984 3985include::{generated}/validity/structs/VkImageDrmFormatModifierPropertiesEXT.adoc[] 3986-- 3987endif::VK_EXT_image_drm_format_modifier[] 3988 3989[open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos'] 3990-- 3991To destroy an image, call: 3992 3993include::{generated}/api/protos/vkDestroyImage.adoc[] 3994 3995 * pname:device is the logical device that destroys the image. 3996 * pname:image is the image to destroy. 3997 * pname:pAllocator controls host memory allocation as described in the 3998 <<memory-allocation, Memory Allocation>> chapter. 3999 4000.Valid Usage 4001**** 4002 * [[VUID-vkDestroyImage-image-01000]] 4003 All submitted commands that refer to pname:image, either directly or via 4004 a sname:VkImageView, must: have completed execution 4005ifndef::VKSC_VERSION_1_0[] 4006 * [[VUID-vkDestroyImage-image-01001]] 4007 If sname:VkAllocationCallbacks were provided when pname:image was 4008 created, a compatible set of callbacks must: be provided here 4009 * [[VUID-vkDestroyImage-image-01002]] 4010 If no sname:VkAllocationCallbacks were provided when pname:image was 4011 created, pname:pAllocator must: be `NULL` 4012endif::VKSC_VERSION_1_0[] 4013ifdef::VK_KHR_swapchain[] 4014 * [[VUID-vkDestroyImage-image-04882]] 4015 pname:image must: not have been acquired from 4016 flink:vkGetSwapchainImagesKHR 4017endif::VK_KHR_swapchain[] 4018**** 4019 4020include::{generated}/validity/protos/vkDestroyImage.adoc[] 4021-- 4022 4023 4024[[resources-image-format-features]] 4025=== Image Format Features 4026 4027Valid uses of a slink:VkImage may: depend on the image's _format features_, 4028defined below. 4029Such constraints are documented in the affected valid usage statement. 4030 4031 * If the image was created with ename:VK_IMAGE_TILING_LINEAR, then its set 4032 of _format features_ is the value of 4033 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 4034 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 4035 slink:VkImageCreateInfo::pname:format. 4036 * If the image was created with ename:VK_IMAGE_TILING_OPTIMAL, 4037ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4038 but without an 4039 <<memory-external-android-hardware-buffer-external-formats,Android 4040 hardware buffer external format>>, 4041endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4042ifdef::VK_QNX_external_memory_screen_buffer[] 4043ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 4044 but without a 4045endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4046ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4047 or a 4048endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4049 <<memory-external-screen-buffer-external-formats,QNX Screen Buffer 4050 external format>> 4051endif::VK_QNX_external_memory_screen_buffer[] 4052ifdef::VK_FUCHSIA_buffer_collection[] 4053ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] 4054 but without an 4055endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4056ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4057 or an 4058endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4059 slink:VkBufferCollectionImageCreateInfoFUCHSIA, 4060endif::VK_FUCHSIA_buffer_collection[] 4061 then its set of _format features_ is the value of 4062 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 4063 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 4064 slink:VkImageCreateInfo::pname:format. 4065ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 4066 * If the image was created with an 4067 <<memory-external-android-hardware-buffer-external-formats,Android 4068 hardware buffer external format>>, then its set of _format features_ is 4069 the value of 4070 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 4071 found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on 4072 the Android hardware buffer that was imported to the 4073 slink:VkDeviceMemory to which the image is bound. 4074endif::VK_ANDROID_external_memory_android_hardware_buffer[] 4075ifdef::VK_QNX_external_memory_screen_buffer[] 4076 * If the image was created with an 4077 <<memory-external-screen-buffer-external-formats,QNX Screen buffer 4078 external format>>, then its set of _format features_ is the value of 4079 slink:VkScreenBufferFormatPropertiesQNX::pname:formatFeatures found by 4080 calling flink:vkGetScreenBufferPropertiesQNX on the QNX Screen buffer 4081 that was imported to the slink:VkDeviceMemory to which the image is 4082 bound. 4083endif::VK_QNX_external_memory_screen_buffer[] 4084ifdef::VK_EXT_image_drm_format_modifier[] 4085 * If the image was created with 4086 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: 4087 ** The image's DRM format modifier is the value of 4088 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier 4089 found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. 4090 ** Let 4091 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 4092 be the array found by calling 4093 flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as 4094 slink:VkImageCreateInfo::pname:format. 4095 ** Let `VkDrmFormatModifierPropertiesEXT prop` be the array element whose 4096 pname:drmFormatModifier member is the value of the image's DRM format 4097 modifier. 4098 ** Then the image's set of _format features_ is the value of 4099 `prop`::pname:drmFormatModifierTilingFeatures. 4100endif::VK_EXT_image_drm_format_modifier[] 4101 4102 4103ifdef::VK_NV_corner_sampled_image[] 4104[[resources-images-corner-sampled]] 4105=== Corner-Sampled Images 4106 4107A _corner-sampled image_ is an image where unnormalized texel coordinates 4108are centered on integer values rather than half-integer values. 4109 4110A corner-sampled image has a number of differences compared to conventional 4111texture image: 4112 4113 * Texels are centered on integer coordinates. 4114 See <<textures-unnormalized-to-integer, Unnormalized Texel Coordinate 4115 Operations>> 4116 * Normalized coordinates are scaled using [eq]#coord {times} (dim - 1)# 4117 rather than [eq]#coord {times} dim#, where dim is the size of one 4118 dimension of the image. 4119 See <<textures-normalized-to-unnormalized, normalized texel coordinate 4120 transform>>. 4121 * Partial derivatives are scaled using [eq]#coord {times} (dim - 1)# 4122 rather than [eq]#coord {times} dim#. 4123 See <<textures-scale-factor,Scale Factor Operation>>. 4124 * Calculation of the next higher LOD size goes according to 4125 [eq]#{lceil}dim / 2{rceil}# rather than [eq]#{lfloor}dim / 2{rfloor}#. 4126 See <<resources-image-mip-level-sizing,Image Mip Level Sizing>>. 4127 * The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. 4128 See <<resources-image-mip-level-sizing,Image Mip Level Sizing>>. 4129 4130Corner-sampling is only supported for 2D and 3D images. 4131When sampling a corner-sampled image, the sampler addressing mode must: be 4132ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. 4133Corner-sampled images are not supported as cube maps or depth/stencil 4134images. 4135endif::VK_NV_corner_sampled_image[] 4136 4137 4138[[resources-image-mip-level-sizing]] 4139=== Image Mip Level Sizing 4140 4141A _complete mipmap chain_ is the full set of mip levels, from the largest 4142mip level provided, down to the _minimum mip level size_. 4143 4144 4145==== Conventional Images 4146 4147For conventional images, the dimensions of each successive mip level, 4148[eq]#n+1#, are: 4149 4150 {empty}:: [eq]#pname:width~n+1~ = max({lfloor}pname:width~n~/2{rfloor}, 4151 1)# 4152 {empty}:: [eq]#pname:height~n+1~ = max({lfloor}pname:height~n~/2{rfloor}, 4153 1)# 4154 {empty}:: [eq]#pname:depth~n+1~ = max({lfloor}pname:depth~n~/2{rfloor}, 4155 1)# 4156 4157where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# 4158are the dimensions of the next larger mip level, [eq]#n#. 4159 4160The minimum mip level size is: 4161 4162 * 1 for one-dimensional images, 4163 * 1x1 for two-dimensional images, and 4164 * 1x1x1 for three-dimensional images. 4165 4166The number of levels in a complete mipmap chain is: 4167 4168 {empty}:: [eq]#{lfloor}log~2~(max(pname:width~0~, pname:height~0~, 4169 pname:depth~0~)){rfloor} {plus} 1# 4170 4171where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# 4172are the dimensions of the largest (most detailed) mip level, `0`. 4173 4174 4175ifdef::VK_NV_corner_sampled_image[] 4176==== Corner-Sampled Images 4177 4178For corner-sampled images, the dimensions of each successive mip level, 4179[eq]#n+1#, are: 4180 4181 {empty}:: [eq]#pname:width~n+1~ = max({lceil}pname:width~n~/2{rceil}, 2)# 4182 {empty}:: [eq]#pname:height~n+1~ = max({lceil}pname:height~n~/2{rceil}, 4183 2)# 4184 {empty}:: [eq]#pname:depth~n+1~ = max({lceil}pname:depth~n~/2{rceil}, 2)# 4185 4186where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# 4187are the dimensions of the next larger mip level, [eq]#n#. 4188 4189The minimum mip level size is: 4190 4191 * 2x2 for two-dimensional images, and 4192 * 2x2x2 for three-dimensional images. 4193 4194The number of levels in a complete mipmap chain is: 4195 4196 {empty}:: [eq]#{lceil}log~2~(max(pname:width~0~, pname:height~0~, 4197 pname:depth~0~)){rceil}# 4198 4199where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# 4200are the dimensions of the largest (most detailed) mip level, `0`. 4201endif::VK_NV_corner_sampled_image[] 4202 4203 4204[[resources-image-layouts]] 4205== Image Layouts 4206 4207Images are stored in implementation-dependent opaque layouts in memory. 4208Each layout has limitations on what kinds of operations are supported for 4209image subresources using the layout. 4210At any given time, the data representing an image subresource in memory 4211exists in a particular layout which is determined by the most recent layout 4212transition that was performed on that image subresource. 4213Applications have control over which layout each image subresource uses, and 4214can: transition an image subresource from one layout to another. 4215Transitions can: happen with an image memory barrier, included as part of a 4216flink:vkCmdPipelineBarrier or a flink:vkCmdWaitEvents command buffer command 4217(see <<synchronization-image-memory-barriers>>), or as part of a subpass 4218dependency within a render pass (see sname:VkSubpassDependency). 4219 4220Image layout is per-image subresource. 4221Separate image subresources of the same image can: be in different layouts 4222at the same time, with the exception that depth and stencil aspects of a 4223given image subresource can: only be in different layouts if the 4224<<features-separateDepthStencilLayouts, pname:separateDepthStencilLayouts>> 4225feature is enabled. 4226 4227[NOTE] 4228.Note 4229==== 4230Each layout may: offer optimal performance for a specific usage of image 4231memory. 4232For example, an image with a layout of 4233ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL may: provide optimal 4234performance for use as a color attachment, but be unsupported for use in 4235transfer commands. 4236Applications can: transition an image subresource from one layout to another 4237in order to achieve optimal performance when the image subresource is used 4238for multiple kinds of operations. 4239After initialization, applications need not use any layout other than the 4240general layout, though this may: produce suboptimal performance on some 4241implementations. 4242==== 4243 4244Upon creation, all image subresources of an image are initially in the same 4245layout, where that layout is selected by the 4246sname:VkImageCreateInfo::pname:initialLayout member. 4247The pname:initialLayout must: be either ename:VK_IMAGE_LAYOUT_UNDEFINED or 4248ename:VK_IMAGE_LAYOUT_PREINITIALIZED. 4249If it is ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can: be 4250preinitialized by the host while using this layout, and the transition away 4251from this layout will preserve that data. 4252If it is ename:VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are 4253considered to be undefined:, and the transition away from this layout is not 4254guaranteed to preserve that data. 4255For either of these initial layouts, any image subresources must: be 4256transitioned to another layout before they are accessed by the device. 4257 4258Host access to image memory is only well-defined for 4259<<glossary-linear-resource,linear>> images and for image subresources of 4260those images which are currently in either the 4261ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL 4262layout. 4263Calling flink:vkGetImageSubresourceLayout for a linear image returns a 4264subresource layout mapping that is valid for either of those image layouts. 4265 4266[open,refpage='VkImageLayout',desc='Layout of image and image subresources',type='enums'] 4267-- 4268The set of image layouts consists of: 4269 4270include::{generated}/api/enums/VkImageLayout.adoc[] 4271 4272The type(s) of device access supported by each layout are: 4273 4274 * ename:VK_IMAGE_LAYOUT_UNDEFINED specifies that the layout is unknown. 4275 Image memory cannot: be transitioned into this layout. 4276 This layout can: be used as the pname:initialLayout member of 4277 slink:VkImageCreateInfo. 4278 This layout can: be used in place of the current image layout in a 4279 layout transition, but doing so will cause the contents of the image's 4280 memory to be undefined:. 4281 * ename:VK_IMAGE_LAYOUT_PREINITIALIZED specifies that an image's memory is 4282 in a defined layout and can: be populated by data, but that it has not 4283 yet been initialized by the driver. 4284 Image memory cannot: be transitioned into this layout. 4285 This layout can: be used as the pname:initialLayout member of 4286 slink:VkImageCreateInfo. 4287 This layout is intended to be used as the initial layout for an image 4288 whose contents are written by the host, and hence the data can: be 4289 written to memory immediately, without first executing a layout 4290 transition. 4291 Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with 4292 <<glossary-linear-resource,linear>> images because there is not a 4293 standard layout defined for ename:VK_IMAGE_TILING_OPTIMAL images. 4294 * ename:VK_IMAGE_LAYOUT_GENERAL supports all types of device access. 4295ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 4296 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL specifies a layout that must: 4297 only be used with attachment accesses in the graphics pipeline. 4298 * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL specifies a layout allowing read 4299 only access as an attachment, or in shaders as a sampled image, combined 4300 image/sampler, or input attachment. 4301endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 4302 * ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must: only be used as a 4303 color or resolve attachment in a sname:VkFramebuffer. 4304 This layout is valid only for image subresources of images created with 4305 the ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled. 4306 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL specifies a 4307 layout for both the depth and stencil aspects of a depth/stencil format 4308 image allowing read and write access as a depth/stencil attachment. 4309ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4310 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and 4311 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. 4312endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4313 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL specifies a layout 4314 for both the depth and stencil aspects of a depth/stencil format image 4315 allowing read only access as a depth/stencil attachment or in shaders as 4316 a sampled image, combined image/sampler, or input attachment. 4317ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4318 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and 4319 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. 4320endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4321ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4322 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 4323 specifies a layout for depth/stencil format images allowing read and 4324 write access to the stencil aspect as a stencil attachment, and read 4325 only access to the depth aspect as a depth attachment or in shaders as a 4326 sampled image, combined image/sampler, or input attachment. 4327ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4328 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and 4329 ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. 4330endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4331 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 4332 specifies a layout for depth/stencil format images allowing read and 4333 write access to the depth aspect as a depth attachment, and read only 4334 access to the stencil aspect as a stencil attachment or in shaders as a 4335 sampled image, combined image/sampler, or input attachment. 4336ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4337 It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and 4338 ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. 4339endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4340endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4341ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4342 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL specifies a layout for 4343 the depth aspect of a depth/stencil format image allowing read and write 4344 access as a depth attachment. 4345 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL specifies a layout for the 4346 depth aspect of a depth/stencil format image allowing read-only access 4347 as a depth attachment or in shaders as a sampled image, combined 4348 image/sampler, or input attachment. 4349 * ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for 4350 the stencil aspect of a depth/stencil format image allowing read and 4351 write access as a stencil attachment. 4352 * ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for 4353 the stencil aspect of a depth/stencil format image allowing read-only 4354 access as a stencil attachment or in shaders as a sampled image, 4355 combined image/sampler, or input attachment. 4356endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 4357 * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL specifies a layout 4358 allowing read-only access in a shader as a sampled image, combined 4359 image/sampler, or input attachment. 4360 This layout is valid only for image subresources of images created with 4361 the ename:VK_IMAGE_USAGE_SAMPLED_BIT or 4362 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bits enabled. 4363 * ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must: only be used as a 4364 source image of a transfer command (see the definition of 4365 <<synchronization-pipeline-stages-transfer, 4366 ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). 4367 This layout is valid only for image subresources of images created with 4368 the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled. 4369 * ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must: only be used as a 4370 destination image of a transfer command. 4371 This layout is valid only for image subresources of images created with 4372 the ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled. 4373ifdef::VK_KHR_swapchain[] 4374 * ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must: only be used for presenting 4375 a presentable image for display. 4376ifdef::VK_KHR_shared_presentable_image[] 4377 * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared 4378 presentable images, and must: be used for any usage the image supports. 4379endif::VK_KHR_shared_presentable_image[] 4380endif::VK_KHR_swapchain[] 4381ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 4382 * ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR must: 4383 only be used as a 4384ifdef::VK_KHR_fragment_shading_rate[] 4385 <<primsrast-fragment-shading-rate-attachment, fragment shading rate 4386 attachment>> 4387endif::VK_KHR_fragment_shading_rate[] 4388ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[or] 4389ifdef::VK_NV_shading_rate_image[] 4390 <<primsrast-shading-rate-image, shading rate image>>. 4391endif::VK_NV_shading_rate_image[] 4392 This layout is valid only for image subresources of images created with 4393 the ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage 4394 bit enabled. 4395endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 4396ifdef::VK_EXT_fragment_density_map[] 4397 * ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT must: only be 4398 used as a fragment density map attachment in a sname:VkRenderPass. 4399 This layout is valid only for image subresources of images created with 4400 the ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT usage bit enabled. 4401endif::VK_EXT_fragment_density_map[] 4402ifdef::VK_KHR_video_decode_queue[] 4403 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR must: only be used as a 4404 <<decode-output-picture,decode output picture>> in a 4405 <<video-decode-operations,video decode operation>>. 4406 This layout is valid only for image subresources of images created with 4407 the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage bit enabled. 4408 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR is reserved for future use. 4409 * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR must: only be used as an 4410 output <<reconstructed-picture,reconstructed picture>> or an input 4411 <<reference-picture,reference picture>> in a <<video-decode-operations, 4412 video decode operation>>. 4413 This layout is valid only for image subresources of images created with 4414 the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage bit enabled. 4415endif::VK_KHR_video_decode_queue[] 4416ifdef::VK_KHR_video_encode_queue[] 4417 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR is reserved for future use. 4418 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR must: only be used as an 4419 <<encode-input-picture,encode input picture>> in a 4420 <<video-encode-operations,video encode operation>>. 4421 This layout is valid only for image subresources of images created with 4422 the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage bit enabled. 4423 * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR must: only be used as an 4424 output <<reconstructed-picture,reconstructed picture>> or an input 4425 <<reference-picture,reference picture>> in a <<video-encode-operations, 4426 video encode operation>>. 4427 This layout is valid only for image subresources of images created with 4428 the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage bit enabled. 4429endif::VK_KHR_video_encode_queue[] 4430ifdef::VK_EXT_attachment_feedback_loop_layout[] 4431 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT must: only be 4432 used as either a color attachment or depth/stencil attachment in a 4433 sname:VkFramebuffer and/or read-only access in a shader as a sampled 4434 image, combined image/sampler, or input attachment. 4435 This layout is valid only for image subresources of images created with 4436 the ename:VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit 4437 enabled and either the ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or 4438 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT and either the 4439 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or 4440 ename:VK_IMAGE_USAGE_SAMPLED_BIT usage bits enabled. 4441endif::VK_EXT_attachment_feedback_loop_layout[] 4442 4443The layout of each image subresource is not a state of the image subresource 4444itself, but is rather a property of how the data in memory is organized, and 4445thus for each mechanism of accessing an image in the API the application 4446must: specify a parameter or structure member that indicates which image 4447layout the image subresource(s) are considered to be in when the image will 4448be accessed. 4449For transfer commands, this is a parameter to the command (see <<clears>> 4450and <<copies>>). 4451For use as a framebuffer attachment, this is a member in the substructures 4452of the slink:VkRenderPassCreateInfo (see <<renderpass,Render Pass>>). 4453For use in a descriptor set, this is a member in the 4454sname:VkDescriptorImageInfo structure (see <<descriptorsets-updates>>). 4455-- 4456 4457 4458[[resources-image-layouts-matching-rule]] 4459=== Image Layout Matching Rules 4460 4461At the time that any command buffer command accessing an image executes on 4462any queue, the layouts of the image subresources that are accessed must: all 4463match exactly the layout specified via the API controlling those 4464ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[accesses,] 4465ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[accesses.] 4466ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4467except in case of accesses to an image with a depth/stencil format performed 4468through descriptors referring to only a single aspect of the image, where 4469the following relaxed matching rules apply: 4470 4471 * Descriptors referring just to the depth aspect of a depth/stencil image 4472 only need to match in the image layout of the depth aspect, thus 4473 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and 4474 ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL are 4475 considered to match. 4476 * Descriptors referring just to the stencil aspect of a depth/stencil 4477 image only need to match in the image layout of the stencil aspect, thus 4478 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and 4479 ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL are 4480 considered to match. 4481endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4482 4483When performing a layout transition on an image subresource, the old layout 4484value must: either equal the current layout of the image subresource (at the 4485time the transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED 4486(implying that the contents of the image subresource need not be preserved). 4487The new layout used in a transition must: not be 4488ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED. 4489 4490ifdef::VK_EXT_sample_locations[] 4491 4492The image layout of each image subresource of a depth/stencil image created 4493with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is 4494dependent on the last sample locations used to render to the image 4495subresource as a depth/stencil attachment, thus applications must: provide 4496the same sample locations that were last used to render to the given image 4497subresource whenever a layout transition of the image subresource happens, 4498otherwise the contents of the depth aspect of the image subresource become 4499undefined:. 4500 4501In addition, depth reads from a depth/stencil attachment referring to an 4502image subresource range of a depth/stencil image created with 4503ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using 4504different sample locations than what have been last used to perform depth 4505writes to the image subresources of the same image subresource range return 4506undefined: values. 4507 4508Similarly, depth writes to a depth/stencil attachment referring to an image 4509subresource range of a depth/stencil image created with 4510ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using 4511different sample locations than what have been last used to perform depth 4512writes to the image subresources of the same image subresource range make 4513the contents of the depth aspect of those image subresources undefined:. 4514 4515endif::VK_EXT_sample_locations[] 4516 4517 4518[[resources-image-views]] 4519== Image Views 4520 4521[open,refpage='VkImageView',desc='Opaque handle to an image view object',type='handles'] 4522-- 4523Image objects are not directly accessed by pipeline shaders for reading or 4524writing image data. 4525Instead, _image views_ representing contiguous ranges of the image 4526subresources and containing additional metadata are used for that purpose. 4527Views must: be created on images of compatible types, and must: represent a 4528valid subset of image subresources. 4529 4530Image views are represented by sname:VkImageView handles: 4531 4532include::{generated}/api/handles/VkImageView.adoc[] 4533-- 4534 4535[open,refpage='VK_REMAINING_ARRAY_LAYERS',desc='Sentinel for all remaining array layers',type='consts'] 4536-- 4537ename:VK_REMAINING_ARRAY_LAYERS is a special constant value used for image 4538views to indicate that all remaining array layers in an image after the base 4539layer should be included in the view. 4540 4541include::{generated}/api/enums/VK_REMAINING_ARRAY_LAYERS.adoc[] 4542-- 4543 4544[open,refpage='VK_REMAINING_MIP_LEVELS',desc='Sentinel for all remaining mipmap levels',type='consts'] 4545-- 4546ename:VK_REMAINING_MIP_LEVELS is a special constant value used for image 4547views to indicate that all remaining mipmap levels in an image after the 4548base level should be included in the view. 4549 4550include::{generated}/api/enums/VK_REMAINING_MIP_LEVELS.adoc[] 4551-- 4552 4553[open,refpage='VkImageViewType',desc='Image view types',type='enums'] 4554-- 4555The types of image views that can: be created are: 4556 4557include::{generated}/api/enums/VkImageViewType.adoc[] 4558-- 4559 4560[open,refpage='vkCreateImageView',desc='Create an image view from an existing image',type='protos'] 4561-- 4562:refpage: vkCreateImageView 4563:objectnameplural: image views 4564:objectnamecamelcase: imageView 4565:objectcount: 1 4566 4567To create an image view, call: 4568 4569include::{generated}/api/protos/vkCreateImageView.adoc[] 4570 4571 * pname:device is the logical device that creates the image view. 4572 * pname:pCreateInfo is a pointer to a sname:VkImageViewCreateInfo 4573 structure containing parameters to be used to create the image view. 4574 * pname:pAllocator controls host memory allocation as described in the 4575 <<memory-allocation, Memory Allocation>> chapter. 4576 * pname:pView is a pointer to a slink:VkImageView handle in which the 4577 resulting image view object is returned. 4578 4579include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 4580 4581.Valid Usage 4582**** 4583 * [[VUID-vkCreateImageView-image-09179]] 4584 slink:VkImageViewCreateInfo::pname:image must: have been created from 4585 pname:device 4586ifdef::VKSC_VERSION_1_0[] 4587include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 4588 * [[VUID-vkCreateImageView-subresourceRange-05063]] 4589 If slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount is not 4590 ename:VK_REMAINING_ARRAY_LAYERS and is greater than `1`, or if 4591 slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount is 4592 ename:VK_REMAINING_ARRAY_LAYERS and the remaining number of layers in 4593 slink:VkImageViewCreateInfo::pname:image is greater than `1`, the number 4594 of image views with more than one array layer currently allocated from 4595 pname:device plus `1` must: be less than or equal to the total number of 4596 image views requested via 4597 slink:VkDeviceObjectReservationCreateInfo::pname:layeredImageViewRequestCount 4598 specified when pname:device was created 4599endif::VKSC_VERSION_1_0[] 4600**** 4601 4602include::{generated}/validity/protos/vkCreateImageView.adoc[] 4603-- 4604 4605[open,refpage='VkImageViewCreateInfo',desc='Structure specifying parameters of a newly created image view',type='structs'] 4606-- 4607The sname:VkImageViewCreateInfo structure is defined as: 4608 4609include::{generated}/api/structs/VkImageViewCreateInfo.adoc[] 4610 4611 * pname:sType is a elink:VkStructureType value identifying this structure. 4612 * pname:pNext is `NULL` or a pointer to a structure extending this 4613 structure. 4614 * pname:flags is a bitmask of elink:VkImageViewCreateFlagBits specifying 4615 additional parameters of the image view. 4616 * pname:image is a slink:VkImage on which the view will be created. 4617 * pname:viewType is a elink:VkImageViewType value specifying the type of 4618 the image view. 4619 * pname:format is a elink:VkFormat specifying the format and type used to 4620 interpret texel blocks of the image. 4621 * pname:components is a slink:VkComponentMapping structure specifying a 4622 remapping of color components (or of depth or stencil components after 4623 they have been converted into color components). 4624 * pname:subresourceRange is a slink:VkImageSubresourceRange structure 4625 selecting the set of mipmap levels and array layers to be accessible to 4626 the view. 4627 4628[[resources-image-inherited-usage]] 4629Some of the pname:image creation parameters are inherited by the view. 4630In particular, image view creation inherits the implicit parameter 4631pname:usage specifying the allowed usages of the image view that, by 4632default, takes the value of the corresponding pname:usage parameter 4633specified in slink:VkImageCreateInfo at image creation time. 4634ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4635The implicit pname:usage can: be overridden by adding a 4636slink:VkImageViewUsageCreateInfo structure to the pname:pNext chain, but the 4637view usage must: be a subset of the image usage. 4638endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4639ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 4640If pname:image has a depth-stencil format and was created with a 4641slink:VkImageStencilUsageCreateInfo structure included in the pname:pNext 4642chain of slink:VkImageCreateInfo, the usage is calculated based on the 4643pname:subresource.aspectMask provided: 4644 4645 * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_STENCIL_BIT, the 4646 implicit pname:usage is equal to 4647 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. 4648 * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_DEPTH_BIT, the 4649 implicit pname:usage is equal to slink:VkImageCreateInfo::pname:usage. 4650 * If both aspects are included in pname:aspectMask, the implicit 4651 pname:usage is equal to the intersection of 4652 slink:VkImageCreateInfo::pname:usage and 4653 slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. 4654endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 4655 4656ifdef::VK_EXT_image_sliced_view_of_3d[] 4657If pname:image is a 3D image, its Z range can: be restricted to a subset by 4658adding a slink:VkImageViewSlicedCreateInfoEXT to the pname:pNext chain. 4659endif::VK_EXT_image_sliced_view_of_3d[] 4660 4661If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 4662flag, 4663ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4664and if the pname:format of the image is not 4665<<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, 4666endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4667pname:format can: be different from the image's format, but if 4668ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4669pname:image was created without the 4670ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and 4671endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4672they are not equal they must: be _compatible_. 4673Image format compatibility is defined in the 4674<<formats-compatibility-classes,Format Compatibility Classes>> section. 4675Views of compatible formats will have the same mapping between texel 4676coordinates and memory locations irrespective of the pname:format, with only 4677the interpretation of the bit pattern changing. 4678 4679ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4680[[image-views-plane-promotion]] 4681If pname:image was created with a 4682<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and the 4683image view's pname:aspectMask is one of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 4684ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT, the 4685view's aspect mask is considered to be equivalent to 4686ename:VK_IMAGE_ASPECT_COLOR_BIT when used as a framebuffer attachment. 4687endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4688 4689[NOTE] 4690.Note 4691==== 4692Values intended to be used with one view format may: not be exactly 4693preserved when written or read through a different format. 4694For example, an integer value that happens to have the bit pattern of a 4695floating point denorm or NaN may: be flushed or canonicalized when written 4696or read through a view with a floating point format. 4697Similarly, a value written through a signed normalized format that has a bit 4698pattern exactly equal to [eq]#-2^b^# may: be changed to [eq]#-2^b^ {plus} 1# 4699as described in <<fundamentals-fixedfpconv,Conversion from Normalized 4700Fixed-Point to Floating-Point>>. 4701==== 4702 4703ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 4704If pname:image was created with the 4705ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 4706must: be _compatible_ with the image's format as described above; or must: 4707be an uncompressed format, in which case it must: be 4708<<formats-size-compatibility, _size-compatible_>> with the image's format. 4709In this case, the resulting image view's texel dimensions equal the 4710dimensions of the selected mip level divided by the compressed texel block 4711size and rounded up. 4712endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 4713 4714The slink:VkComponentMapping pname:components member describes a remapping 4715from components of the image to components of the vector returned by shader 4716image instructions. 4717This remapping must: be the identity swizzle for storage image descriptors, 4718input attachment descriptors, 4719ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4720and framebuffer attachments. 4721endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4722ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4723framebuffer attachments, and any sname:VkImageView used with a combined 4724image sampler that enables <<samplers-YCbCr-conversion,sampler {YCbCr} 4725conversion>>. 4726endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4727 4728ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4729If the image view is to be used with a sampler which supports 4730<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>, an _identically 4731defined object_ of type slink:VkSamplerYcbcrConversion to that used to 4732create the sampler must: be passed to flink:vkCreateImageView in a 4733slink:VkSamplerYcbcrConversionInfo included in the pname:pNext chain of 4734slink:VkImageViewCreateInfo. 4735Conversely, if a slink:VkSamplerYcbcrConversion object is passed to 4736flink:vkCreateImageView, an identically defined 4737slink:VkSamplerYcbcrConversion object must: be used when sampling the image. 4738 4739[[image-views-requiring-sampler-ycbcr-conversion]] 4740If the image has a 4741<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format, 4742pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, and 4743pname:usage includes ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the pname:format 4744must: be identical to the image pname:format and the sampler to be used with 4745the image view must: enable <<samplers-YCbCr-conversion,sampler {YCbCr} 4746conversion>>. 4747 4748ifdef::VK_KHR_video_queue[] 4749When such an image is used in a <<video-coding,video coding>> operation, the 4750<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> has no effect. 4751endif::VK_KHR_video_queue[] 4752 4753If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT 4754and the image has a 4755<<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format, 4756and if pname:subresourceRange.aspectMask is 4757ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or 4758ename:VK_IMAGE_ASPECT_PLANE_2_BIT, pname:format must: be 4759<<formats-compatible-planes,compatible>> with the corresponding plane of the 4760image, and the sampler to be used with the image view must: not enable 4761<<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>. 4762The pname:width and pname:height of the single-plane image view must: be 4763derived from the multi-planar image's dimensions in the manner listed for 4764<<formats-compatible-planes,plane compatibility>> for the plane. 4765 4766Any view of an image plane will have the same mapping between texel 4767coordinates and memory locations as used by the components of the color 4768aspect, subject to the formulae relating texel coordinates to 4769lower-resolution planes as described in <<textures-chroma-reconstruction, 4770Chroma Reconstruction>>. 4771That is, if an R or B plane has a reduced resolution relative to the G plane 4772of the multi-planar image, the image view operates using the (_u~plane~_, 4773_v~plane~_) unnormalized coordinates of the reduced-resolution plane, and 4774these coordinates access the same memory locations as the (_u~color~_, 4775_v~color~_) unnormalized coordinates of the color aspect for which chroma 4776reconstruction operations operate on the same (_u~plane~_, _v~plane~_) or 4777(_i~plane~_, _j~plane~_) coordinates. 4778endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 4779 4780[[resources-image-views-compatibility]] 4781.Image type and image view type compatibility requirements 4782[cols="35%,50%",options="header"] 4783|==== 4784| Image View Type | Compatible Image Types 4785| ename:VK_IMAGE_VIEW_TYPE_1D | ename:VK_IMAGE_TYPE_1D 4786| ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY | ename:VK_IMAGE_TYPE_1D 4787| ename:VK_IMAGE_VIEW_TYPE_2D | ename:VK_IMAGE_TYPE_2D 4788ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] 4789| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY | ename:VK_IMAGE_TYPE_2D 4790ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] 4791| ename:VK_IMAGE_VIEW_TYPE_CUBE | ename:VK_IMAGE_TYPE_2D 4792| ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY | ename:VK_IMAGE_TYPE_2D 4793| ename:VK_IMAGE_VIEW_TYPE_3D | ename:VK_IMAGE_TYPE_3D 4794|==== 4795 4796.Valid Usage 4797**** 4798 * [[VUID-VkImageViewCreateInfo-image-01003]] 4799 If pname:image was not created with 4800 ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then pname:viewType must: not 4801 be ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 4802 * [[VUID-VkImageViewCreateInfo-viewType-01004]] 4803 If the <<features-imageCubeArray, pname:imageCubeArray>> feature is not 4804 enabled, pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 4805ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 4806 * [[VUID-VkImageViewCreateInfo-image-06723]] 4807 If pname:image was created with ename:VK_IMAGE_TYPE_3D but without 4808 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then pname:viewType 4809 must: not be ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 4810ifndef::VK_EXT_image_2d_view_of_3d[] 4811 * [[VUID-VkImageViewCreateInfo-image-06727]] 4812 If pname:image was created with ename:VK_IMAGE_TYPE_3D but without 4813 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then pname:viewType 4814 must: not be ename:VK_IMAGE_VIEW_TYPE_2D 4815endif::VK_EXT_image_2d_view_of_3d[] 4816ifdef::VK_EXT_image_2d_view_of_3d[] 4817 * [[VUID-VkImageViewCreateInfo-image-06728]] 4818 If pname:image was created with ename:VK_IMAGE_TYPE_3D but without 4819 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or 4820 ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, then 4821 pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_2D 4822endif::VK_EXT_image_2d_view_of_3d[] 4823 * [[VUID-VkImageViewCreateInfo-image-04970]] 4824 If pname:image was created with ename:VK_IMAGE_TYPE_3D and 4825 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or 4826 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:subresourceRange.levelCount 4827 must: be 1 4828ifndef::VKSC_VERSION_1_0[] 4829 * [[VUID-VkImageViewCreateInfo-image-04971]] 4830 If pname:image was created with ename:VK_IMAGE_TYPE_3D and 4831 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or 4832 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then 4833 slink:VkImageCreateInfo::pname:flags must: not contain any of 4834 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 4835 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and 4836 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 4837endif::VKSC_VERSION_1_0[] 4838 * [[VUID-VkImageViewCreateInfo-image-04972]] 4839 If pname:image was created with a pname:samples value not equal to 4840 ename:VK_SAMPLE_COUNT_1_BIT then pname:viewType must: be either 4841 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 4842endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 4843 * [[VUID-VkImageViewCreateInfo-image-04441]] 4844 pname:image must: have been created with a pname:usage value containing 4845 at least one of the usages defined in the <<valid-imageview-imageusage, 4846 valid image usage>> list for image views 4847 * [[VUID-VkImageViewCreateInfo-None-02273]] 4848 The <<resources-image-view-format-features,format features>> of the 4849 resultant image view must: contain at least one bit 4850 * [[VUID-VkImageViewCreateInfo-usage-02274]] 4851 If pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the 4852 <<resources-image-view-format-features,format features>> of the 4853 resultant image view must: contain 4854 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT 4855 * [[VUID-VkImageViewCreateInfo-usage-02275]] 4856 If pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, then the image 4857 view's <<resources-image-view-format-features,format features>> must: 4858 contain ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT 4859ifndef::VK_NV_linear_color_attachment[] 4860 * [[VUID-VkImageViewCreateInfo-usage-02276]] 4861 If pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then 4862 the image view's <<resources-image-view-format-features,format 4863 features>> must: contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 4864endif::VK_NV_linear_color_attachment[] 4865ifdef::VK_NV_linear_color_attachment[] 4866 * [[VUID-VkImageViewCreateInfo-usage-08931]] 4867 If pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then 4868 the image view's <<resources-image-view-format-features,format 4869 features>> must: contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 4870 ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV 4871endif::VK_NV_linear_color_attachment[] 4872 * [[VUID-VkImageViewCreateInfo-usage-02277]] 4873 If pname:usage contains 4874 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view's 4875 <<resources-image-view-format-features,format features>> must: contain 4876 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 4877ifdef::VK_KHR_video_maintenance1[] 4878ifdef::VK_KHR_video_decode_queue[] 4879 * [[VUID-VkImageViewCreateInfo-image-08333]] 4880 If pname:image was created with 4881 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage 4882 contains ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the image 4883 view's <<resources-image-view-format-features,format features>> must: 4884 contain ename:VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR 4885 * [[VUID-VkImageViewCreateInfo-image-08334]] 4886 If pname:image was created with 4887 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage 4888 contains ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the image 4889 view's <<resources-image-view-format-features,format features>> must: 4890 contain ename:VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR 4891 * [[VUID-VkImageViewCreateInfo-image-08335]] 4892 If pname:image was created with 4893 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then 4894 pname:usage must: not include 4895 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR 4896endif::VK_KHR_video_decode_queue[] 4897ifdef::VK_KHR_video_encode_queue[] 4898 * [[VUID-VkImageViewCreateInfo-image-08336]] 4899 If pname:image was created with 4900 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage 4901 contains ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, then the image 4902 view's <<resources-image-view-format-features,format features>> must: 4903 contain ename:VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR 4904 * [[VUID-VkImageViewCreateInfo-image-08337]] 4905 If pname:image was created with 4906 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage 4907 contains ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the image 4908 view's <<resources-image-view-format-features,format features>> must: 4909 contain ename:VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR 4910 * [[VUID-VkImageViewCreateInfo-image-08338]] 4911 If pname:image was created with 4912 ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then 4913 pname:usage must: not include 4914 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR 4915endif::VK_KHR_video_encode_queue[] 4916endif::VK_KHR_video_maintenance1[] 4917 * [[VUID-VkImageViewCreateInfo-usage-08932]] 4918 If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, 4919ifdef::VK_ANDROID_external_format_resolve[] 4920 and any of the following is true: 4921 ** the <<features-externalFormatResolve, pname:externalFormatResolve>> 4922 feature is not enabled 4923 ** the <<limits-nullColorAttachmentWithExternalFormatResolve, 4924 pname:nullColorAttachmentWithExternalFormatResolve>> property is 4925 ename:VK_FALSE 4926 ** pname:image was created with an 4927 slink:VkExternalFormatANDROID::pname:externalFormat value of 0 4928endif::VK_ANDROID_external_format_resolve[] 4929 4930+ 4931then the image view's <<resources-image-view-format-features,format 4932 features>> must: contain at least one of 4933 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 4934 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 4935ifdef::VK_NV_linear_color_attachment[] 4936 or ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV 4937endif::VK_NV_linear_color_attachment[] 4938 * [[VUID-VkImageViewCreateInfo-subresourceRange-01478]] 4939 pname:subresourceRange.baseMipLevel must: be less than the 4940 pname:mipLevels specified in slink:VkImageCreateInfo when pname:image 4941 was created 4942 * [[VUID-VkImageViewCreateInfo-subresourceRange-01718]] 4943 If pname:subresourceRange.levelCount is not 4944 ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel 4945 {plus} pname:subresourceRange.levelCount# must: be less than or equal to 4946 the pname:mipLevels specified in slink:VkImageCreateInfo when 4947 pname:image was created 4948ifdef::VK_EXT_fragment_density_map[] 4949 * [[VUID-VkImageViewCreateInfo-image-02571]] 4950 If pname:image was created with pname:usage containing 4951 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, 4952 pname:subresourceRange.levelCount must: be `1` 4953endif::VK_EXT_fragment_density_map[] 4954ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] 4955 * [[VUID-VkImageViewCreateInfo-subresourceRange-01480]] 4956 pname:subresourceRange.baseArrayLayer must: be less than the 4957 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 4958 was created 4959 * [[VUID-VkImageViewCreateInfo-subresourceRange-01719]] 4960 If pname:subresourceRange.layerCount is not 4961 ename:VK_REMAINING_ARRAY_LAYERS, 4962 [eq]#pname:subresourceRange.baseArrayLayer {plus} 4963 pname:subresourceRange.layerCount# must: be less than or equal to the 4964 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 4965 was created 4966endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 4967ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 4968ifndef::VK_EXT_image_2d_view_of_3d[] 4969 * [[VUID-VkImageViewCreateInfo-image-01482]] 4970 If pname:image is not a 3D image created with 4971 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or pname:viewType is 4972 not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 4973 pname:subresourceRange.baseArrayLayer must: be less than the 4974 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 4975 was created 4976 * [[VUID-VkImageViewCreateInfo-subresourceRange-01483]] 4977 If pname:subresourceRange.layerCount is not 4978 ename:VK_REMAINING_ARRAY_LAYERS, pname:image is not a 3D image created 4979 with ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or 4980 pname:viewType is not ename:VK_IMAGE_VIEW_TYPE_2D or 4981 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, pname:subresourceRange.layerCount 4982 must: be non-zero and [eq]#pname:subresourceRange.baseArrayLayer {plus} 4983 pname:subresourceRange.layerCount# must: be less than or equal to the 4984 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 4985 was created 4986endif::VK_EXT_image_2d_view_of_3d[] 4987ifdef::VK_EXT_image_2d_view_of_3d[] 4988 * [[VUID-VkImageViewCreateInfo-image-06724]] 4989 If pname:image is not a 3D image created with 4990 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or 4991 ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, or pname:viewType 4992 is not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 4993 pname:subresourceRange.baseArrayLayer must: be less than the 4994 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 4995 was created 4996 * [[VUID-VkImageViewCreateInfo-subresourceRange-06725]] 4997 If pname:subresourceRange.layerCount is not 4998 ename:VK_REMAINING_ARRAY_LAYERS, pname:image is not a 3D image created 4999 with ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT or 5000 ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set, or pname:viewType 5001 is not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 5002 pname:subresourceRange.layerCount must: be non-zero and 5003 [eq]#pname:subresourceRange.baseArrayLayer {plus} 5004 pname:subresourceRange.layerCount# must: be less than or equal to the 5005 pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image 5006 was created 5007endif::VK_EXT_image_2d_view_of_3d[] 5008 * [[VUID-VkImageViewCreateInfo-image-02724]] 5009 If pname:image is a 3D image created with 5010 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is 5011 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 5012 pname:subresourceRange.baseArrayLayer must: be less than the depth 5013 computed from pname:baseMipLevel and pname:extent.depth specified in 5014 slink:VkImageCreateInfo when pname:image was created, according to the 5015 formula defined in <<resources-image-mip-level-sizing,Image Mip Level 5016 Sizing>> 5017 * [[VUID-VkImageViewCreateInfo-subresourceRange-02725]] 5018 If pname:subresourceRange.layerCount is not 5019 ename:VK_REMAINING_ARRAY_LAYERS, pname:image is a 3D image created with 5020 ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is 5021 ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, 5022 pname:subresourceRange.layerCount must: be non-zero and 5023 [eq]#pname:subresourceRange.baseArrayLayer {plus} 5024 pname:subresourceRange.layerCount# must: be less than or equal to the 5025 depth computed from pname:baseMipLevel and pname:extent.depth specified 5026 in slink:VkImageCreateInfo when pname:image was created, according to 5027 the formula defined in <<resources-image-mip-level-sizing,Image Mip 5028 Level Sizing>> 5029endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 5030// The VU below comes in 4 alternate versions 5031// both disabled, both enabled, maintenance2 only, ycbcr only 5032ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5033ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5034 * [[VUID-VkImageViewCreateInfo-image-01018]] 5035 If pname:image was created with the 5036 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be 5037 compatible with the pname:format used to create pname:image, as defined 5038 in <<formats-compatibility-classes,Format Compatibility Classes>> 5039endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5040endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5041// The nested ifdefs are there in anticipation of the hoped-for day when the 5042// VU extractor and validation layers can handle VU with imbedded 5043// conditionals. They are commented out until then. 5044// 5045// If VK_VERSION_1_1,VK_KHR_maintenance2 and NOT VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 5046ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5047ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5048 * [[VUID-VkImageViewCreateInfo-image-01759]] 5049 If pname:image was created with the 5050 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the 5051 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 5052 must: be compatible with the pname:format used to create pname:image, as 5053 defined in <<formats-compatibility-classes,Format Compatibility 5054 Classes>> 5055endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5056endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5057// If NOT VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 5058ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5059ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5060 * [[VUID-VkImageViewCreateInfo-image-01760]] 5061 If pname:image was created with the 5062 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the pname:format 5063 of the pname:image is not a 5064 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, 5065 pname:format must: be compatible with the pname:format used to create 5066 pname:image, as defined in <<formats-compatibility-classes,Format 5067 Compatibility Classes>> 5068endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5069endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5070// If VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion 5071ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5072ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5073 * [[VUID-VkImageViewCreateInfo-image-01761]] 5074 If pname:image was created with the 5075 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, 5076// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5077 but without the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT 5078 flag, 5079// endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5080// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5081 and if the pname:format of the pname:image is not a 5082 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, 5083// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5084 pname:format must: be compatible with the pname:format used to create 5085 pname:image, as defined in <<formats-compatibility-classes,Format 5086 Compatibility Classes>> 5087endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5088endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5089ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5090 * [[VUID-VkImageViewCreateInfo-image-01583]] 5091 If pname:image was created with the 5092 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format 5093 must: be compatible with, or must: be an uncompressed format that is 5094 size-compatible with, the pname:format used to create pname:image 5095 * [[VUID-VkImageViewCreateInfo-image-07072]] 5096 If pname:image was created with the 5097 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and 5098 pname:format is a non-compressed format, the pname:levelCount member of 5099 pname:subresourceRange must: be `1` 5100 * [[VUID-VkImageViewCreateInfo-image-09487]] 5101 If pname:image was created with the 5102 ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, 5103ifdef::VK_KHR_maintenance6[] 5104 the 5105 sname:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:blockTexelViewCompatibleMultipleLayers 5106 property is not set to ename:VK_TRUE, 5107endif::VK_KHR_maintenance6[] 5108 and pname:format is a non-compressed format, then the pname:layerCount 5109 member of pname:subresourceRange must: be `1` 5110endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5111ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] 5112 * [[VUID-VkImageViewCreateInfo-pNext-01585]] 5113 If a slink:VkImageFormatListCreateInfo structure was included in the 5114 pname:pNext chain of the slink:VkImageCreateInfo structure used when 5115 creating pname:image and 5116 slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero 5117 then pname:format must: be one of the formats in 5118 slink:VkImageFormatListCreateInfo::pname:pViewFormats 5119endif::VK_VERSION_1_2,VK_KHR_image_format_list[] 5120ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5121 * [[VUID-VkImageViewCreateInfo-image-01586]] 5122 If pname:image was created with the 5123 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the pname:format of 5124 the pname:image is a 5125 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and 5126 if pname:subresourceRange.aspectMask is one of the 5127 <<formats-planes-image-aspect,multi-planar aspect mask>> bits, then 5128 pname:format must: be compatible with the elink:VkFormat for the plane 5129 of the pname:image pname:format indicated by 5130 pname:subresourceRange.aspectMask, as defined in 5131 <<formats-compatible-planes>> 5132 * [[VUID-VkImageViewCreateInfo-subresourceRange-07818]] 5133 pname:subresourceRange.aspectMask must: only have at most 1 valid 5134 <<formats-planes-image-aspect,multi-planar aspect mask>> bit 5135endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5136ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5137// The VU below comes in an alternate version when the extension is 5138// enabled. 5139 * [[VUID-VkImageViewCreateInfo-image-01019]] 5140 If pname:image was not created with the 5141 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be 5142 identical to the pname:format used to create pname:image 5143endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5144// The nested ifdefs are there in anticipation of the hoped-for day when the 5145// VU extractor and validation layers can handle VU with imbedded 5146// conditionals. They are commented out until then. 5147ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5148 * [[VUID-VkImageViewCreateInfo-image-01762]] 5149 If pname:image was not created with the 5150 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, 5151// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5152 or if the pname:format of the pname:image is a 5153 <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format and 5154 if pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, 5155// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5156 pname:format must: be identical to the pname:format used to create 5157 pname:image 5158endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5159ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5160 * [[VUID-VkImageViewCreateInfo-format-06415]] 5161 If the image view <<image-views-requiring-sampler-ycbcr-conversion, 5162 requires a sampler {YCbCr} conversion>> and pname:usage contains 5163 ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the pname:pNext chain must: 5164 include a slink:VkSamplerYcbcrConversionInfo structure with a conversion 5165 value other than dlink:VK_NULL_HANDLE 5166 * [[VUID-VkImageViewCreateInfo-format-04714]] 5167 If pname:format has a code:_422 or code:_420 suffix then pname:image 5168 must: have been created with a width that is a multiple of 2 5169 * [[VUID-VkImageViewCreateInfo-format-04715]] 5170 If pname:format has a code:_420 suffix then pname:image must: have been 5171 created with a height that is a multiple of 2 5172 * [[VUID-VkImageViewCreateInfo-pNext-01970]] 5173 If the pname:pNext chain includes a slink:VkSamplerYcbcrConversionInfo 5174 structure with a pname:conversion value other than dlink:VK_NULL_HANDLE, 5175 all members of pname:components must: have the 5176 <<resources-image-views-identity-mappings,identity swizzle>> 5177 * [[VUID-VkImageViewCreateInfo-pNext-06658]] 5178 If the pname:pNext chain includes a slink:VkSamplerYcbcrConversionInfo 5179 structure with a pname:conversion value other than dlink:VK_NULL_HANDLE, 5180 pname:format must: be the same used in 5181 slink:VkSamplerYcbcrConversionCreateInfo::pname:format 5182endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5183 * [[VUID-VkImageViewCreateInfo-image-01020]] 5184 If pname:image is non-sparse then it must: be bound completely and 5185 contiguously to a single sname:VkDeviceMemory object 5186 * [[VUID-VkImageViewCreateInfo-subResourceRange-01021]] 5187 pname:viewType must: be compatible with the type of pname:image as shown 5188 in the <<resources-image-views-compatibility,view type compatibility 5189 table>> 5190ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 5191 * [[VUID-VkImageViewCreateInfo-image-02399]] 5192 If pname:image has an 5193 <<memory-external-android-hardware-buffer-external-formats,Android 5194 external format>>, pname:format must: be ename:VK_FORMAT_UNDEFINED 5195 * [[VUID-VkImageViewCreateInfo-image-02400]] 5196 If pname:image has an 5197 <<memory-external-android-hardware-buffer-external-formats,Android 5198 external format>>, the pname:pNext chain must: include a 5199 slink:VkSamplerYcbcrConversionInfo structure with a pname:conversion 5200 object created with the same external format as pname:image 5201 * [[VUID-VkImageViewCreateInfo-image-02401]] 5202 If pname:image has an 5203 <<memory-external-android-hardware-buffer-external-formats,Android 5204 external format>>, all members of pname:components must: be the 5205 <<resources-image-views-identity-mappings,identity swizzle>> 5206endif::VK_ANDROID_external_memory_android_hardware_buffer[] 5207ifdef::VK_QNX_external_memory_screen_buffer[] 5208 * [[VUID-VkImageViewCreateInfo-image-08957]] 5209 If pname:image has an 5210 <<memory-external-screen-buffer-external-formats,QNX Screen external 5211 format>>, pname:format must: be ename:VK_FORMAT_UNDEFINED 5212 * [[VUID-VkImageViewCreateInfo-image-08958]] 5213 If pname:image has an 5214 <<memory-external-screen-buffer-external-formats,QNX Screen external 5215 format>>, the pname:pNext chain must: include a 5216 slink:VkSamplerYcbcrConversionInfo structure with a pname:conversion 5217 object created with the same external format as pname:image 5218 * [[VUID-VkImageViewCreateInfo-image-08959]] 5219 If pname:image has an 5220 <<memory-external-screen-buffer-external-formats,QNX Screen external 5221 format>>, all members of pname:components must: be the 5222 <<resources-image-views-identity-mappings,identity swizzle>> 5223endif::VK_QNX_external_memory_screen_buffer[] 5224ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 5225 * [[VUID-VkImageViewCreateInfo-image-02086]] 5226 If pname:image was created with pname:usage containing 5227 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, 5228 pname:viewType must: be ename:VK_IMAGE_VIEW_TYPE_2D or 5229 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 5230endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 5231ifdef::VK_NV_shading_rate_image[] 5232 * [[VUID-VkImageViewCreateInfo-image-02087]] 5233 If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 5234 enabled, and If pname:image was created with pname:usage containing 5235 ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, pname:format must: be 5236 ename:VK_FORMAT_R8_UINT 5237endif::VK_NV_shading_rate_image[] 5238ifdef::VK_KHR_fragment_shading_rate[] 5239 * [[VUID-VkImageViewCreateInfo-usage-04550]] 5240 If the <<features-attachmentFragmentShadingRate, 5241 pname:attachmentFragmentShadingRate>> feature is enabled, and the 5242 pname:usage for the image view includes 5243 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then the 5244 image view's <<resources-image-view-format-features,format features>> 5245 must: contain 5246 ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 5247 * [[VUID-VkImageViewCreateInfo-usage-04551]] 5248 If the <<features-attachmentFragmentShadingRate, 5249 pname:attachmentFragmentShadingRate>> feature is enabled, the 5250 pname:usage for the image view includes 5251 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, and 5252 <<limits-layeredShadingRateAttachments, 5253 pname:layeredShadingRateAttachments>> is ename:VK_FALSE, 5254 pname:subresourceRange.layerCount must: be `1` 5255endif::VK_KHR_fragment_shading_rate[] 5256ifdef::VK_EXT_fragment_density_map[] 5257 * [[VUID-VkImageViewCreateInfo-flags-02572]] 5258 If the <<features-fragmentDensityMapDynamic, 5259 pname:fragmentDensityMapDynamic>> feature is not enabled, pname:flags 5260 must: not contain 5261 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 5262ifdef::VK_EXT_fragment_density_map2[] 5263 * [[VUID-VkImageViewCreateInfo-flags-03567]] 5264 If the <<features-fragmentDensityMapDeferred, 5265 pname:fragmentDensityMapDeferred>> feature is not enabled, pname:flags 5266 must: not contain 5267 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT 5268 * [[VUID-VkImageViewCreateInfo-flags-03568]] 5269 If pname:flags contains 5270 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT, 5271 pname:flags must: not contain 5272 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 5273 * [[VUID-VkImageViewCreateInfo-image-03569]] 5274 If pname:image was created with pname:flags containing 5275 ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT and pname:usage containing 5276 ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:subresourceRange.layerCount 5277 must: be less than or equal to <<limits-maxSubsampledArrayLayers, 5278 sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:maxSubsampledArrayLayers>> 5279endif::VK_EXT_fragment_density_map2[] 5280ifdef::VK_HUAWEI_invocation_mask[] 5281 * [[VUID-VkImageViewCreateInfo-invocationMask-04993]] 5282 If the <<features-invocationMask, pname:invocationMask>> feature is 5283 enabled, and if pname:image was created with pname:usage containing 5284 ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, pname:format must: be 5285 ename:VK_FORMAT_R8_UINT 5286endif::VK_HUAWEI_invocation_mask[] 5287 * [[VUID-VkImageViewCreateInfo-flags-04116]] 5288 If pname:flags does not contain 5289 ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT and 5290 pname:image was created with pname:usage containing 5291 ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, its pname:flags must: 5292 not contain any of ename:VK_IMAGE_CREATE_PROTECTED_BIT, 5293 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, 5294 ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or 5295 ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT 5296endif::VK_EXT_fragment_density_map[] 5297ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5298ifndef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 5299 * [[VUID-VkImageViewCreateInfo-pNext-02661]] 5300 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 5301 structure, its pname:usage member must: not include any bits that were 5302 not set in the pname:usage member of the slink:VkImageCreateInfo 5303 structure used to create pname:image 5304endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 5305ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 5306 * [[VUID-VkImageViewCreateInfo-pNext-02662]] 5307 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 5308 structure, and pname:image was not created with a 5309 slink:VkImageStencilUsageCreateInfo structure included in the 5310 pname:pNext chain of slink:VkImageCreateInfo, its pname:usage member 5311 must: not include any bits that were not set in the pname:usage member 5312 of the slink:VkImageCreateInfo structure used to create pname:image 5313 * [[VUID-VkImageViewCreateInfo-pNext-02663]] 5314 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 5315 structure, pname:image was created with a 5316 slink:VkImageStencilUsageCreateInfo structure included in the 5317 pname:pNext chain of slink:VkImageCreateInfo, and 5318 pname:subresourceRange.aspectMask includes 5319 ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the 5320 slink:VkImageViewUsageCreateInfo structure must: not include any bits 5321 that were not set in the pname:usage member of the 5322 slink:VkImageStencilUsageCreateInfo structure used to create pname:image 5323 * [[VUID-VkImageViewCreateInfo-pNext-02664]] 5324 If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo 5325 structure, pname:image was created with a 5326 slink:VkImageStencilUsageCreateInfo structure included in the 5327 pname:pNext chain of slink:VkImageCreateInfo, and 5328 pname:subresourceRange.aspectMask includes bits other than 5329 ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the 5330 slink:VkImageViewUsageCreateInfo structure must: not include any bits 5331 that were not set in the pname:usage member of the 5332 slink:VkImageCreateInfo structure used to create pname:image 5333endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] 5334endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5335 * [[VUID-VkImageViewCreateInfo-imageViewType-04973]] 5336 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, 5337 ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and 5338 pname:subresourceRange.layerCount is not 5339 ename:VK_REMAINING_ARRAY_LAYERS, then pname:subresourceRange.layerCount 5340 must: be 1 5341 * [[VUID-VkImageViewCreateInfo-imageViewType-04974]] 5342 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, 5343 ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and 5344 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 5345 then the remaining number of layers must: be 1 5346 * [[VUID-VkImageViewCreateInfo-viewType-02960]] 5347 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and 5348 pname:subresourceRange.layerCount is not 5349 ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: 5350 be `6` 5351 * [[VUID-VkImageViewCreateInfo-viewType-02961]] 5352 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and 5353 pname:subresourceRange.layerCount is not 5354 ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: 5355 be a multiple of `6` 5356 * [[VUID-VkImageViewCreateInfo-viewType-02962]] 5357 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and 5358 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 5359 the remaining number of layers must: be `6` 5360 * [[VUID-VkImageViewCreateInfo-viewType-02963]] 5361 If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and 5362 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 5363 the remaining number of layers must: be a multiple of `6` 5364ifdef::VK_KHR_portability_subset[] 5365 * [[VUID-VkImageViewCreateInfo-imageViewFormatSwizzle-04465]] 5366 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 5367 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatSwizzle 5368 is ename:VK_FALSE, all elements of pname:components must: have the 5369 <<resources-image-views-identity-mappings,identity swizzle>> 5370 * [[VUID-VkImageViewCreateInfo-imageViewFormatReinterpretation-04466]] 5371 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 5372 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatReinterpretation 5373 is ename:VK_FALSE, the elink:VkFormat in pname:format must: not contain 5374 a different number of components, or a different number of bits in each 5375 component, than the format of the sname:VkImage in pname:image 5376endif::VK_KHR_portability_subset[] 5377ifdef::VKSC_VERSION_1_0[] 5378 * [[VUID-VkImageViewCreateInfo-subresourceRange-05064]] 5379 If pname:subresourceRange.levelCount is not 5380 ename:VK_REMAINING_MIP_LEVELS, pname:subresourceRange.levelCount must: 5381 be less than or equal to 5382 slink:VkDeviceObjectReservationCreateInfo::pname:maxImageViewMipLevels 5383 * [[VUID-VkImageViewCreateInfo-subresourceRange-05200]] 5384 If pname:subresourceRange.levelCount is ename:VK_REMAINING_MIP_LEVELS, 5385 the remaining number of mip levels must: be less than or equal to 5386 slink:VkDeviceObjectReservationCreateInfo::pname:maxImageViewMipLevels 5387 * [[VUID-VkImageViewCreateInfo-subresourceRange-05065]] 5388 If pname:subresourceRange.layerCount is not 5389 ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: 5390 be less than or equal to 5391 slink:VkDeviceObjectReservationCreateInfo::pname:maxImageViewArrayLayers 5392 * [[VUID-VkImageViewCreateInfo-subresourceRange-05201]] 5393 If pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, 5394 the remaining number of layers must: be less than or equal to 5395 slink:VkDeviceObjectReservationCreateInfo::pname:maxImageViewMipLevels 5396 * [[VUID-VkImageViewCreateInfo-subresourceRange-05066]] 5397 If pname:subresourceRange.layerCount is not 5398 ename:VK_REMAINING_ARRAY_LAYERS and is greater than `1`, or if 5399 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS and 5400 the remaining number of layers is greater than `1`, then if 5401 pname:subresourceRange.levelCount is not ename:VK_REMAINING_MIP_LEVELS, 5402 pname:subresourceRange.levelCount must: be less than or equal to 5403 slink:VkDeviceObjectReservationCreateInfo::pname:maxLayeredImageViewMipLevels 5404 * [[VUID-VkImageViewCreateInfo-subresourceRange-05202]] 5405 If pname:subresourceRange.layerCount is not 5406 ename:VK_REMAINING_ARRAY_LAYERS and is greater than `1`, or if 5407 pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS and 5408 the remaining number of layers is greater than `1`, then if 5409 pname:subresourceRange.levelCount is ename:VK_REMAINING_MIP_LEVELS, the 5410 remaining number of mip levels must: be less than or equal to 5411 slink:VkDeviceObjectReservationCreateInfo::pname:maxLayeredImageViewMipLevels 5412endif::VKSC_VERSION_1_0[] 5413ifdef::VK_KHR_video_decode_queue[] 5414 * [[VUID-VkImageViewCreateInfo-image-04817]] 5415 If pname:image was created with pname:usage containing 5416 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, 5417 ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, or 5418 ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:viewType 5419 must: be ename:VK_IMAGE_VIEW_TYPE_2D or 5420 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 5421endif::VK_KHR_video_decode_queue[] 5422ifdef::VK_KHR_video_encode_queue[] 5423 * [[VUID-VkImageViewCreateInfo-image-04818]] 5424 If pname:image was created with pname:usage containing 5425 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, 5426 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, or 5427 ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:viewType 5428 must: be ename:VK_IMAGE_VIEW_TYPE_2D or 5429 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 5430endif::VK_KHR_video_encode_queue[] 5431ifdef::VK_EXT_descriptor_buffer[] 5432 * [[VUID-VkImageViewCreateInfo-flags-08106]] 5433 If pname:flags includes 5434 ename:VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the 5435 <<features-descriptorBufferCaptureReplay, 5436 pname:descriptorBufferCaptureReplay>> feature must: be enabled 5437 * [[VUID-VkImageViewCreateInfo-pNext-08107]] 5438 If the pname:pNext chain includes a 5439 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, pname:flags 5440 must: contain 5441 ename:VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 5442endif::VK_EXT_descriptor_buffer[] 5443ifdef::VK_EXT_metal_objects[] 5444 * [[VUID-VkImageViewCreateInfo-pNext-06787]] 5445 If the pname:pNext chain includes a 5446 slink:VkExportMetalObjectCreateInfoEXT structure, its 5447 pname:exportObjectType member must: be 5448 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_TEXTURE_BIT_EXT 5449endif::VK_EXT_metal_objects[] 5450ifdef::VK_QCOM_image_processing[] 5451 * [[VUID-VkImageViewCreateInfo-pNext-06944]] 5452 If the pname:pNext chain includes 5453 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then 5454 <<features-textureSampleWeighted, pname:textureSampleWeighted>> feature 5455 must: be enabled 5456 * [[VUID-VkImageViewCreateInfo-pNext-06945]] 5457 If the pname:pNext chain includes 5458 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then pname:image 5459 must: have been created with pname:usage containing 5460 ename:VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM 5461 * [[VUID-VkImageViewCreateInfo-pNext-06946]] 5462 If the pname:pNext chain includes 5463 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then 5464 pname:components must: be ename:VK_COMPONENT_SWIZZLE_IDENTITY for all 5465 components 5466 * [[VUID-VkImageViewCreateInfo-pNext-06947]] 5467 If the pname:pNext chain includes 5468 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then 5469 pname:subresourceRange.aspectMask must: be 5470 ename:VK_IMAGE_ASPECT_COLOR_BIT 5471 * [[VUID-VkImageViewCreateInfo-pNext-06948]] 5472 If the pname:pNext chain includes 5473 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then 5474 pname:subresourceRange.levelCount must: be `1` 5475 * [[VUID-VkImageViewCreateInfo-pNext-06949]] 5476 If the pname:pNext chain includes 5477 slink:VkImageViewSampleWeightCreateInfoQCOM structure, then 5478 pname:viewType must: be ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY or 5479 ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY 5480 * [[VUID-VkImageViewCreateInfo-pNext-06950]] 5481 If the pname:pNext chain includes 5482 slink:VkImageViewSampleWeightCreateInfoQCOM structure and if 5483 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, then pname:image 5484 must: have been created with pname:imageType ename:VK_IMAGE_TYPE_1D 5485 * [[VUID-VkImageViewCreateInfo-pNext-06951]] 5486 If the pname:pNext chain includes 5487 slink:VkImageViewSampleWeightCreateInfoQCOM structure and pname:viewType 5488 is ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, then 5489 pname:subresourceRange.layerCount must: be equal to `2` 5490 * [[VUID-VkImageViewCreateInfo-pNext-06952]] 5491 If the pname:pNext chain includes 5492 slink:VkImageViewSampleWeightCreateInfoQCOM structure and pname:viewType 5493 is ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY, then pname:image must: have been 5494 created with pname:width equal to or greater than latexmath:[(numPhases 5495 \times \mathbin{max}\left( 5496 \mathbin{align}\left(filterSize.width,4\right), 5497 filterSize.height\right))] 5498 * [[VUID-VkImageViewCreateInfo-pNext-06953]] 5499 If the pname:pNext chain includes 5500 slink:VkImageViewSampleWeightCreateInfoQCOM structure and if 5501 pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, then pname:image 5502 must: have been created with pname:imageType ename:VK_IMAGE_TYPE_2D 5503 * [[VUID-VkImageViewCreateInfo-pNext-06954]] 5504 If the pname:pNext chain includes 5505 slink:VkImageViewSampleWeightCreateInfoQCOM structure and pname:viewType 5506 is ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, then 5507 pname:subresourceRange.layerCount must: be equal or greater than 5508 [eq]#numPhases# 5509 * [[VUID-VkImageViewCreateInfo-pNext-06955]] 5510 If the pname:pNext chain includes 5511 slink:VkImageViewSampleWeightCreateInfoQCOM structure and pname:viewType 5512 is ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, then pname:image must: have been 5513 created with pname:width equal to or greater than pname:filterSize.width 5514 * [[VUID-VkImageViewCreateInfo-pNext-06956]] 5515 If the pname:pNext chain includes 5516 slink:VkImageViewSampleWeightCreateInfoQCOM structure and pname:viewType 5517 is ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, then pname:image must: have been 5518 created with pname:height equal to or greater than 5519 pname:filterSize.height 5520 * [[VUID-VkImageViewCreateInfo-pNext-06957]] 5521 If the pname:pNext chain includes 5522 slink:VkImageViewSampleWeightCreateInfoQCOM structure then 5523 slink:VkImageViewSampleWeightCreateInfoQCOM::pname:filterSize.height 5524 must: be less than or equal to <<limits-weightfilter-maxdimension, 5525 sname:VkPhysicalDeviceImageProcessingPropertiesQCOM::pname:maxWeightFilterDimension.height>> 5526endif::VK_QCOM_image_processing[] 5527 5528**** 5529 5530include::{generated}/validity/structs/VkImageViewCreateInfo.adoc[] 5531-- 5532 5533[open,refpage='VkImageViewCreateFlagBits',desc='Bitmask specifying additional parameters of an image view',type='enums'] 5534-- 5535Bits which can: be set in slink:VkImageViewCreateInfo::pname:flags, 5536specifying additional parameters of an image view, are: 5537 5538include::{generated}/api/enums/VkImageViewCreateFlagBits.adoc[] 5539 5540ifdef::VK_EXT_fragment_density_map[] 5541 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT 5542 specifies that the fragment density map will be read by device during 5543 ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT 5544ifdef::VK_EXT_fragment_density_map2[] 5545 * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT 5546 specifies that the fragment density map will be read by the host during 5547 flink:vkEndCommandBuffer for the primary command buffer that the render 5548 pass is recorded into 5549endif::VK_EXT_fragment_density_map2[] 5550endif::VK_EXT_fragment_density_map[] 5551ifdef::VK_EXT_descriptor_buffer[] 5552 * ename:VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 5553 specifies that the image view can: be used with descriptor buffers when 5554 capturing and replaying (e.g. for trace capture and replay), see 5555 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. 5556endif::VK_EXT_descriptor_buffer[] 5557-- 5558 5559[open,refpage='VkImageViewCreateFlags',desc='Reserved for future use',type='flags'] 5560-- 5561include::{generated}/api/flags/VkImageViewCreateFlags.adoc[] 5562 5563tname:VkImageViewCreateFlags is a bitmask type for setting a mask of zero or 5564more elink:VkImageViewCreateFlagBits. 5565-- 5566 5567ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 5568[open,refpage='VkImageViewUsageCreateInfo',desc='Specify the intended usage of an image view',type='structs'] 5569-- 5570The set of usages for the created image view can: be restricted compared to 5571the parent image's pname:usage flags by adding a 5572sname:VkImageViewUsageCreateInfo structure to the pname:pNext chain of 5573slink:VkImageViewCreateInfo. 5574 5575The sname:VkImageViewUsageCreateInfo structure is defined as: 5576 5577include::{generated}/api/structs/VkImageViewUsageCreateInfo.adoc[] 5578 5579ifdef::VK_KHR_maintenance2[] 5580or the equivalent 5581 5582include::{generated}/api/structs/VkImageViewUsageCreateInfoKHR.adoc[] 5583endif::VK_KHR_maintenance2[] 5584 5585 * pname:sType is a elink:VkStructureType value identifying this structure. 5586 * pname:pNext is `NULL` or a pointer to a structure extending this 5587 structure. 5588 * pname:usage is a bitmask of elink:VkImageUsageFlagBits specifying 5589 allowed usages of the image view. 5590 5591When this structure is chained to slink:VkImageViewCreateInfo the 5592pname:usage field overrides the implicit pname:usage parameter inherited 5593from image creation time and its value is used instead for the purposes of 5594determining the valid usage conditions of slink:VkImageViewCreateInfo. 5595 5596include::{generated}/validity/structs/VkImageViewUsageCreateInfo.adoc[] 5597-- 5598endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 5599 5600ifdef::VK_EXT_image_sliced_view_of_3d[] 5601[open,refpage='VkImageViewSlicedCreateInfoEXT',desc='Specify the subset of 3D slices of an image view',type='structs'] 5602-- 5603The range of 3D slices for the created image view can: be restricted to a 5604subset of the parent image's Z range by adding a 5605sname:VkImageViewSlicedCreateInfoEXT structure to the pname:pNext chain of 5606slink:VkImageViewCreateInfo. 5607 5608The sname:VkImageViewSlicedCreateInfoEXT structure is defined as: 5609 5610include::{generated}/api/structs/VkImageViewSlicedCreateInfoEXT.adoc[] 5611 5612 * pname:sType is a elink:VkStructureType value identifying this structure. 5613 * pname:pNext is `NULL` or a pointer to a structure extending this 5614 structure. 5615 * pname:sliceOffset is the Z-offset for the first 3D slice accessible to 5616 the image view. 5617 * pname:sliceCount is the number of 3D slices accessible to the image 5618 view. 5619 5620When this structure is chained to slink:VkImageViewCreateInfo the 5621pname:sliceOffset field is treated as a Z-offset for the sliced view and 5622pname:sliceCount specifies the range. 5623Shader accesses using a Z coordinate of 0 will access the depth slice 5624corresponding to pname:sliceOffset in the image, and in a shader, the 5625maximum in-bounds Z coordinate for the view is [eq]#pname:sliceCount - 1#. 5626 5627A sliced 3D view must: only be used with a single mip level. 5628The slice coordinates are integer coordinates within the 5629pname:subresourceRange.baseMipLevel used to create the image view. 5630 5631The effective view depth is equal to pname:extent.depth used to create the 5632pname:image for this view adjusted by pname:subresourceRange.baseMipLevel as 5633specified in <<resources-image-mip-level-sizing,Image Mip Level Sizing>>. 5634 5635Shader access to this image view is only affected by 5636sname:VkImageViewSlicedCreateInfoEXT if it uses a descriptor of type 5637ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. 5638For access using any other descriptor type, the contents of 5639sname:VkImageViewSlicedCreateInfoEXT are ignored; instead, pname:sliceOffset 5640is treated as being equal to 0, and pname:sliceCount is treated as being 5641equal to ename:VK_REMAINING_3D_SLICES_EXT. 5642 5643.Valid Usage 5644**** 5645 * [[VUID-VkImageViewSlicedCreateInfoEXT-sliceOffset-07867]] 5646 pname:sliceOffset must: be less than the effective view depth as 5647 specified in <<resources-image-mip-level-sizing,Image Mip Level Sizing>> 5648 * [[VUID-VkImageViewSlicedCreateInfoEXT-sliceCount-07868]] 5649 If pname:sliceCount is not ename:VK_REMAINING_3D_SLICES_EXT, it must: be 5650 be non-zero and [eq]#pname:sliceOffset {plus} pname:sliceCount# must: be 5651 less than or equal to the effective view depth as specified in 5652 <<resources-image-mip-level-sizing,Image Mip Level Sizing>> 5653 * [[VUID-VkImageViewSlicedCreateInfoEXT-image-07869]] 5654 pname:image must: have been created with pname:imageType equal to 5655 ename:VK_IMAGE_TYPE_3D 5656 * [[VUID-VkImageViewSlicedCreateInfoEXT-viewType-07909]] 5657 pname:viewType must: be ename:VK_IMAGE_VIEW_TYPE_3D 5658 * [[VUID-VkImageViewSlicedCreateInfoEXT-None-07870]] 5659 The image view must: reference exactly 1 mip level 5660 * [[VUID-VkImageViewSlicedCreateInfoEXT-None-07871]] 5661 The <<features-imageSlicedViewOf3D,imageSlicedViewOf3D>> feature must: 5662 be enabled on the device 5663**** 5664 5665include::{generated}/validity/structs/VkImageViewSlicedCreateInfoEXT.adoc[] 5666-- 5667 5668[open,refpage='VK_REMAINING_3D_SLICES_EXT',desc='Sentinel for all remaining 3D slices',type='consts'] 5669-- 5670ename:VK_REMAINING_3D_SLICES_EXT is a special constant value used for 5671slink:VkImageViewSlicedCreateInfoEXT::pname:sliceCount to indicate that all 5672remaining 3D slices in an image after the first slice offset specified 5673should be included in the view. 5674 5675include::{generated}/api/enums/VK_REMAINING_3D_SLICES_EXT.adoc[] 5676-- 5677endif::VK_EXT_image_sliced_view_of_3d[] 5678 5679[open,refpage='VkImageSubresourceRange',desc='Structure specifying an image subresource range',type='structs'] 5680-- 5681The sname:VkImageSubresourceRange structure is defined as: 5682 5683include::{generated}/api/structs/VkImageSubresourceRange.adoc[] 5684 5685 * pname:aspectMask is a bitmask of elink:VkImageAspectFlagBits specifying 5686 which aspect(s) of the image are included in the view. 5687 * pname:baseMipLevel is the first mipmap level accessible to the view. 5688 * pname:levelCount is the number of mipmap levels (starting from 5689 pname:baseMipLevel) accessible to the view. 5690 * pname:baseArrayLayer is the first array layer accessible to the view. 5691 * pname:layerCount is the number of array layers (starting from 5692 pname:baseArrayLayer) accessible to the view. 5693 5694The number of mipmap levels and array layers must: be a subset of the image 5695subresources in the image. 5696If an application wants to use all mip levels or layers in an image after 5697the pname:baseMipLevel or pname:baseArrayLayer, it can: set pname:levelCount 5698and pname:layerCount to the special values ename:VK_REMAINING_MIP_LEVELS and 5699ename:VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip 5700levels or layers. 5701 5702For cube and cube array image views, the layers of the image view starting 5703at pname:baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, 5704-Z. 5705For cube arrays, each set of six sequential layers is a single cube, so the 5706number of cube maps in a cube map array view is _pname:layerCount / 6_, and 5707image array layer [eq]#(pname:baseArrayLayer {plus} i)# is face index 5708[eq]#(i mod 6)# of cube _i / 6_. 5709If the number of layers in the view, whether set explicitly in 5710pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a 5711multiple of 6, the last cube map in the array must: not be accessed. 5712 5713pname:aspectMask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT, 5714ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if 5715pname:format is a color, depth-only or stencil-only format, 5716ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5717respectively. 5718endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5719ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5720respectively, except if pname:format is a 5721<<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>. 5722endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5723If using a depth/stencil format with both depth and stencil components, 5724pname:aspectMask must: include at least one of 5725ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT, and 5726can: include both. 5727 5728ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 5729When the sname:VkImageSubresourceRange structure is used to select a subset 5730of the slices of a 3D image's mip level in order to create a 2D or 2D array 5731image view of a 3D image created with 5732ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, pname:baseArrayLayer and 5733pname:layerCount specify the first slice index and the number of slices to 5734include in the created image view. 5735Such an image view can: be used as a framebuffer attachment that refers only 5736to the specified range of slices of the selected mip level. 5737However, any layout transitions performed on such an attachment view during 5738a render pass instance still apply to the entire subresource referenced 5739which includes all the slices of the selected mip level. 5740endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 5741 5742When using an image view of a depth/stencil image to populate a descriptor 5743set (e.g. for sampling in the shader, or for use as an input attachment), 5744the pname:aspectMask must: only include one bit, which selects whether the 5745image view is used for depth reads (i.e. using a floating-point sampler or 5746input attachment in the shader) or stencil reads (i.e. using an unsigned 5747integer sampler or input attachment in the shader). 5748When an image view of a depth/stencil image is used as a depth/stencil 5749framebuffer attachment, the pname:aspectMask is ignored and both depth and 5750stencil image subresources are used. 5751 5752ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5753When creating a sname:VkImageView, if <<samplers-YCbCr-conversion,sampler 5754{YCbCr} conversion>> is enabled in the sampler, the pname:aspectMask of a 5755pname:subresourceRange used by the sname:VkImageView must: be 5756ename:VK_IMAGE_ASPECT_COLOR_BIT. 5757 5758When creating a sname:VkImageView, if sampler {YCbCr} conversion is not 5759enabled in the sampler and the image pname:format is 5760<<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, the image must: 5761have been created with ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the 5762pname:aspectMask of the sname:VkImageView's pname:subresourceRange must: be 5763ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or 5764ename:VK_IMAGE_ASPECT_PLANE_2_BIT. 5765endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5766 5767.Valid Usage 5768**** 5769 * [[VUID-VkImageSubresourceRange-levelCount-01720]] 5770 If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: be 5771 greater than `0` 5772 * [[VUID-VkImageSubresourceRange-layerCount-01721]] 5773 If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be 5774 greater than `0` 5775ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5776 * [[VUID-VkImageSubresourceRange-aspectMask-01670]] 5777 If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, then it 5778 must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 5779 ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT 5780endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5781ifdef::VK_EXT_image_drm_format_modifier[] 5782 * [[VUID-VkImageSubresourceRange-aspectMask-02278]] 5783 pname:aspectMask must: not include 5784 `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ 5785endif::VK_EXT_image_drm_format_modifier[] 5786**** 5787 5788include::{generated}/validity/structs/VkImageSubresourceRange.adoc[] 5789-- 5790 5791[open,refpage='VkImageAspectFlagBits',desc='Bitmask specifying which aspects of an image are included in a view',type='enums'] 5792-- 5793Bits which can: be set in an aspect mask to specify aspects of an image for 5794purposes such as identifying a subresource, are: 5795 5796include::{generated}/api/enums/VkImageAspectFlagBits.adoc[] 5797 5798ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 5799 * ename:VK_IMAGE_ASPECT_NONE specifies no image aspect, or the image 5800 aspect is not applicable. 5801endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 5802 * ename:VK_IMAGE_ASPECT_COLOR_BIT specifies the color aspect. 5803 * ename:VK_IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect. 5804 * ename:VK_IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect. 5805 * ename:VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect used 5806 for <<sparsememory, sparse resource>> operations. 5807ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5808 * ename:VK_IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a _multi-planar_ 5809 image format. 5810 * ename:VK_IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a _multi-planar_ 5811 image format. 5812 * ename:VK_IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a _multi-planar_ 5813 image format. 5814endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 5815ifdef::VK_EXT_image_drm_format_modifier[] 5816 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT specifies _memory plane_ 0. 5817 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT specifies _memory plane_ 1. 5818 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT specifies _memory plane_ 2. 5819 * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT specifies _memory plane_ 3. 5820endif::VK_EXT_image_drm_format_modifier[] 5821-- 5822 5823[open,refpage='VkImageAspectFlags',desc='Bitmask of VkImageAspectFlagBits',type='flags'] 5824-- 5825include::{generated}/api/flags/VkImageAspectFlags.adoc[] 5826 5827tname:VkImageAspectFlags is a bitmask type for setting a mask of zero or 5828more elink:VkImageAspectFlagBits. 5829-- 5830 5831[open,refpage='VkComponentMapping',desc='Structure specifying a color component mapping',type='structs'] 5832-- 5833The sname:VkComponentMapping structure is defined as: 5834 5835include::{generated}/api/structs/VkComponentMapping.adoc[] 5836 5837 * pname:r is a elink:VkComponentSwizzle specifying the component value 5838 placed in the R component of the output vector. 5839 * pname:g is a elink:VkComponentSwizzle specifying the component value 5840 placed in the G component of the output vector. 5841 * pname:b is a elink:VkComponentSwizzle specifying the component value 5842 placed in the B component of the output vector. 5843 * pname:a is a elink:VkComponentSwizzle specifying the component value 5844 placed in the A component of the output vector. 5845 5846include::{generated}/validity/structs/VkComponentMapping.adoc[] 5847-- 5848 5849[open,refpage='VkComponentSwizzle',desc='Specify how a component is swizzled',type='enums'] 5850-- 5851Possible values of the members of slink:VkComponentMapping, specifying the 5852component values placed in each component of the output vector, are: 5853 5854include::{generated}/api/enums/VkComponentSwizzle.adoc[] 5855 5856 * ename:VK_COMPONENT_SWIZZLE_IDENTITY specifies that the component is set 5857 to the identity swizzle. 5858 * ename:VK_COMPONENT_SWIZZLE_ZERO specifies that the component is set to 5859 zero. 5860 * ename:VK_COMPONENT_SWIZZLE_ONE specifies that the component is set to 5861 either 1 or 1.0, depending on whether the type of the image view format 5862 is integer or floating-point respectively, as determined by the 5863 <<formats-definition,Format Definition>> section for each 5864 elink:VkFormat. 5865 * ename:VK_COMPONENT_SWIZZLE_R specifies that the component is set to the 5866 value of the R component of the image. 5867 * ename:VK_COMPONENT_SWIZZLE_G specifies that the component is set to the 5868 value of the G component of the image. 5869 * ename:VK_COMPONENT_SWIZZLE_B specifies that the component is set to the 5870 value of the B component of the image. 5871 * ename:VK_COMPONENT_SWIZZLE_A specifies that the component is set to the 5872 value of the A component of the image. 5873 5874[[resources-image-views-identity-mappings]] 5875Setting the identity swizzle on a component is equivalent to setting the 5876identity mapping on that component. 5877That is: 5878 5879.Component Mappings Equivalent To ename:VK_COMPONENT_SWIZZLE_IDENTITY 5880[options="header"] 5881|==== 5882| Component | Identity Mapping 5883| pname:components.r | ename:VK_COMPONENT_SWIZZLE_R 5884| pname:components.g | ename:VK_COMPONENT_SWIZZLE_G 5885| pname:components.b | ename:VK_COMPONENT_SWIZZLE_B 5886| pname:components.a | ename:VK_COMPONENT_SWIZZLE_A 5887|==== 5888-- 5889 5890ifdef::VK_EXT_astc_decode_mode[] 5891[open,refpage='VkImageViewASTCDecodeModeEXT',desc='Structure describing the ASTC decode mode for an image view',type='structs'] 5892-- 5893If the pname:pNext chain includes a sname:VkImageViewASTCDecodeModeEXT 5894structure, then that structure includes a parameter specifying the decode 5895mode for image views using ASTC compressed formats. 5896 5897The sname:VkImageViewASTCDecodeModeEXT structure is defined as: 5898 5899include::{generated}/api/structs/VkImageViewASTCDecodeModeEXT.adoc[] 5900 5901 * pname:sType is a elink:VkStructureType value identifying this structure. 5902 * pname:pNext is `NULL` or a pointer to a structure extending this 5903 structure. 5904 * pname:decodeMode is the intermediate format used to decode ASTC 5905 compressed formats. 5906 5907.Valid Usage 5908**** 5909 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02230]] 5910 pname:decodeMode must: be one of ename:VK_FORMAT_R16G16B16A16_SFLOAT, 5911 ename:VK_FORMAT_R8G8B8A8_UNORM, or 5912 ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 5913 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02231]] 5914 If the <<features-astc-decodeModeSharedExponent, 5915 pname:decodeModeSharedExponent>> feature is not enabled, 5916 pname:decodeMode must: not be ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 5917 * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02232]] 5918 If pname:decodeMode is ename:VK_FORMAT_R8G8B8A8_UNORM the image view 5919 must: not include blocks using any of the ASTC HDR modes 5920 * [[VUID-VkImageViewASTCDecodeModeEXT-format-04084]] 5921 pname:format of the image view must: be one of the 5922 <<appendix-compressedtex-astc, ASTC Compressed Image Formats>> 5923**** 5924 5925If pname:format uses sRGB encoding then the pname:decodeMode has no effect. 5926 5927include::{generated}/validity/structs/VkImageViewASTCDecodeModeEXT.adoc[] 5928-- 5929endif::VK_EXT_astc_decode_mode[] 5930 5931ifdef::VK_QCOM_image_processing[] 5932[open,refpage='VkImageViewSampleWeightCreateInfoQCOM',desc='Structure describing weight sampling parameters for image view',type='structs'] 5933-- 5934If the pname:pNext chain includes a 5935sname:VkImageViewSampleWeightCreateInfoQCOM structure, then that structure 5936includes a parameter specifying the parameters for weight image views used 5937in <<textures-weightimage,weight image sampling>>. 5938 5939The sname:VkImageViewSampleWeightCreateInfoQCOM structure is defined as: 5940 5941include::{generated}/api/structs/VkImageViewSampleWeightCreateInfoQCOM.adoc[] 5942 5943 * pname:sType is a elink:VkStructureType value identifying this structure. 5944 * pname:pNext is `NULL` or a pointer to a structure extending this 5945 structure. 5946 * pname:filterCenter is a slink:VkOffset2D describing the location of the 5947 weight filter origin. 5948 * pname:filterSize is a slink:VkExtent2D specifying weight filter 5949 dimensions. 5950 * pname:numPhases is number of sub-pixel filter phases. 5951 5952 5953The pname:filterCenter specifies the origin or center of the filter kernel, 5954as described in <<textures-weightimage-filteroperation, Weight Sampling 5955Operation>>. 5956The pname:numPhases describes the number of sub-pixel filter phases as 5957described in <<textures-weightimage-filterphases,Weight Sampling Phases>>. 5958 5959.Valid Usage 5960**** 5961 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-filterSize-06958]] 5962 pname:filterSize.width must: be less than or equal to 5963 <<limits-weightfilter-maxdimension, 5964 sname:VkPhysicalDeviceImageProcessingPropertiesQCOM::pname:maxWeightFilterDimension.width>> 5965 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-filterSize-06959]] 5966 pname:filterSize.height must: be less than or equal to 5967 <<limits-weightfilter-maxdimension, 5968 sname:VkPhysicalDeviceImageProcessingPropertiesQCOM::pname:maxWeightFilterDimension.height>> 5969 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-filterCenter-06960]] 5970 pname:filterCenter.x must: be less than or equal to 5971 [eq]#(filterSize.width - 1)# 5972 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-filterCenter-06961]] 5973 pname:filterCenter.y must: be less than or equal to 5974 [eq]#(filterSize.height - 1)# 5975 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-numPhases-06962]] 5976 pname:numPhases must: be a power of two squared value (i.e., 1, 4, 16, 5977 64, 256, etc.) 5978 * [[VUID-VkImageViewSampleWeightCreateInfoQCOM-numPhases-06963]] 5979 pname:numPhases must: be less than or equal to 5980 <<limits-weightfilter-phases, 5981 sname:VkPhysicalDeviceImageProcessingPropertiesQCOM::pname:maxWeightFilterPhases>> 5982**** 5983 5984 5985include::{generated}/validity/structs/VkImageViewSampleWeightCreateInfoQCOM.adoc[] 5986-- 5987endif::VK_QCOM_image_processing[] 5988 5989 5990[open,refpage='vkDestroyImageView',desc='Destroy an image view object',type='protos'] 5991-- 5992To destroy an image view, call: 5993 5994include::{generated}/api/protos/vkDestroyImageView.adoc[] 5995 5996 * pname:device is the logical device that destroys the image view. 5997 * pname:imageView is the image view to destroy. 5998 * pname:pAllocator controls host memory allocation as described in the 5999 <<memory-allocation, Memory Allocation>> chapter. 6000 6001.Valid Usage 6002**** 6003 * [[VUID-vkDestroyImageView-imageView-01026]] 6004 All submitted commands that refer to pname:imageView must: have 6005 completed execution 6006ifndef::VKSC_VERSION_1_0[] 6007 * [[VUID-vkDestroyImageView-imageView-01027]] 6008 If sname:VkAllocationCallbacks were provided when pname:imageView was 6009 created, a compatible set of callbacks must: be provided here 6010 * [[VUID-vkDestroyImageView-imageView-01028]] 6011 If no sname:VkAllocationCallbacks were provided when pname:imageView was 6012 created, pname:pAllocator must: be `NULL` 6013endif::VKSC_VERSION_1_0[] 6014**** 6015 6016include::{generated}/validity/protos/vkDestroyImageView.adoc[] 6017-- 6018 6019ifdef::VK_NVX_image_view_handle[] 6020[open,refpage='vkGetImageViewHandleNVX',desc='Get the handle for an image view for a specific descriptor type',type='protos'] 6021-- 6022To get the handle for an image view, call: 6023 6024include::{generated}/api/protos/vkGetImageViewHandleNVX.adoc[] 6025 6026 * pname:device is the logical device that owns the image view. 6027 * pname:pInfo describes the image view to query and type of handle. 6028 6029include::{generated}/validity/protos/vkGetImageViewHandleNVX.adoc[] 6030-- 6031 6032[open,refpage='VkImageViewHandleInfoNVX',desc='Structure specifying the image view for handle queries',type='structs'] 6033-- 6034The sname:VkImageViewHandleInfoNVX structure is defined as: 6035 6036include::{generated}/api/structs/VkImageViewHandleInfoNVX.adoc[] 6037 6038 * pname:sType is a elink:VkStructureType value identifying this structure. 6039 * pname:pNext is `NULL` or a pointer to a structure extending this 6040 structure. 6041 * pname:imageView is the image view to query. 6042 * pname:descriptorType is the type of descriptor for which to query a 6043 handle. 6044 * pname:sampler is the sampler to combine with the image view when 6045 generating the handle. 6046 6047.Valid Usage 6048**** 6049 * [[VUID-VkImageViewHandleInfoNVX-descriptorType-02654]] 6050 pname:descriptorType must: be ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 6051 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 6052 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 6053 * [[VUID-VkImageViewHandleInfoNVX-sampler-02655]] 6054 pname:sampler must: be a valid slink:VkSampler if pname:descriptorType 6055 is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 6056 * [[VUID-VkImageViewHandleInfoNVX-imageView-02656]] 6057 If descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 6058 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the image that 6059 pname:imageView was created from must: have been created with the 6060 ename:VK_IMAGE_USAGE_SAMPLED_BIT usage bit set 6061 * [[VUID-VkImageViewHandleInfoNVX-imageView-02657]] 6062 If descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the image 6063 that pname:imageView was created from must: have been created with the 6064 ename:VK_IMAGE_USAGE_STORAGE_BIT usage bit set 6065**** 6066 6067include::{generated}/validity/structs/VkImageViewHandleInfoNVX.adoc[] 6068-- 6069 6070[open,refpage='vkGetImageViewAddressNVX',desc='Get the device address of an image view',type='protos'] 6071-- 6072To get the device address for an image view, call: 6073 6074include::{generated}/api/protos/vkGetImageViewAddressNVX.adoc[] 6075 6076 * pname:device is the logical device that owns the image view. 6077 * pname:imageView is a handle to the image view. 6078 * pname:pProperties contains the device address and size when the call 6079 returns. 6080 6081include::{generated}/validity/protos/vkGetImageViewAddressNVX.adoc[] 6082-- 6083 6084[open,refpage='VkImageViewAddressPropertiesNVX',desc='Structure specifying the image view for handle queries',type='structs'] 6085-- 6086The sname:VkImageViewAddressPropertiesNVX structure is defined as: 6087 6088include::{generated}/api/structs/VkImageViewAddressPropertiesNVX.adoc[] 6089 6090 * pname:sType is a elink:VkStructureType value identifying this structure. 6091 * pname:pNext is `NULL` or a pointer to a structure extending this 6092 structure. 6093 * pname:deviceAddress is the device address of the image view. 6094 * pname:size is the size in bytes of the image view device memory. 6095 6096 6097include::{generated}/validity/structs/VkImageViewAddressPropertiesNVX.adoc[] 6098-- 6099endif::VK_NVX_image_view_handle[] 6100 6101 6102[[resources-image-view-format-features]] 6103=== Image View Format Features 6104 6105Valid uses of a slink:VkImageView may: depend on the image view's _format 6106features_, defined below. 6107Such constraints are documented in the affected valid usage statement. 6108 6109ifndef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6110 * If slink:VkImageViewCreateInfo::pname:image was created with 6111 ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format 6112 features_ is the value of 6113 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 6114 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 6115 slink:VkImageViewCreateInfo::pname:format. 6116endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6117ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6118 * If Vulkan 1.3 is supported or the `apiext:VK_KHR_format_feature_flags2` 6119 extension is supported, and slink:VkImageViewCreateInfo::pname:image was 6120 created with ename:VK_IMAGE_TILING_LINEAR, then the image view's set of 6121 _format features_ is the value of 6122 slink:VkFormatProperties3::pname:linearTilingFeatures found by calling 6123 flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as 6124 slink:VkImageViewCreateInfo::pname:format. 6125 * If Vulkan 1.3 is not supported and the 6126 `apiext:VK_KHR_format_feature_flags2` extension is not supported, and 6127 slink:VkImageViewCreateInfo::pname:image was created with 6128 ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format 6129 features_ is the union of the value of 6130 slink:VkFormatProperties::pname:linearTilingFeatures found by calling 6131 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 6132 slink:VkImageViewCreateInfo::pname:format, with: 6133 ** ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT if the 6134 format is a depth/stencil format and the image view features also 6135 contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. 6136 ** ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT if the format 6137 is one of the <<formats-without-shader-storage-format,extended storage 6138 formats>> and pname:shaderStorageImageReadWithoutFormat is enabled on 6139 the device. 6140 ** ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT if the 6141 format is one of the <<formats-without-shader-storage-format,extended 6142 storage formats>> and pname:shaderStorageImageWriteWithoutFormat is 6143 enabled on the device. 6144endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6145ifndef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6146 * If slink:VkImageViewCreateInfo::pname:image was created with 6147 ename:VK_IMAGE_TILING_OPTIMAL, 6148ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 6149 but without an 6150 <<memory-external-android-hardware-buffer-external-formats,Android 6151 hardware buffer external format>>, 6152endif::VK_ANDROID_external_memory_android_hardware_buffer[] 6153ifdef::VK_QNX_external_memory_screen_buffer[] 6154 or a <<memory-external-screen-buffer-external-formats,QNX Screen buffer 6155 external format>>, 6156endif::VK_QNX_external_memory_screen_buffer[] 6157 then the image view's set of _format features_ is the value of 6158 slink:VkFormatProperties::pname:optimalTilingFeatures found by calling 6159 flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as 6160 slink:VkImageViewCreateInfo::pname:format. 6161endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6162ifdef::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6163 * If Vulkan 1.3 is supported or the `apiext:VK_KHR_format_feature_flags2` 6164 extension is supported, and slink:VkImageViewCreateInfo::pname:image was 6165 created with ename:VK_IMAGE_TILING_OPTIMAL, 6166ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 6167 but without an 6168 <<memory-external-android-hardware-buffer-external-formats,Android 6169 hardware buffer external format>>, 6170endif::VK_ANDROID_external_memory_android_hardware_buffer[] 6171ifdef::VK_QNX_external_memory_screen_buffer[] 6172 or a <<memory-external-screen-buffer-external-formats,QNX Screen buffer 6173 external format>>, 6174endif::VK_QNX_external_memory_screen_buffer[] 6175 then the image view's set of _format features_ is the value of 6176 slink:VkFormatProperties::pname:optimalTilingFeatures or 6177 slink:VkFormatProperties3::pname:optimalTilingFeatures found by calling 6178 flink:vkGetPhysicalDeviceFormatProperties or 6179 flink:vkGetPhysicalDeviceImageFormatProperties2 on the same pname:format 6180 as slink:VkImageViewCreateInfo::pname:format. 6181 * If Vulkan 1.3 is not supported and the 6182 `apiext:VK_KHR_format_feature_flags2` extension is not supported, and 6183 slink:VkImageViewCreateInfo::pname:image was created with 6184 ename:VK_IMAGE_TILING_OPTIMAL, 6185ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 6186 but without an 6187 <<memory-external-android-hardware-buffer-external-formats,Android 6188 hardware buffer external format>>, 6189endif::VK_ANDROID_external_memory_android_hardware_buffer[] 6190ifdef::VK_QNX_external_memory_screen_buffer[] 6191 or a <<memory-external-screen-buffer-external-formats,QNX Screen buffer 6192 external format>>, 6193endif::VK_QNX_external_memory_screen_buffer[] 6194 then the image view's set of _format features_ is the union of the value 6195 of slink:VkFormatProperties::pname:optimalTilingFeatures found by 6196 calling flink:vkGetPhysicalDeviceFormatProperties on the same 6197 pname:format as slink:VkImageViewCreateInfo::pname:format, with: 6198 ** ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT if the 6199 format is a depth/stencil format and the image view features also 6200 contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT. 6201 ** ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT if the format 6202 is one of the <<formats-without-shader-storage-format,extended storage 6203 formats>> and pname:shaderStorageImageReadWithoutFormat is enabled on 6204 the device. 6205 ** ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT if the 6206 format is one of the <<formats-without-shader-storage-format,extended 6207 storage formats>> and pname:shaderStorageImageWriteWithoutFormat is 6208 enabled on the device. 6209endif::VK_VERSION_1_3,VK_KHR_format_feature_flags2[] 6210ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 6211 * If slink:VkImageViewCreateInfo::pname:image was created with an 6212 <<memory-external-android-hardware-buffer-external-formats,Android 6213 hardware buffer external format>>, then the image views's set of _format 6214 features_ is the value of 6215 slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures 6216 found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on 6217 the Android hardware buffer that was imported to the 6218 slink:VkDeviceMemory to which the 6219 slink:VkImageViewCreateInfo::pname:image is bound. 6220endif::VK_ANDROID_external_memory_android_hardware_buffer[] 6221ifdef::VK_QNX_external_memory_screen_buffer[] 6222 * If slink:VkImageViewCreateInfo::pname:image was created with a 6223 <<memory-external-screen-buffer-external-formats,QNX Screen buffer 6224 external format>>, then the image views's set of _format features_ is 6225 the value of 6226 slink:VkScreenBufferFormatPropertiesQNX::pname:formatFeatures found by 6227 calling flink:vkGetScreenBufferPropertiesQNX on the QNX Screen buffer 6228 that was imported to the slink:VkDeviceMemory to which the 6229 slink:VkImageViewCreateInfo::pname:image is bound. 6230endif::VK_QNX_external_memory_screen_buffer[] 6231ifdef::VK_FUCHSIA_buffer_collection[] 6232 * If slink:VkImageViewCreateInfo::pname:image was created with a chained 6233 slink:VkBufferCollectionImageCreateInfoFUCHSIA, then the image view's 6234 set of _format features_ is the value of 6235 slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found by 6236 calling flink:vkGetBufferCollectionPropertiesFUCHSIA on the buffer 6237 collection passed as 6238 slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection when 6239 the image was created. 6240endif::VK_FUCHSIA_buffer_collection[] 6241ifdef::VK_EXT_image_drm_format_modifier[] 6242 * If slink:VkImageViewCreateInfo::pname:image was created with 6243 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: 6244 ** The image's DRM format modifier is the value of 6245 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier 6246 found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. 6247 ** Let 6248 slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties 6249 be the array found by calling 6250 flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as 6251 slink:VkImageViewCreateInfo::pname:format. 6252 ** Let `VkDrmFormatModifierPropertiesEXT prop` be the array element whose 6253 pname:drmFormatModifier member is the value of the image's DRM format 6254 modifier. 6255 ** Then the image view's set of _format features_ is 6256 `prop`::pname:drmFormatModifierTilingFeatures. 6257endif::VK_EXT_image_drm_format_modifier[] 6258 6259ifdef::VK_EXT_image_view_min_lod[] 6260[open,refpage='VkImageViewMinLodCreateInfoEXT',desc='Structure describing the minimum LOD of an image view',type='structs'] 6261-- 6262The sname:VkImageViewMinLodCreateInfoEXT structure is defined as: 6263 6264include::{generated}/api/structs/VkImageViewMinLodCreateInfoEXT.adoc[] 6265 6266 * pname:sType is a elink:VkStructureType value identifying this structure. 6267 * pname:pNext is `NULL` or a pointer to a structure extending this 6268 structure. 6269 * pname:minLod is the value to clamp the minimum LOD accessible by this 6270 slink:VkImageView. 6271 6272If the pname:pNext chain includes a sname:VkImageViewMinLodCreateInfoEXT 6273structure, then that structure includes a parameter specifying a value to 6274clamp the minimum LOD value during <<textures-image-level-selection,Image 6275Level(s) Selection>>, <<textures-gather,Texel Gathering>> and 6276<<textures-integer-coordinate-operations,Integer Texel Coordinate 6277Operations>>. 6278 6279If the image view contains sname:VkImageViewMinLodCreateInfoEXT and it is 6280used as part of a sampling operation: 6281 6282[eq]#minLodFloat~imageView~ = pname:minLod# 6283 6284otherwise: 6285 6286[eq]#minLodFloat~imageView~ = 0.0# 6287 6288An integer variant of this parameter is also defined for sampling operations 6289which access integer mipmap levels: 6290 6291[eq]#minLodInteger~imageView~ = {lfloor}minLodFloat~imageView~{rfloor}# 6292 6293.Valid Usage 6294**** 6295 * [[VUID-VkImageViewMinLodCreateInfoEXT-minLod-06455]] 6296 If the <<features-minLod, pname:minLod>> feature is not enabled, 6297 pname:minLod must: be `0.0` 6298 * [[VUID-VkImageViewMinLodCreateInfoEXT-minLod-06456]] 6299 pname:minLod must: be less or equal to the index of the last mipmap 6300 level accessible to the view 6301**** 6302 6303include::{generated}/validity/structs/VkImageViewMinLodCreateInfoEXT.adoc[] 6304-- 6305endif::VK_EXT_image_view_min_lod[] 6306 6307 6308ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 6309[[resources-acceleration-structures]] 6310== Acceleration Structures 6311 6312[open,refpage='VkAccelerationStructureKHR',desc='Opaque handle to an acceleration structure object',type='handles'] 6313-- 6314:refpage: VkAccelerationStructureKHR 6315 6316Acceleration structures are opaque data structures that are built by the 6317implementation to more efficiently perform spatial queries on the provided 6318geometric data. 6319For this extension, an acceleration structure is either a top-level 6320acceleration structure containing a set of bottom-level acceleration 6321structures or a bottom-level acceleration structure containing either a set 6322of axis-aligned bounding boxes for custom geometry or a set of triangles. 6323 6324Each instance in the top-level acceleration structure contains a reference 6325to a bottom-level acceleration structure as well as an instance transform 6326plus information required to index into the shader bindings. 6327The top-level acceleration structure is what is bound to the acceleration 6328descriptor, for example to trace inside the shader in the ray tracing 6329pipeline. 6330 6331Acceleration structures are represented by sname:VkAccelerationStructureKHR 6332handles: 6333 6334include::{generated}/api/handles/VkAccelerationStructureKHR.adoc[] 6335-- 6336 6337ifdef::VK_NV_ray_tracing[] 6338[open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] 6339-- 6340:refpage: VkAccelerationStructureNV 6341 6342Acceleration structures for the `apiext:VK_NV_ray_tracing extension` are 6343represented by the similar sname:VkAccelerationStructureNV handles: 6344 6345include::{generated}/api/handles/VkAccelerationStructureNV.adoc[] 6346-- 6347 6348[open,refpage='vkCreateAccelerationStructureNV',desc='Create a new acceleration structure object',type='protos'] 6349-- 6350:refpage: vkCreateAccelerationStructureNV 6351 6352To create acceleration structures, call: 6353 6354include::{generated}/api/protos/vkCreateAccelerationStructureNV.adoc[] 6355 6356 * pname:device is the logical device that creates the buffer object. 6357 * pname:pCreateInfo is a pointer to a 6358 slink:VkAccelerationStructureCreateInfoNV structure containing 6359 parameters affecting creation of the acceleration structure. 6360 * pname:pAllocator controls host memory allocation as described in the 6361 <<memory-allocation, Memory Allocation>> chapter. 6362 * pname:pAccelerationStructure is a pointer to a 6363 slink:VkAccelerationStructureNV handle in which the resulting 6364 acceleration structure object is returned. 6365 6366Similarly to other objects in Vulkan, the acceleration structure creation 6367merely creates an object with a specific "`shape`" as specified by the 6368information in slink:VkAccelerationStructureInfoNV and pname:compactedSize 6369in pname:pCreateInfo. 6370 6371Once memory has been bound to the acceleration structure using 6372flink:vkBindAccelerationStructureMemoryNV, that memory is populated by calls 6373to flink:vkCmdBuildAccelerationStructureNV and 6374flink:vkCmdCopyAccelerationStructureNV. 6375 6376Acceleration structure creation uses the count and type information from the 6377geometries, but does not use the data references in the structures. 6378 6379include::{generated}/validity/protos/vkCreateAccelerationStructureNV.adoc[] 6380-- 6381 6382[open,refpage='VkAccelerationStructureCreateInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 6383-- 6384:refpage: VkAccelerationStructureCreateInfoNV 6385 6386The sname:VkAccelerationStructureCreateInfoNV structure is defined as: 6387 6388include::{generated}/api/structs/VkAccelerationStructureCreateInfoNV.adoc[] 6389 6390 * pname:sType is a elink:VkStructureType value identifying this structure. 6391 * pname:pNext is `NULL` or a pointer to a structure extending this 6392 structure. 6393 * pname:compactedSize is the size from the result of 6394 flink:vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration 6395 structure is going to be the target of a compacting copy. 6396 * pname:info is the slink:VkAccelerationStructureInfoNV structure 6397 specifying further parameters of the created acceleration structure. 6398 6399.Valid Usage 6400**** 6401 * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] 6402 If pname:compactedSize is not `0` then both pname:info.geometryCount and 6403 pname:info.instanceCount must: be `0` 6404**** 6405 6406include::{generated}/validity/structs/VkAccelerationStructureCreateInfoNV.adoc[] 6407-- 6408 6409[open,refpage='VkAccelerationStructureInfoNV',desc='Structure specifying the parameters of acceleration structure object',type='structs'] 6410-- 6411:refpage: VkAccelerationStructureInfoNV 6412 6413The sname:VkAccelerationStructureInfoNV structure is defined as: 6414 6415include::{generated}/api/structs/VkAccelerationStructureInfoNV.adoc[] 6416 6417 * pname:sType is a elink:VkStructureType value identifying this structure. 6418 * pname:pNext is `NULL` or a pointer to a structure extending this 6419 structure. 6420 * pname:type is a elink:VkAccelerationStructureTypeNV value specifying the 6421 type of acceleration structure that will be created. 6422 * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsNV 6423 specifying additional parameters of the acceleration structure. 6424 * pname:instanceCount specifies the number of instances that will be in 6425 the new acceleration structure. 6426 * pname:geometryCount specifies the number of geometries that will be in 6427 the new acceleration structure. 6428 * pname:pGeometries is a pointer to an array of pname:geometryCount 6429 slink:VkGeometryNV structures containing the scene data being passed 6430 into the acceleration structure. 6431 6432sname:VkAccelerationStructureInfoNV contains information that is used both 6433for acceleration structure creation with 6434flink:vkCreateAccelerationStructureNV and in combination with the actual 6435geometric data to build the acceleration structure with 6436flink:vkCmdBuildAccelerationStructureNV. 6437 6438.Valid Usage 6439**** 6440 * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] 6441 pname:geometryCount must: be less than or equal to 6442 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount 6443 * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] 6444 pname:instanceCount must: be less than or equal to 6445 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount 6446 * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] 6447 The total number of triangles in all geometries must: be less than or 6448 equal to 6449 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount 6450 * [[VUID-VkAccelerationStructureInfoNV-type-02425]] 6451 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then 6452 pname:geometryCount must: be `0` 6453 * [[VUID-VkAccelerationStructureInfoNV-type-02426]] 6454 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV 6455 then pname:instanceCount must: be `0` 6456 * [[VUID-VkAccelerationStructureInfoNV-type-02786]] 6457 If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV 6458 then the pname:geometryType member of each geometry in pname:pGeometries 6459 must: be the same 6460ifdef::VK_KHR_acceleration_structure[] 6461 * [[VUID-VkAccelerationStructureInfoNV-type-04623]] 6462 pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 6463endif::VK_KHR_acceleration_structure[] 6464 * [[VUID-VkAccelerationStructureInfoNV-flags-02592]] 6465 If pname:flags has the 6466 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, 6467 then it must: not have the 6468 ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set 6469 * [[VUID-VkAccelerationStructureInfoNV-scratch-02781]] 6470 pname:scratch must: have been created with 6471 ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag 6472 * [[VUID-VkAccelerationStructureInfoNV-instanceData-02782]] 6473 If pname:instanceData is not dlink:VK_NULL_HANDLE, pname:instanceData 6474 must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV 6475 usage flag 6476**** 6477 6478include::{generated}/validity/structs/VkAccelerationStructureInfoNV.adoc[] 6479-- 6480endif::VK_NV_ray_tracing[] 6481 6482ifdef::VK_KHR_acceleration_structure[] 6483[open,refpage='vkCreateAccelerationStructureKHR',desc='Create a new acceleration structure object',type='protos'] 6484-- 6485:refpage: vkCreateAccelerationStructureKHR 6486 6487To create an acceleration structure, call: 6488 6489include::{generated}/api/protos/vkCreateAccelerationStructureKHR.adoc[] 6490 6491 * pname:device is the logical device that creates the acceleration 6492 structure object. 6493 * pname:pCreateInfo is a pointer to a 6494 slink:VkAccelerationStructureCreateInfoKHR structure containing 6495 parameters affecting creation of the acceleration structure. 6496 * pname:pAllocator controls host memory allocation as described in the 6497 <<memory-allocation, Memory Allocation>> chapter. 6498 * pname:pAccelerationStructure is a pointer to a 6499 sname:VkAccelerationStructureKHR handle in which the resulting 6500 acceleration structure object is returned. 6501 6502Similar to other objects in Vulkan, the acceleration structure creation 6503merely creates an object with a specific "`shape`". 6504The type and quantity of geometry that can be built into an acceleration 6505structure is determined by the parameters of 6506slink:VkAccelerationStructureCreateInfoKHR. 6507 6508The acceleration structure data is stored in the object referred to by 6509sname:VkAccelerationStructureCreateInfoKHR::pname:buffer. 6510Once memory has been bound to that buffer, it must: be populated by 6511acceleration structure build or acceleration structure copy commands such as 6512flink:vkCmdBuildAccelerationStructuresKHR, 6513flink:vkBuildAccelerationStructuresKHR, 6514flink:vkCmdCopyAccelerationStructureKHR, and 6515flink:vkCopyAccelerationStructureKHR. 6516 6517[NOTE] 6518.Note 6519==== 6520The expected usage for a trace capture/replay tool is that it will serialize 6521and later deserialize the acceleration structure data using acceleration 6522structure copy commands. 6523During capture the tool will use 6524flink:vkCopyAccelerationStructureToMemoryKHR or 6525flink:vkCmdCopyAccelerationStructureToMemoryKHR with a pname:mode of 6526ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR, and 6527flink:vkCopyMemoryToAccelerationStructureKHR or 6528flink:vkCmdCopyMemoryToAccelerationStructureKHR with a pname:mode of 6529ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR during replay. 6530==== 6531 6532The input buffers passed to acceleration structure build commands will be 6533referenced by the implementation for the duration of the command. 6534After the command completes, the acceleration structure may: hold a 6535reference to any acceleration structure specified by an active instance 6536contained therein. 6537Apart from this referencing, acceleration structures must: be fully 6538self-contained. 6539The application can: reuse or free any memory which was used by the command 6540as an input or as scratch without affecting the results of ray traversal. 6541 6542.Valid Usage 6543**** 6544 * [[VUID-vkCreateAccelerationStructureKHR-accelerationStructure-03611]] 6545 The <<features-accelerationStructure, 6546 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 6547 feature must: be enabled 6548 * [[VUID-vkCreateAccelerationStructureKHR-deviceAddress-03488]] 6549 If slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress is 6550 not zero, the <<features-accelerationStructureCaptureReplay, 6551 pname:accelerationStructureCaptureReplay>> feature must: be enabled 6552 * [[VUID-vkCreateAccelerationStructureKHR-device-03489]] 6553 If pname:device was created with multiple physical devices, then the 6554 <<features-bufferDeviceAddressMultiDevice, 6555 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6556**** 6557 6558include::{generated}/validity/protos/vkCreateAccelerationStructureKHR.adoc[] 6559-- 6560 6561[open,refpage='VkAccelerationStructureCreateInfoKHR',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 6562-- 6563:refpage: VkAccelerationStructureCreateInfoKHR 6564 6565The sname:VkAccelerationStructureCreateInfoKHR structure is defined as: 6566 6567include::{generated}/api/structs/VkAccelerationStructureCreateInfoKHR.adoc[] 6568 6569 * pname:sType is a elink:VkStructureType value identifying this structure. 6570 * pname:pNext is `NULL` or a pointer to a structure extending this 6571 structure. 6572 * pname:createFlags is a bitmask of 6573 elink:VkAccelerationStructureCreateFlagBitsKHR specifying additional 6574 creation parameters of the acceleration structure. 6575 * pname:buffer is the buffer on which the acceleration structure will be 6576 stored. 6577 * pname:offset is an offset in bytes from the base address of the buffer 6578 at which the acceleration structure will be stored, and must: be a 6579 multiple of `256`. 6580 * pname:size is the size required for the acceleration structure. 6581 * pname:type is a elink:VkAccelerationStructureTypeKHR value specifying 6582 the type of acceleration structure that will be created. 6583 * pname:deviceAddress is the device address requested for the acceleration 6584 structure if the <<features-accelerationStructureCaptureReplay, 6585 pname:accelerationStructureCaptureReplay>> feature is being used. 6586 If pname:deviceAddress is zero, no specific address is requested. 6587 6588Applications should: avoid creating acceleration structures with 6589application-provided addresses and implementation-provided addresses in the 6590same process, to reduce the likelihood of 6591ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors. 6592 6593[NOTE] 6594.Note 6595==== 6596The expected usage for this is that a trace capture/replay tool will add the 6597ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers 6598that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add 6599ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as 6600storage for an acceleration structure where pname:deviceAddress is not zero. 6601This also means that the tool will need to add 6602ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow 6603the flag to be set where the application may not have otherwise required it. 6604During capture the tool will save the queried opaque device addresses in the 6605trace. 6606During replay, the buffers will be created specifying the original address 6607so any address values stored in the trace data will remain valid. 6608 6609Implementations are expected to separate such buffers in the GPU address 6610space so normal allocations will avoid using these addresses. 6611Apps/tools should avoid mixing app-provided and implementation-provided 6612addresses for buffers created with 6613ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address 6614space allocation conflicts. 6615==== 6616 6617 6618Applications should: create an acceleration structure with a specific 6619elink:VkAccelerationStructureTypeKHR other than 6620ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. 6621 6622[NOTE] 6623.Note 6624==== 6625ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is intended to be used by 6626API translation layers. 6627This can be used at acceleration structure creation time in cases where the 6628actual acceleration structure type (top or bottom) is not yet known. 6629The actual acceleration structure type must be specified as 6630ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or 6631ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR when the build is 6632performed. 6633==== 6634 6635If the acceleration structure will be the target of a build operation, the 6636required size for an acceleration structure can: be queried with 6637flink:vkGetAccelerationStructureBuildSizesKHR. 6638If the acceleration structure is going to be the target of a compacting 6639copy, flink:vkCmdWriteAccelerationStructuresPropertiesKHR or 6640flink:vkWriteAccelerationStructuresPropertiesKHR can: be used to obtain the 6641compacted size required. 6642 6643ifdef::VK_NV_ray_tracing_motion_blur[] 6644If the acceleration structure will be the target of a build operation with 6645ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must: include 6646ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in pname:createFlags 6647and include slink:VkAccelerationStructureMotionInfoNV as an extension 6648structure in pname:pNext with the number of instances as metadata for the 6649object. 6650endif::VK_NV_ray_tracing_motion_blur[] 6651 6652.Valid Usage 6653**** 6654 * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612]] 6655 If pname:deviceAddress is not zero, pname:createFlags must: include 6656 ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR 6657 * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09488]] 6658 If pname:deviceAddress is not zero, it must: have been retrieved from an 6659 identically created acceleration structure, except for pname:buffer and 6660 pname:deviceAddress 6661 * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09489]] 6662 If pname:deviceAddress is not zero, pname:buffer must: have been created 6663 identically to the pname:buffer used to create the acceleration 6664 structure from which pname:deviceAddress was retrieved, except for 6665 slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 6666 * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09490]] 6667 If pname:deviceAddress is not zero, pname:buffer must: have been created 6668 with a 6669 slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 6670 that was retrieved from flink:vkGetBufferOpaqueCaptureAddress for the 6671 pname:buffer that was used to create the acceleration structure from 6672 which pname:deviceAddress was retrieved 6673 * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613]] 6674 If pname:createFlags includes 6675 ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, 6676 slink:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureCaptureReplay 6677 must: be ename:VK_TRUE 6678 * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614]] 6679 pname:buffer must: have been created with a pname:usage value containing 6680 ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR 6681 * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615]] 6682 pname:buffer must: not have been created with 6683 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT 6684 * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03616]] 6685 The sum of pname:offset and pname:size must: be less than the size of 6686 pname:buffer 6687 * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03734]] 6688 pname:offset must: be a multiple of `256` bytes 6689ifdef::VK_NV_ray_tracing_motion_blur[] 6690 * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-04954]] 6691 If ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV is set in 6692 pname:createFlags and pname:type is 6693 ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, one member of the 6694 pname:pNext chain must: be a pointer to a valid instance of 6695 slink:VkAccelerationStructureMotionInfoNV 6696 * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-04955]] 6697 If any geometry includes 6698 sname:VkAccelerationStructureGeometryMotionTrianglesDataNV then 6699 pname:createFlags must: contain 6700 ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV 6701endif::VK_NV_ray_tracing_motion_blur[] 6702ifdef::VK_EXT_descriptor_buffer[] 6703 * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-08108]] 6704 If pname:createFlags includes 6705 ename:VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, 6706 the <<features-descriptorBufferCaptureReplay, 6707 pname:descriptorBufferCaptureReplay>> feature must: be enabled 6708 * [[VUID-VkAccelerationStructureCreateInfoKHR-pNext-08109]] 6709 If the pname:pNext chain includes a 6710 slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, 6711 pname:createFlags must: contain 6712 ename:VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 6713endif::VK_EXT_descriptor_buffer[] 6714**** 6715 6716include::{generated}/validity/structs/VkAccelerationStructureCreateInfoKHR.adoc[] 6717-- 6718 6719ifdef::VK_NV_ray_tracing_motion_blur[] 6720[open,refpage='VkAccelerationStructureMotionInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] 6721-- 6722:refpage: VkAccelerationStructureMotionInfoNV 6723 6724The sname:VkAccelerationStructureMotionInfoNV structure is defined as: 6725 6726include::{generated}/api/structs/VkAccelerationStructureMotionInfoNV.adoc[] 6727 6728 * pname:sType is a elink:VkStructureType value identifying this structure. 6729 * pname:pNext is `NULL` or a pointer to a structure extending this 6730 structure. 6731 * pname:maxInstances is the maximum number of instances that may: be used 6732 in the motion top-level acceleration structure. 6733 * pname:flags is 0 and reserved for future use. 6734 6735include::{generated}/validity/structs/VkAccelerationStructureMotionInfoNV.adoc[] 6736-- 6737 6738[open,refpage='VkAccelerationStructureMotionInfoFlagsNV',desc='Reserved for future use',type='flags'] 6739-- 6740include::{generated}/api/flags/VkAccelerationStructureMotionInfoFlagsNV.adoc[] 6741 6742tname:VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting 6743a mask, but is currently reserved for future use. 6744-- 6745endif::VK_NV_ray_tracing_motion_blur[] 6746 6747[open,refpage='vkGetAccelerationStructureBuildSizesKHR',desc='Retrieve the required size for an acceleration structure',type='protos'] 6748-- 6749:refpage: vkGetAccelerationStructureBuildSizesKHR 6750 6751To get the build sizes for an acceleration structure, call: 6752 6753include::{generated}/api/protos/vkGetAccelerationStructureBuildSizesKHR.adoc[] 6754 6755 * pname:device is the logical device that will be used for creating the 6756 acceleration structure. 6757 * pname:buildType defines whether host or device operations (or both) are 6758 being queried for. 6759 * pname:pBuildInfo is a pointer to a 6760 slink:VkAccelerationStructureBuildGeometryInfoKHR structure describing 6761 parameters of a build operation. 6762 * pname:pMaxPrimitiveCounts is a pointer to an array of 6763 pname:pBuildInfo->geometryCount code:uint32_t values defining the number 6764 of primitives built into each geometry. 6765 * pname:pSizeInfo is a pointer to a 6766 slink:VkAccelerationStructureBuildSizesInfoKHR structure which returns 6767 the size required for an acceleration structure and the sizes required 6768 for the scratch buffers, given the build parameters. 6769 6770The pname:srcAccelerationStructure, pname:dstAccelerationStructure, and 6771pname:mode members of pname:pBuildInfo are ignored. 6772Any slink:VkDeviceOrHostAddressKHR or slink:VkDeviceOrHostAddressConstKHR 6773members of pname:pBuildInfo are ignored by this command, except that the 6774pname:hostAddress member of 6775slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData 6776will be examined to check if it is `NULL`. 6777 6778An acceleration structure created with the pname:accelerationStructureSize 6779returned by this command supports any build or update with a 6780slink:VkAccelerationStructureBuildGeometryInfoKHR structure and array of 6781slink:VkAccelerationStructureBuildRangeInfoKHR structures subject to the 6782following properties: 6783 6784 * The build command is a host build command, and pname:buildType is 6785 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or 6786 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 6787 * The build command is a device build command, and pname:buildType is 6788 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or 6789 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 6790 * For slink:VkAccelerationStructureBuildGeometryInfoKHR: 6791 ** Its pname:type, and pname:flags members are equal to 6792 pname:pBuildInfo->type and pname:pBuildInfo->flags, respectively. 6793 ** pname:geometryCount is less than or equal to 6794 pname:pBuildInfo->geometryCount. 6795 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6796 given index, its pname:geometryType member is equal to 6797 pname:pBuildInfo->geometryType. 6798 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6799 given index, its pname:flags member is equal to the corresponding 6800 member of the same element in pname:pBuildInfo. 6801 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6802 given index, with a pname:geometryType member equal to 6803 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:vertexFormat and 6804 pname:indexType members of pname:geometry.triangles are equal to the 6805 corresponding members of the same element in pname:pBuildInfo. 6806 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6807 given index, with a pname:geometryType member equal to 6808 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:maxVertex member of 6809 pname:geometry.triangles is less than or equal to the corresponding 6810 member of the same element in pname:pBuildInfo. 6811 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6812 given index, with a pname:geometryType member equal to 6813 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the 6814 pname:transformData member of pname:geometry.triangles is not `NULL`, 6815 the corresponding pname:transformData.hostAddress parameter in 6816 pname:pBuildInfo is not `NULL`. 6817 * For each slink:VkAccelerationStructureBuildRangeInfoKHR corresponding to 6818 the slink:VkAccelerationStructureBuildGeometryInfoKHR: 6819 ** Its pname:primitiveCount member is less than or equal to the 6820 corresponding element of pname:pMaxPrimitiveCounts. 6821ifdef::VK_EXT_opacity_micromap[] 6822 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6823 given index, with a pname:geometryType member equal to 6824 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the pname:pNext chain contains 6825 slink:VkAccelerationStructureTrianglesOpacityMicromapEXT the 6826 corresponding member of pname:pBuildInfo also contains 6827 slink:VkAccelerationStructureTrianglesOpacityMicromapEXT and with an 6828 equivalent pname:micromap. 6829endif::VK_EXT_opacity_micromap[] 6830ifdef::VK_NV_displacement_micromap[] 6831 ** For each element of either pname:pGeometries or pname:ppGeometries at a 6832 given index, with a pname:geometryType member equal to 6833 ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the pname:pNext chain contains 6834 slink:VkAccelerationStructureTrianglesDisplacementMicromapNV the 6835 corresponding member of pname:pBuildInfo also contains 6836 slink:VkAccelerationStructureTrianglesDisplacementMicromapNV and with 6837 an equivalent pname:micromap. 6838endif::VK_NV_displacement_micromap[] 6839 6840Similarly, the pname:updateScratchSize value will support any build command 6841specifying the ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR 6842pname:mode under the above conditions, and the pname:buildScratchSize value 6843will support any build command specifying the 6844ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR pname:mode under the 6845above conditions. 6846 6847.Valid Usage 6848**** 6849 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-accelerationStructure-08933]] 6850 The <<features-accelerationStructure, 6851 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 6852 feature must: be enabled 6853 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-device-03618]] 6854 If pname:device was created with multiple physical devices, then the 6855 <<features-bufferDeviceAddressMultiDevice, 6856 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6857 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03619]] 6858 If pname:pBuildInfo->geometryCount is not `0`, pname:pMaxPrimitiveCounts 6859 must: be a valid pointer to an array of pname:pBuildInfo->geometryCount 6860 code:uint32_t values 6861 * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03785]] 6862 If pname:pBuildInfo->pGeometries or pname:pBuildInfo->ppGeometries has a 6863 pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each 6864 pname:pMaxPrimitiveCounts[i] must: be less than or equal to 6865 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxInstanceCount 6866**** 6867 6868include::{generated}/validity/protos/vkGetAccelerationStructureBuildSizesKHR.adoc[] 6869-- 6870 6871[open,refpage='VkAccelerationStructureBuildSizesInfoKHR',desc='Structure specifying build sizes for an acceleration structure',type='structs'] 6872-- 6873:refpage: VkAccelerationStructureBuildSizesInfoKHR 6874 6875The sname:VkAccelerationStructureBuildSizesInfoKHR structure describes the 6876required build sizes for an acceleration structure and scratch buffers and 6877is defined as: 6878 6879include::{generated}/api/structs/VkAccelerationStructureBuildSizesInfoKHR.adoc[] 6880 6881 * pname:sType is a elink:VkStructureType value identifying this structure. 6882 * pname:pNext is `NULL` or a pointer to a structure extending this 6883 structure. 6884 * pname:accelerationStructureSize is the size in bytes required in a 6885 slink:VkAccelerationStructureKHR for a build or update operation. 6886 * pname:updateScratchSize is the size in bytes required in a scratch 6887 buffer for an update operation. 6888 * pname:buildScratchSize is the size in bytes required in a scratch buffer 6889 for a build operation. 6890 6891include::{generated}/validity/structs/VkAccelerationStructureBuildSizesInfoKHR.adoc[] 6892-- 6893endif::VK_KHR_acceleration_structure[] 6894 6895[open,refpage='VkAccelerationStructureTypeKHR',desc='Type of acceleration structure',type='enums',alias='VkAccelerationStructureTypeNV'] 6896-- 6897:refpage: VkAccelerationStructureTypeKHR 6898 6899Values which can: be set in 6900ifdef::VK_KHR_acceleration_structure[] 6901slink:VkAccelerationStructureCreateInfoKHR::pname:type 6902endif::VK_KHR_acceleration_structure[] 6903ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 6904ifdef::VK_NV_ray_tracing[] 6905slink:VkAccelerationStructureInfoNV::pname:type 6906endif::VK_NV_ray_tracing[] 6907specifying the type of acceleration structure, are: 6908 6909include::{generated}/api/enums/VkAccelerationStructureTypeKHR.adoc[] 6910 6911ifdef::VK_NV_ray_tracing[] 6912or the equivalent 6913 6914include::{generated}/api/enums/VkAccelerationStructureTypeNV.adoc[] 6915endif::VK_NV_ray_tracing[] 6916 6917 * ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR is a top-level 6918 acceleration structure containing instance data referring to 6919 bottom-level acceleration structures. 6920 * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR is a bottom-level 6921 acceleration structure containing the AABBs or geometry to be 6922 intersected. 6923 * ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is an acceleration 6924 structure whose type is determined at build time used for special 6925 circumstances. 6926 In these cases, the acceleration structure type is not known at creation 6927 time, but must: be specified at build time as either top or bottom. 6928-- 6929 6930ifdef::VK_KHR_acceleration_structure[] 6931[open,refpage='VkAccelerationStructureCreateFlagBitsKHR',desc='Bitmask specifying additional creation parameters for acceleration structure',type='enums'] 6932-- 6933Bits which can: be set in 6934slink:VkAccelerationStructureCreateInfoKHR::pname:createFlags, specifying 6935additional creation parameters for acceleration structures, are: 6936 6937include::{generated}/api/enums/VkAccelerationStructureCreateFlagBitsKHR.adoc[] 6938 6939 * ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR 6940 specifies that the acceleration structure's address can: be saved and 6941 reused on a subsequent run. 6942ifdef::VK_EXT_descriptor_buffer[] 6943 * ename:VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 6944 specifies that the acceleration structure can: be used with descriptor 6945 buffers when capturing and replaying (e.g. for trace capture and 6946 replay), see slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more 6947 detail. 6948endif::VK_EXT_descriptor_buffer[] 6949-- 6950 6951[open,refpage='VkAccelerationStructureCreateFlagsKHR',desc='Bitmask of VkAccelerationStructureCreateFlagBitsKHR',type='flags'] 6952-- 6953include::{generated}/api/flags/VkAccelerationStructureCreateFlagsKHR.adoc[] 6954 6955tname:VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a 6956mask of zero or more elink:VkAccelerationStructureCreateFlagBitsKHR. 6957-- 6958endif::VK_KHR_acceleration_structure[] 6959 6960[open,refpage='VkBuildAccelerationStructureFlagBitsKHR',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums',alias='VkBuildAccelerationStructureFlagBitsNV'] 6961-- 6962:refpage: VkBuildAccelerationStructureFlagBitsKHR 6963 6964Bits which can: be set in 6965ifdef::VK_KHR_acceleration_structure[] 6966slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:flags 6967endif::VK_KHR_acceleration_structure[] 6968ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 6969ifdef::VK_NV_ray_tracing[] 6970slink:VkAccelerationStructureInfoNV::pname:flags 6971endif::VK_NV_ray_tracing[] 6972specifying additional parameters for acceleration structure builds, are: 6973 6974include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsKHR.adoc[] 6975 6976ifdef::VK_NV_ray_tracing[] 6977or the equivalent 6978 6979include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsNV.adoc[] 6980endif::VK_NV_ray_tracing[] 6981 6982 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR indicates 6983 that the specified acceleration structure can: be updated with 6984ifdef::VK_KHR_acceleration_structure[] 6985 a pname:mode of ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR in 6986 slink:VkAccelerationStructureBuildGeometryInfoKHR 6987endif::VK_KHR_acceleration_structure[] 6988ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 6989ifdef::VK_NV_ray_tracing[] 6990 an pname:update of ename:VK_TRUE in 6991 flink:vkCmdBuildAccelerationStructureNV 6992endif::VK_NV_ray_tracing[] 6993 . 6994 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR indicates 6995 that the specified acceleration structure can: act as the source for a 6996 copy acceleration structure command with pname:mode of 6997 ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR to produce a 6998 compacted acceleration structure. 6999 * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR 7000 indicates that the given acceleration structure build should: prioritize 7001 trace performance over build time. 7002 * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR 7003 indicates that the given acceleration structure build should: prioritize 7004 build time over trace performance. 7005 * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR indicates that 7006 this acceleration structure should: minimize the size of the scratch 7007 memory and the final result acceleration structure, potentially at the 7008 expense of build time or trace performance. 7009ifdef::VK_EXT_opacity_micromap[] 7010 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_EXT 7011 indicates that the opacity micromaps associated with the specified 7012 acceleration structure may: change with an acceleration structure 7013 update. 7014 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_EXT 7015 indicates that the data of the opacity micromaps associated with the 7016 specified acceleration structure may: change with an acceleration 7017 structure update. 7018 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_EXT 7019 indicates that the specified acceleration structure may: be referenced 7020 in an instance with 7021 ename:VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_EXT set. 7022endif::VK_EXT_opacity_micromap[] 7023ifdef::VK_KHR_ray_tracing_position_fetch[] 7024 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DATA_ACCESS_KHR indicates 7025 that the specified acceleration structure can: be used when fetching the 7026 vertex positions of a hit triangle. 7027endif::VK_KHR_ray_tracing_position_fetch[] 7028ifdef::VK_NV_displacement_micromap[] 7029 * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISPLACEMENT_MICROMAP_UPDATE_NV 7030 indicates that the displacement micromaps associated with the specified 7031 acceleration structure may: change with an acceleration structure 7032 update. 7033endif::VK_NV_displacement_micromap[] 7034 7035[NOTE] 7036.Note 7037==== 7038ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and 7039ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR may: take 7040more time and memory than a normal build, and so should: only be used when 7041those features are needed. 7042==== 7043-- 7044 7045[open,refpage='VkBuildAccelerationStructureFlagsKHR',desc='Bitmask of VkBuildAccelerationStructureFlagBitsKHR',type='flags',alias='VkBuildAccelerationStructureFlagsNV'] 7046-- 7047:refpage: VkBuildAccelerationStructureFlagsKHR 7048 7049include::{generated}/api/flags/VkBuildAccelerationStructureFlagsKHR.adoc[] 7050 7051ifdef::VK_NV_ray_tracing[] 7052or the equivalent 7053 7054include::{generated}/api/flags/VkBuildAccelerationStructureFlagsNV.adoc[] 7055endif::VK_NV_ray_tracing[] 7056 7057tname:VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a 7058mask of zero or more elink:VkBuildAccelerationStructureFlagBitsKHR. 7059-- 7060 7061ifdef::VK_NV_ray_tracing[] 7062[open,refpage='VkGeometryNV',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] 7063-- 7064:refpage: VkGeometryNV 7065 7066The sname:VkGeometryNV structure describes geometry in a bottom-level 7067acceleration structure and is defined as: 7068 7069include::{generated}/api/structs/VkGeometryNV.adoc[] 7070 7071 * pname:sType is a elink:VkStructureType value identifying this structure. 7072 * pname:pNext is `NULL` or a pointer to a structure extending this 7073 structure. 7074 * pname:geometryType specifies the elink:VkGeometryTypeKHR which this 7075 geometry refers to. 7076 * pname:geometry contains the geometry data as described in 7077 slink:VkGeometryDataNV. 7078 * pname:flags has elink:VkGeometryFlagBitsKHR describing options for this 7079 geometry. 7080 7081.Valid Usage 7082**** 7083 * [[VUID-VkGeometryNV-geometryType-03503]] 7084 pname:geometryType must: be ename:VK_GEOMETRY_TYPE_TRIANGLES_NV or 7085 ename:VK_GEOMETRY_TYPE_AABBS_NV 7086**** 7087 7088include::{generated}/validity/structs/VkGeometryNV.adoc[] 7089-- 7090endif::VK_NV_ray_tracing[] 7091 7092[open,refpage='VkGeometryTypeKHR',desc='Enum specifying which type of geometry is provided',type='enums',alias='VkGeometryTypeNV'] 7093-- 7094:refpage: VkGeometryTypeKHR 7095 7096Geometry types are specified by elink:VkGeometryTypeKHR, which takes values: 7097 7098include::{generated}/api/enums/VkGeometryTypeKHR.adoc[] 7099 7100ifdef::VK_NV_ray_tracing[] 7101or the equivalent 7102 7103include::{generated}/api/enums/VkGeometryTypeNV.adoc[] 7104endif::VK_NV_ray_tracing[] 7105 7106 * ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR specifies a geometry type 7107 consisting of triangles. 7108 * ename:VK_GEOMETRY_TYPE_AABBS_KHR specifies a geometry type consisting of 7109 axis-aligned bounding boxes. 7110ifdef::VK_KHR_acceleration_structure[] 7111 * ename:VK_GEOMETRY_TYPE_INSTANCES_KHR specifies a geometry type 7112 consisting of acceleration structure instances. 7113endif::VK_KHR_acceleration_structure[] 7114-- 7115 7116[open,refpage='VkGeometryFlagBitsKHR',desc='Bitmask specifying additional parameters for a geometry',type='enums',alias='VkGeometryFlagBitsNV'] 7117-- 7118:refpage: VkGeometryFlagBitsKHR 7119 7120Bits specifying additional parameters for geometries in acceleration 7121structure builds, are: 7122 7123include::{generated}/api/enums/VkGeometryFlagBitsKHR.adoc[] 7124 7125ifdef::VK_NV_ray_tracing[] 7126or the equivalent 7127 7128include::{generated}/api/enums/VkGeometryFlagBitsNV.adoc[] 7129endif::VK_NV_ray_tracing[] 7130 7131 * ename:VK_GEOMETRY_OPAQUE_BIT_KHR indicates that this geometry does not 7132 invoke the any-hit shaders even if present in a hit group. 7133 * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR indicates that 7134 the implementation must: only call the any-hit shader a single time for 7135 each primitive in this geometry. 7136 If this bit is absent an implementation may: invoke the any-hit shader 7137 more than once for this geometry. 7138-- 7139 7140[open,refpage='VkGeometryFlagsKHR',desc='Bitmask of VkGeometryFlagBitsKHR',type='flags',alias='VkGeometryFlagsNV'] 7141-- 7142:refpage: VkGeometryFlagsKHR 7143 7144include::{generated}/api/flags/VkGeometryFlagsKHR.adoc[] 7145 7146ifdef::VK_NV_ray_tracing[] 7147or the equivalent 7148 7149include::{generated}/api/flags/VkGeometryFlagsNV.adoc[] 7150endif::VK_NV_ray_tracing[] 7151 7152tname:VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or 7153more elink:VkGeometryFlagBitsKHR. 7154-- 7155 7156ifdef::VK_NV_ray_tracing[] 7157[open,refpage='VkGeometryDataNV',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] 7158-- 7159:refpage: VkGeometryDataNV 7160 7161The sname:VkGeometryDataNV structure specifies geometry in a bottom-level 7162acceleration structure and is defined as: 7163 7164include::{generated}/api/structs/VkGeometryDataNV.adoc[] 7165 7166 * pname:triangles contains triangle data if 7167 slink:VkGeometryNV::pname:geometryType is 7168 ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. 7169 * pname:aabbs contains axis-aligned bounding box data if 7170 slink:VkGeometryNV::pname:geometryType is 7171 ename:VK_GEOMETRY_TYPE_AABBS_NV. 7172 7173include::{generated}/validity/structs/VkGeometryDataNV.adoc[] 7174-- 7175 7176[open,refpage='VkGeometryTrianglesNV',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] 7177-- 7178:refpage: VkGeometryTrianglesNV 7179 7180The sname:VkGeometryTrianglesNV structure specifies triangle geometry in a 7181bottom-level acceleration structure and is defined as: 7182 7183include::{generated}/api/structs/VkGeometryTrianglesNV.adoc[] 7184 7185 * pname:sType is a elink:VkStructureType value identifying this structure. 7186 * pname:pNext is `NULL` or a pointer to a structure extending this 7187 structure. 7188 * pname:vertexData is the buffer containing vertex data for this geometry. 7189 * pname:vertexOffset is the offset in bytes within pname:vertexData 7190 containing vertex data for this geometry. 7191 * pname:vertexCount is the number of valid vertices. 7192 * pname:vertexStride is the stride in bytes between each vertex. 7193 * pname:vertexFormat is a elink:VkFormat describing the format of each 7194 vertex element. 7195 * pname:indexData is the buffer containing index data for this geometry. 7196 * pname:indexOffset is the offset in bytes within pname:indexData 7197 containing index data for this geometry. 7198 * pname:indexCount is the number of indices to include in this geometry. 7199 * pname:indexType is a elink:VkIndexType describing the format of each 7200 index. 7201 * pname:transformData is an optional buffer containing an 7202 slink:VkTransformMatrixNV structure defining a transformation to be 7203 applied to this geometry. 7204 * pname:transformOffset is the offset in bytes in pname:transformData of 7205 the transform information described above. 7206 7207If pname:indexType is ename:VK_INDEX_TYPE_NONE_NV, then this structure 7208describes a set of triangles determined by pname:vertexCount. 7209Otherwise, this structure describes a set of indexed triangles determined by 7210pname:indexCount. 7211 7212.Valid Usage 7213**** 7214 * [[VUID-VkGeometryTrianglesNV-vertexOffset-02428]] 7215 pname:vertexOffset must: be less than the size of pname:vertexData 7216 * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] 7217 pname:vertexOffset must: be a multiple of the component size of 7218 pname:vertexFormat 7219 * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] 7220 pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, 7221 ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, 7222 ename:VK_FORMAT_R16G16_SFLOAT, ename:VK_FORMAT_R16G16_SNORM, or 7223 ename:VK_FORMAT_R16G16B16_SNORM 7224 * [[VUID-VkGeometryTrianglesNV-vertexStride-03818]] 7225 pname:vertexStride must: be less than or equal to [eq]#2^32^-1# 7226 * [[VUID-VkGeometryTrianglesNV-indexOffset-02431]] 7227 pname:indexOffset must: be less than the size of pname:indexData 7228 * [[VUID-VkGeometryTrianglesNV-indexOffset-02432]] 7229 pname:indexOffset must: be a multiple of the element size of 7230 pname:indexType 7231 * [[VUID-VkGeometryTrianglesNV-indexType-02433]] 7232 pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, 7233 ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_NV 7234 * [[VUID-VkGeometryTrianglesNV-indexData-02434]] 7235 pname:indexData must: be dlink:VK_NULL_HANDLE if pname:indexType is 7236 ename:VK_INDEX_TYPE_NONE_NV 7237 * [[VUID-VkGeometryTrianglesNV-indexData-02435]] 7238 pname:indexData must: be a valid sname:VkBuffer handle if 7239 pname:indexType is not ename:VK_INDEX_TYPE_NONE_NV 7240 * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] 7241 pname:indexCount must: be `0` if pname:indexType is 7242 ename:VK_INDEX_TYPE_NONE_NV 7243 * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] 7244 pname:transformOffset must: be less than the size of pname:transformData 7245 * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] 7246 pname:transformOffset must: be a multiple of `16` 7247**** 7248 7249include::{generated}/validity/structs/VkGeometryTrianglesNV.adoc[] 7250-- 7251 7252[open,refpage='VkGeometryAABBNV',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] 7253-- 7254:refpage: VkGeometryAABBNV 7255 7256The sname:VkGeometryAABBNV structure specifies axis-aligned bounding box 7257geometry in a bottom-level acceleration structure, and is defined as: 7258 7259include::{generated}/api/structs/VkGeometryAABBNV.adoc[] 7260 7261 * pname:sType is a elink:VkStructureType value identifying this structure. 7262 * pname:pNext is `NULL` or a pointer to a structure extending this 7263 structure. 7264 * pname:aabbData is the buffer containing axis-aligned bounding box data. 7265 * pname:numAABBs is the number of AABBs in this geometry. 7266 * pname:stride is the stride in bytes between AABBs in pname:aabbData. 7267 * pname:offset is the offset in bytes of the first AABB in pname:aabbData. 7268 7269The AABB data in memory is six 32-bit floats consisting of the minimum x, y, 7270and z values followed by the maximum x, y, and z values. 7271 7272.Valid Usage 7273**** 7274 * [[VUID-VkGeometryAABBNV-offset-02439]] 7275 pname:offset must: be less than the size of pname:aabbData 7276 * [[VUID-VkGeometryAABBNV-offset-02440]] 7277 pname:offset must: be a multiple of `8` 7278 * [[VUID-VkGeometryAABBNV-stride-02441]] 7279 pname:stride must: be a multiple of `8` 7280**** 7281 7282include::{generated}/validity/structs/VkGeometryAABBNV.adoc[] 7283-- 7284endif::VK_NV_ray_tracing[] 7285 7286[open,refpage='vkDestroyAccelerationStructureKHR',desc='Destroy an acceleration structure object',type='protos'] 7287-- 7288:refpage: vkDestroyAccelerationStructureKHR 7289 7290To destroy an acceleration structure, call: 7291 7292ifdef::VK_KHR_acceleration_structure[] 7293include::{generated}/api/protos/vkDestroyAccelerationStructureKHR.adoc[] 7294endif::VK_KHR_acceleration_structure[] 7295 7296 * pname:device is the logical device that destroys the acceleration 7297 structure. 7298 * pname:accelerationStructure is the acceleration structure to destroy. 7299 * pname:pAllocator controls host memory allocation as described in the 7300 <<memory-allocation, Memory Allocation>> chapter. 7301 7302.Valid Usage 7303**** 7304 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-08934]] 7305 The <<features-accelerationStructure, 7306 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 7307 feature must: be enabled 7308 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02442]] 7309 All submitted commands that refer to pname:accelerationStructure must: 7310 have completed execution 7311ifndef::VKSC_VERSION_1_0[] 7312 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02443]] 7313 If sname:VkAllocationCallbacks were provided when 7314 pname:accelerationStructure was created, a compatible set of callbacks 7315 must: be provided here 7316 * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02444]] 7317 If no sname:VkAllocationCallbacks were provided when 7318 pname:accelerationStructure was created, pname:pAllocator must: be 7319 `NULL` 7320endif::VKSC_VERSION_1_0[] 7321**** 7322 7323include::{generated}/validity/protos/vkDestroyAccelerationStructureKHR.adoc[] 7324-- 7325 7326ifdef::VK_NV_ray_tracing[] 7327[open,refpage='vkDestroyAccelerationStructureNV',desc='Destroy an acceleration structure object',type='protos'] 7328-- 7329:refpage: vkDestroyAccelerationStructureNV 7330 7331To destroy an acceleration structure, call: 7332 7333include::{generated}/api/protos/vkDestroyAccelerationStructureNV.adoc[] 7334 7335 * pname:device is the logical device that destroys the buffer. 7336 * pname:accelerationStructure is the acceleration structure to destroy. 7337 * pname:pAllocator controls host memory allocation as described in the 7338 <<memory-allocation, Memory Allocation>> chapter. 7339 7340.Valid Usage 7341**** 7342 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03752]] 7343 All submitted commands that refer to pname:accelerationStructure must: 7344 have completed execution 7345ifndef::VKSC_VERSION_1_0[] 7346 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03753]] 7347 If sname:VkAllocationCallbacks were provided when 7348 pname:accelerationStructure was created, a compatible set of callbacks 7349 must: be provided here 7350 * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03754]] 7351 If no sname:VkAllocationCallbacks were provided when 7352 pname:accelerationStructure was created, pname:pAllocator must: be 7353 `NULL` 7354endif::VKSC_VERSION_1_0[] 7355**** 7356 7357include::{generated}/validity/protos/vkDestroyAccelerationStructureNV.adoc[] 7358-- 7359 7360[open,refpage='vkGetAccelerationStructureMemoryRequirementsNV',desc='Get acceleration structure memory requirements',type='protos'] 7361-- 7362:refpage: vkGetAccelerationStructureMemoryRequirementsNV 7363 7364An acceleration structure has memory requirements for the structure object 7365itself, scratch space for the build, and scratch space for the update. 7366 7367Scratch space is allocated as a sname:VkBuffer, so for 7368ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 7369and 7370ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 7371the pname:pMemoryRequirements->alignment and 7372pname:pMemoryRequirements->memoryTypeBits values returned by this call must: 7373be filled with zero, and should: be ignored by the application. 7374 7375To query the memory requirements, call: 7376 7377include::{generated}/api/protos/vkGetAccelerationStructureMemoryRequirementsNV.adoc[] 7378 7379 * pname:device is the logical device on which the acceleration structure 7380 was created. 7381 * pname:pInfo is a pointer to a 7382 slink:VkAccelerationStructureMemoryRequirementsInfoNV structure 7383 specifying the acceleration structure to get memory requirements for. 7384 * pname:pMemoryRequirements is a pointer to a 7385 slink:VkMemoryRequirements2KHR structure in which the requested 7386 acceleration structure memory requirements are returned. 7387 7388include::{generated}/validity/protos/vkGetAccelerationStructureMemoryRequirementsNV.adoc[] 7389-- 7390 7391[open,refpage='VkAccelerationStructureMemoryRequirementsInfoNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] 7392-- 7393:refpage: VkAccelerationStructureMemoryRequirementsInfoNV 7394 7395The sname:VkAccelerationStructureMemoryRequirementsInfoNV structure is 7396defined as: 7397 7398include::{generated}/api/structs/VkAccelerationStructureMemoryRequirementsInfoNV.adoc[] 7399 7400 * pname:sType is a elink:VkStructureType value identifying this structure. 7401 * pname:pNext is `NULL` or a pointer to a structure extending this 7402 structure. 7403 * pname:type selects the type of memory requirement being queried. 7404 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 7405 returns the memory requirements for the object itself. 7406 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 7407 returns the memory requirements for the scratch memory when doing a 7408 build. 7409 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 7410 returns the memory requirements for the scratch memory when doing an 7411 update. 7412 * pname:accelerationStructure is the acceleration structure to be queried 7413 for memory requirements. 7414 7415include::{generated}/validity/structs/VkAccelerationStructureMemoryRequirementsInfoNV.adoc[] 7416-- 7417 7418[open,refpage='VkAccelerationStructureMemoryRequirementsTypeNV',desc='Acceleration structure memory requirement type',type='enums'] 7419-- 7420:refpage: VkAccelerationStructureMemoryRequirementsTypeNV 7421 7422Possible values of pname:type in 7423sname:VkAccelerationStructureMemoryRequirementsInfoNV are:, 7424 7425include::{generated}/api/enums/VkAccelerationStructureMemoryRequirementsTypeNV.adoc[] 7426 7427 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 7428 requests the memory requirement for the sname:VkAccelerationStructureNV 7429 backing store. 7430 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV 7431 requests the memory requirement for scratch space during the initial 7432 build. 7433 * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV 7434 requests the memory requirement for scratch space during an update. 7435-- 7436endif::VK_NV_ray_tracing[] 7437 7438ifdef::VK_KHR_acceleration_structure[] 7439[open,refpage='VkAccelerationStructureBuildTypeKHR',desc='Acceleration structure build type',type='enums'] 7440-- 7441:refpage: VkAccelerationStructureBuildTypeKHR 7442 7443Possible values of pname:buildType in 7444flink:vkGetAccelerationStructureBuildSizesKHR are: 7445 7446include::{generated}/api/enums/VkAccelerationStructureBuildTypeKHR.adoc[] 7447 7448 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR requests the memory 7449 requirement for operations performed by the host. 7450 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR requests the 7451 memory requirement for operations performed by the device. 7452 * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR requests 7453 the memory requirement for operations performed by either the host, or 7454 the device. 7455-- 7456endif::VK_KHR_acceleration_structure[] 7457 7458ifdef::VK_NV_ray_tracing[] 7459[open,refpage='vkBindAccelerationStructureMemoryNV',desc='Bind acceleration structure memory',type='protos'] 7460-- 7461:refpage: vkBindAccelerationStructureMemoryNV 7462 7463To attach memory to one or more acceleration structures at a time, call: 7464 7465include::{generated}/api/protos/vkBindAccelerationStructureMemoryNV.adoc[] 7466 7467 * pname:device is the logical device that owns the acceleration structures 7468 and memory. 7469 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 7470 * pname:pBindInfos is a pointer to an array of 7471 slink:VkBindAccelerationStructureMemoryInfoNV structures describing 7472 acceleration structures and memory to bind. 7473 7474include::{generated}/validity/protos/vkBindAccelerationStructureMemoryNV.adoc[] 7475-- 7476 7477[open,refpage='VkBindAccelerationStructureMemoryInfoNV',desc='Structure specifying acceleration structure memory binding',type='structs'] 7478-- 7479:refpage: VkBindAccelerationStructureMemoryInfoNV 7480 7481The sname:VkBindAccelerationStructureMemoryInfoNV structure is defined as: 7482 7483include::{generated}/api/structs/VkBindAccelerationStructureMemoryInfoNV.adoc[] 7484 7485 * pname:sType is a elink:VkStructureType value identifying this structure. 7486 * pname:pNext is `NULL` or a pointer to a structure extending this 7487 structure. 7488 * pname:accelerationStructure is the acceleration structure to be attached 7489 to memory. 7490 * pname:memory is a sname:VkDeviceMemory object describing the device 7491 memory to attach. 7492 * pname:memoryOffset is the start offset of the region of memory that is 7493 to be bound to the acceleration structure. 7494 The number of bytes returned in the 7495 slink:VkMemoryRequirements::pname:size member in pname:memory, starting 7496 from pname:memoryOffset bytes, will be bound to the specified 7497 acceleration structure. 7498 * pname:deviceIndexCount is the number of elements in 7499 pname:pDeviceIndices. 7500 * pname:pDeviceIndices is a pointer to an array of device indices. 7501 7502.Valid Usage 7503**** 7504 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-03620]] 7505 pname:accelerationStructure must: not already be backed by a memory 7506 object 7507 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03621]] 7508 pname:memoryOffset must: be less than the size of pname:memory 7509 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-03622]] 7510 pname:memory must: have been allocated using one of the memory types 7511 allowed in the pname:memoryTypeBits member of the 7512 slink:VkMemoryRequirements structure returned from a call to 7513 flink:vkGetAccelerationStructureMemoryRequirementsNV with 7514 pname:accelerationStructure and pname:type of 7515 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 7516 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03623]] 7517 pname:memoryOffset must: be an integer multiple of the pname:alignment 7518 member of the slink:VkMemoryRequirements structure returned from a call 7519 to flink:vkGetAccelerationStructureMemoryRequirementsNV with 7520 pname:accelerationStructure and pname:type of 7521 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV 7522 * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-03624]] 7523 The pname:size member of the sname:VkMemoryRequirements structure 7524 returned from a call to 7525 flink:vkGetAccelerationStructureMemoryRequirementsNV with 7526 pname:accelerationStructure and pname:type of 7527 ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: 7528 be less than or equal to the size of pname:memory minus 7529 pname:memoryOffset 7530**** 7531 7532include::{generated}/validity/structs/VkBindAccelerationStructureMemoryInfoNV.adoc[] 7533-- 7534 7535[open,refpage='vkGetAccelerationStructureHandleNV',desc='Get opaque acceleration structure handle',type='protos'] 7536-- 7537:refpage: vkGetAccelerationStructureHandleNV 7538 7539To allow constructing geometry instances with device code if desired, we 7540need to be able to query a opaque handle for an acceleration structure. 7541This handle is a value of 8 bytes. 7542To get this handle, call: 7543 7544include::{generated}/api/protos/vkGetAccelerationStructureHandleNV.adoc[] 7545 7546 * pname:device is the logical device that owns the acceleration 7547 structures. 7548 * pname:accelerationStructure is the acceleration structure. 7549 * pname:dataSize is the size in bytes of the buffer pointed to by 7550 pname:pData. 7551 * pname:pData is a pointer to a user-allocated buffer where the results 7552 will be written. 7553 7554.Valid Usage 7555**** 7556 * [[VUID-vkGetAccelerationStructureHandleNV-dataSize-02240]] 7557 pname:dataSize must: be large enough to contain the result of the query, 7558 as described above 7559 * [[VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-02787]] 7560 pname:accelerationStructure must: be bound completely and contiguously 7561 to a single sname:VkDeviceMemory object via 7562 flink:vkBindAccelerationStructureMemoryNV 7563**** 7564 7565include::{generated}/validity/protos/vkGetAccelerationStructureHandleNV.adoc[] 7566-- 7567endif::VK_NV_ray_tracing[] 7568 7569ifdef::VK_KHR_acceleration_structure[] 7570[open,refpage='vkGetAccelerationStructureDeviceAddressKHR',desc='Query an address of a acceleration structure',type='protos'] 7571-- 7572:refpage: vkGetAccelerationStructureDeviceAddressKHR 7573 7574To query the 64-bit device address for an acceleration structure, call: 7575 7576include::{generated}/api/protos/vkGetAccelerationStructureDeviceAddressKHR.adoc[] 7577 7578 * pname:device is the logical device that the acceleration structure was 7579 created on. 7580 * pname:pInfo is a pointer to a 7581 slink:VkAccelerationStructureDeviceAddressInfoKHR structure specifying 7582 the acceleration structure to retrieve an address for. 7583 7584The 64-bit return value is an address of the acceleration structure, which 7585can be used for device and shader operations that involve acceleration 7586structures, such as 7587ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 7588ray traversal and 7589endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] 7590acceleration structure building. 7591 7592If the acceleration structure was created with a non-zero value of 7593slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress, the return 7594value will be the same address. 7595 7596If the acceleration structure was created with a pname:type of 7597ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must: 7598be consistent with the relative offset to other acceleration structures with 7599pname:type ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with 7600the same slink:VkBuffer. 7601That is, the difference in returned addresses between the two must: be the 7602same as the difference in offsets provided at acceleration structure 7603creation. 7604 7605The returned address must: be aligned to 256 bytes. 7606 7607[NOTE] 7608.Note 7609==== 7610The acceleration structure device address may: be different from the buffer 7611device address corresponding to the acceleration structure's start offset in 7612its storage buffer for acceleration structure types other than 7613ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. 7614==== 7615 7616.Valid Usage 7617**** 7618 * [[VUID-vkGetAccelerationStructureDeviceAddressKHR-accelerationStructure-08935]] 7619 The <<features-accelerationStructure, 7620 sname:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructure>> 7621 feature must: be enabled 7622 * [[VUID-vkGetAccelerationStructureDeviceAddressKHR-device-03504]] 7623 If pname:device was created with multiple physical devices, then the 7624 <<features-bufferDeviceAddressMultiDevice, 7625 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 7626**** 7627 7628include::{generated}/validity/protos/vkGetAccelerationStructureDeviceAddressKHR.adoc[] 7629-- 7630 7631[open,refpage='VkAccelerationStructureDeviceAddressInfoKHR',desc='Structure specifying the acceleration structure to query an address for',type='structs'] 7632-- 7633:refpage: VkAccelerationStructureDeviceAddressInfoKHR 7634 7635The sname:VkAccelerationStructureDeviceAddressInfoKHR structure is defined 7636as: 7637 7638include::{generated}/api/structs/VkAccelerationStructureDeviceAddressInfoKHR.adoc[] 7639 7640 * pname:sType is a elink:VkStructureType value identifying this structure. 7641 * pname:pNext is `NULL` or a pointer to a structure extending this 7642 structure. 7643 * pname:accelerationStructure specifies the acceleration structure whose 7644 address is being queried. 7645 7646include::{generated}/validity/structs/VkAccelerationStructureDeviceAddressInfoKHR.adoc[] 7647-- 7648endif::VK_KHR_acceleration_structure[] 7649endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 7650 7651 7652ifdef::VK_EXT_opacity_micromap[] 7653[[resources-micromaps]] 7654== Micromaps 7655 7656[open,refpage='VkMicromapEXT',desc='Opaque handle to a micromap object',type='handles'] 7657-- 7658:refpage: VkMicromapEXT 7659 7660Micromaps are opaque data structures that are built by the implementation to 7661encode sub-triangle data to be included in an acceleration structure. 7662 7663Micromaps are represented by sname:VkMicromapEXT handles: 7664 7665include::{generated}/api/handles/VkMicromapEXT.adoc[] 7666-- 7667 7668 7669[open,refpage='vkCreateMicromapEXT',desc='Create a new micromap object',type='protos'] 7670-- 7671:refpage: vkCreateMicromapEXT 7672 7673To create a micromap, call: 7674 7675include::{generated}/api/protos/vkCreateMicromapEXT.adoc[] 7676 7677 * pname:device is the logical device that creates the acceleration 7678 structure object. 7679 * pname:pCreateInfo is a pointer to a slink:VkMicromapCreateInfoEXT 7680 structure containing parameters affecting creation of the micromap. 7681 * pname:pAllocator controls host memory allocation as described in the 7682 <<memory-allocation, Memory Allocation>> chapter. 7683 * pname:pMicromap is a pointer to a sname:VkMicromapEXT handle in which 7684 the resulting micromap object is returned. 7685 7686Similar to other objects in Vulkan, the micromap creation merely creates an 7687object with a specific "`shape`". 7688The type and quantity of geometry that can be built into a micromap is 7689determined by the parameters of slink:VkMicromapCreateInfoEXT. 7690 7691The micromap data is stored in the object referred to by 7692sname:VkMicromapCreateInfoEXT::pname:buffer. 7693Once memory has been bound to that buffer, it must: be populated by micromap 7694build or micromap copy commands such as flink:vkCmdBuildMicromapsEXT, 7695flink:vkBuildMicromapsEXT, flink:vkCmdCopyMicromapEXT, and 7696flink:vkCopyMicromapEXT. 7697 7698[NOTE] 7699.Note 7700==== 7701The expected usage for a trace capture/replay tool is that it will serialize 7702and later deserialize the micromap data using micromap copy commands. 7703During capture the tool will use flink:vkCopyMicromapToMemoryEXT or 7704flink:vkCmdCopyMicromapToMemoryEXT with a pname:mode of 7705ename:VK_COPY_MICROMAP_MODE_SERIALIZE_EXT, and 7706flink:vkCopyMemoryToMicromapEXT or flink:vkCmdCopyMemoryToMicromapEXT with a 7707pname:mode of ename:VK_COPY_MICROMAP_MODE_DESERIALIZE_EXT during replay. 7708==== 7709 7710The input buffers passed to micromap build commands will be referenced by 7711the implementation for the duration of the command. 7712Micromaps must: be fully self-contained. 7713The application can: reuse or free any memory which was used by the command 7714as an input or as scratch without affecting the results of a subsequent 7715acceleration structure build using the micromap or traversal of that 7716acceleration structure. 7717 7718.Valid Usage 7719**** 7720 * [[VUID-vkCreateMicromapEXT-micromap-07430]] 7721 The <<features-micromap, pname:micromap>> feature must: be enabled 7722 * [[VUID-vkCreateMicromapEXT-deviceAddress-07431]] 7723 If slink:VkMicromapCreateInfoEXT::pname:deviceAddress is not zero, the 7724 <<features-micromapCaptureReplay, pname:micromapCaptureReplay>> feature 7725 must: be enabled 7726 * [[VUID-vkCreateMicromapEXT-device-07432]] 7727 If pname:device was created with multiple physical devices, then the 7728 <<features-bufferDeviceAddressMultiDevice, 7729 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 7730**** 7731 7732include::{generated}/validity/protos/vkCreateMicromapEXT.adoc[] 7733-- 7734 7735[open,refpage='VkMicromapCreateInfoEXT',desc='Structure specifying the parameters of a newly created micromap object',type='structs'] 7736-- 7737:refpage: VkMicromapCreateInfoEXT 7738 7739The sname:VkMicromapCreateInfoEXT structure is defined as: 7740 7741include::{generated}/api/structs/VkMicromapCreateInfoEXT.adoc[] 7742 7743 * pname:sType is a elink:VkStructureType value identifying this structure. 7744 * pname:pNext is `NULL` or a pointer to a structure extending this 7745 structure. 7746 * pname:createFlags is a bitmask of elink:VkMicromapCreateFlagBitsEXT 7747 specifying additional creation parameters of the micromap. 7748 * pname:buffer is the buffer on which the micromap will be stored. 7749 * pname:offset is an offset in bytes from the base address of the buffer 7750 at which the micromap will be stored, and must: be a multiple of `256`. 7751 * pname:size is the size required for the micromap. 7752 * pname:type is a elink:VkMicromapTypeEXT value specifying the type of 7753 micromap that will be created. 7754 * pname:deviceAddress is the device address requested for the micromap if 7755 the <<features-micromapCaptureReplay, pname:micromapCaptureReplay>> 7756 feature is being used. 7757 7758If pname:deviceAddress is zero, no specific address is requested. 7759 7760If pname:deviceAddress is not zero, pname:deviceAddress must: be an address 7761retrieved from an identically created micromap on the same implementation. 7762The micromap must: also be placed on an identically created pname:buffer and 7763at the same pname:offset. 7764 7765Applications should: avoid creating micromaps with application-provided 7766addresses and implementation-provided addresses in the same process, to 7767reduce the likelihood of ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR 7768errors. 7769 7770[NOTE] 7771.Note 7772==== 7773The expected usage for this is that a trace capture/replay tool will add the 7774ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers 7775that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add 7776ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as 7777storage for a micromap where pname:deviceAddress is not zero. 7778This also means that the tool will need to add 7779ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow 7780the flag to be set where the application may not have otherwise required it. 7781During capture the tool will save the queried opaque device addresses in the 7782trace. 7783During replay, the buffers will be created specifying the original address 7784so any address values stored in the trace data will remain valid. 7785 7786Implementations are expected to separate such buffers in the GPU address 7787space so normal allocations will avoid using these addresses. 7788Apps/tools should avoid mixing app-provided and implementation-provided 7789addresses for buffers created with 7790ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address 7791space allocation conflicts. 7792==== 7793 7794 7795If the micromap will be the target of a build operation, the required size 7796for a micromap can: be queried with flink:vkGetMicromapBuildSizesEXT. 7797 7798.Valid Usage 7799**** 7800 * [[VUID-VkMicromapCreateInfoEXT-deviceAddress-07433]] 7801 If pname:deviceAddress is not zero, pname:createFlags must: include 7802 ename:VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT 7803 * [[VUID-VkMicromapCreateInfoEXT-createFlags-07434]] 7804 If pname:createFlags includes 7805 ename:VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT, 7806 slink:VkPhysicalDeviceOpacityMicromapFeaturesEXT::pname:micromapCaptureReplay 7807 must: be ename:VK_TRUE 7808 * [[VUID-VkMicromapCreateInfoEXT-buffer-07435]] 7809 pname:buffer must: have been created with a pname:usage value containing 7810 ename:VK_BUFFER_USAGE_MICROMAP_STORAGE_BIT_EXT 7811 * [[VUID-VkMicromapCreateInfoEXT-buffer-07436]] 7812 pname:buffer must: not have been created with 7813 ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT 7814 * [[VUID-VkMicromapCreateInfoEXT-offset-07437]] 7815 The sum of pname:offset and pname:size must: be less than the size of 7816 pname:buffer 7817 * [[VUID-VkMicromapCreateInfoEXT-offset-07438]] 7818 pname:offset must: be a multiple of `256` bytes 7819**** 7820 7821include::{generated}/validity/structs/VkMicromapCreateInfoEXT.adoc[] 7822-- 7823 7824[open,refpage='vkGetMicromapBuildSizesEXT',desc='Retrieve the required size for a micromap',type='protos'] 7825-- 7826:refpage: vkGetMicromapBuildSizesEXT 7827 7828To get the build sizes for a micromap, call: 7829 7830include::{generated}/api/protos/vkGetMicromapBuildSizesEXT.adoc[] 7831 7832 * pname:device is the logical device that will be used for creating the 7833 micromap. 7834 * pname:buildType defines whether host or device operations (or both) are 7835 being queried for. 7836 * pname:pBuildInfo is a pointer to a slink:VkMicromapBuildInfoEXT 7837 structure describing parameters of a build operation. 7838 * pname:pSizeInfo is a pointer to a slink:VkMicromapBuildSizesInfoEXT 7839 structure which returns the size required for a micromap and the sizes 7840 required for the scratch buffers, given the build parameters. 7841 7842The pname:dstMicromap and pname:mode members of pname:pBuildInfo are 7843ignored. 7844Any slink:VkDeviceOrHostAddressKHR members of pname:pBuildInfo are ignored 7845by this command. 7846 7847A micromap created with the pname:micromapSize returned by this command 7848supports any build with a slink:VkMicromapBuildInfoEXT structure subject to 7849the following properties: 7850 7851 * The build command is a host build command, and pname:buildType is 7852 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or 7853 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 7854 * The build command is a device build command, and pname:buildType is 7855 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or 7856 ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR 7857 * For slink:VkMicromapBuildInfoEXT: 7858 ** Its pname:type, and pname:flags members are equal to 7859 pname:pBuildInfo->type and pname:pBuildInfo->flags, respectively. 7860 ** The sum of usage information in either pname:pUsageCounts or 7861 pname:ppUsageCounts is equal to the sum of usage information in either 7862 pname:pBuildInfo->pUsageCounts or pname:pBuildInfo->ppUsageCounts. 7863 7864Similarly, the pname:buildScratchSize value will support any build command 7865specifying the ename:VK_BUILD_MICROMAP_MODE_BUILD_EXT pname:mode under the 7866above conditions. 7867 7868.Valid Usage 7869**** 7870 * [[VUID-vkGetMicromapBuildSizesEXT-dstMicromap-09180]] 7871 slink:VkMicromapBuildInfoEXT::pname:dstMicromap must: have been created 7872 from pname:device 7873 * [[VUID-vkGetMicromapBuildSizesEXT-micromap-07439]] 7874 The <<features-micromap, pname:micromap>> feature must: be enabled 7875 * [[VUID-vkGetMicromapBuildSizesEXT-device-07440]] 7876 If pname:device was created with multiple physical devices, then the 7877 <<features-bufferDeviceAddressMultiDevice, 7878 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 7879**** 7880 7881include::{generated}/validity/protos/vkGetMicromapBuildSizesEXT.adoc[] 7882-- 7883 7884[open,refpage='VkMicromapBuildSizesInfoEXT',desc='Structure specifying build sizes for a micromap',type='structs'] 7885-- 7886:refpage: VkMicromapBuildSizesInfoEXT 7887 7888The sname:VkMicromapBuildSizesInfoEXT structure describes the required build 7889sizes for a micromap and scratch buffers and is defined as: 7890 7891include::{generated}/api/structs/VkMicromapBuildSizesInfoEXT.adoc[] 7892 7893 * pname:sType is a elink:VkStructureType value identifying this structure. 7894 * pname:pNext is `NULL` or a pointer to a structure extending this 7895 structure. 7896 * pname:micromapSize is the size in bytes required in a 7897 slink:VkMicromapEXT for a build or update operation. 7898 * pname:buildScratchSize is the size in bytes required in a scratch buffer 7899 for a build operation. 7900 * pname:discardable indicates whether or not the micromap object may be 7901 destroyed after an acceleration structure build or update. 7902 A false value means that acceleration structures built with this 7903 micromap may: contain references to the data contained therein, and the 7904 application must: not destroy the micromap until ray traversal has 7905 concluded. 7906 A true value means that the information in the micromap will be copied 7907 by value into the acceleration structure, and the micromap may: be 7908 destroyed after the acceleration structure build concludes. 7909 7910include::{generated}/validity/structs/VkMicromapBuildSizesInfoEXT.adoc[] 7911-- 7912 7913[open,refpage='VkMicromapTypeEXT',desc='Type of micromap',type='enums'] 7914-- 7915:refpage: VkMicromapTypeEXT 7916 7917Values which can: be set in slink:VkMicromapCreateInfoEXT::pname:type 7918specifying the type of micromap, are: 7919 7920include::{generated}/api/enums/VkMicromapTypeEXT.adoc[] 7921 7922 * ename:VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT is a micromap containing 7923 data to control the opacity of a triangle. 7924ifdef::VK_NV_displacement_micromap[] 7925 * ename:VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV is a micromap containing 7926 data to control the displacement of subtriangles within a triangle. 7927endif::VK_NV_displacement_micromap[] 7928 7929-- 7930 7931[open,refpage='VkMicromapCreateFlagBitsEXT',desc='Bitmask specifying additional creation parameters for micromap',type='enums'] 7932-- 7933Bits which can: be set in slink:VkMicromapCreateInfoEXT::pname:createFlags, 7934specifying additional creation parameters for micromaps, are: 7935 7936include::{generated}/api/enums/VkMicromapCreateFlagBitsEXT.adoc[] 7937 7938 * ename:VK_MICROMAP_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_EXT specifies 7939 that the micromap's address can: be saved and reused on a subsequent 7940 run. 7941-- 7942 7943[open,refpage='VkMicromapCreateFlagsEXT',desc='Bitmask of VkMicromapCreateFlagBitsEXT',type='flags'] 7944-- 7945include::{generated}/api/flags/VkMicromapCreateFlagsEXT.adoc[] 7946 7947tname:VkMicromapCreateFlagsEXT is a bitmask type for setting a mask of zero 7948or more elink:VkMicromapCreateFlagBitsEXT. 7949-- 7950 7951[open,refpage='VkBuildMicromapFlagBitsEXT',desc='Bitmask specifying additional parameters for micromap builds',type='enums',alias='VkBuildMicromapFlagBitsNV'] 7952-- 7953:refpage: VkBuildMicromapFlagBitsEXT 7954 7955Bits which can: be set in slink:VkMicromapBuildInfoEXT::pname:flags 7956specifying additional parameters for micromap builds, are: 7957 7958include::{generated}/api/enums/VkBuildMicromapFlagBitsEXT.adoc[] 7959 7960 * ename:VK_BUILD_MICROMAP_PREFER_FAST_TRACE_BIT_EXT indicates that the 7961 given micromap build should: prioritize trace performance over build 7962 time. 7963 * ename:VK_BUILD_MICROMAP_PREFER_FAST_BUILD_BIT_EXT indicates that the 7964 given micromap build should: prioritize build time over trace 7965 performance. 7966-- 7967 7968[open,refpage='VkBuildMicromapFlagsEXT',desc='Bitmask of VkBuildMicromapFlagBitsEXT',type='flags',alias='VkBuildMicromapFlagsNV'] 7969-- 7970:refpage: VkBuildMicromapFlagsEXT 7971 7972include::{generated}/api/flags/VkBuildMicromapFlagsEXT.adoc[] 7973 7974tname:VkBuildMicromapFlagsEXT is a bitmask type for setting a mask of zero 7975or more elink:VkBuildMicromapFlagBitsEXT. 7976-- 7977 7978[open,refpage='vkDestroyMicromapEXT',desc='Destroy a micromap object',type='protos'] 7979-- 7980:refpage: vkDestroyMicromapEXT 7981 7982To destroy a micromap, call: 7983 7984include::{generated}/api/protos/vkDestroyMicromapEXT.adoc[] 7985 7986 * pname:device is the logical device that destroys the micromap. 7987 * pname:micromap is the micromap to destroy. 7988 * pname:pAllocator controls host memory allocation as described in the 7989 <<memory-allocation, Memory Allocation>> chapter. 7990 7991.Valid Usage 7992**** 7993 * [[VUID-vkDestroyMicromapEXT-micromap-07441]] 7994 All submitted commands that refer to pname:micromap must: have completed 7995 execution 7996 * [[VUID-vkDestroyMicromapEXT-micromap-07442]] 7997 If sname:VkAllocationCallbacks were provided when pname:micromap was 7998 created, a compatible set of callbacks must: be provided here 7999 * [[VUID-vkDestroyMicromapEXT-micromap-07443]] 8000 If no sname:VkAllocationCallbacks were provided when pname:micromap was 8001 created, pname:pAllocator must: be `NULL` 8002**** 8003 8004include::{generated}/validity/protos/vkDestroyMicromapEXT.adoc[] 8005-- 8006 8007endif::VK_EXT_opacity_micromap[] 8008 8009 8010[[resources-association]] 8011== Resource Memory Association 8012 8013Resources are initially created as _virtual allocations_ with no backing 8014memory. 8015Device memory is allocated separately (see <<memory-device>>) and then 8016associated with the resource. 8017This association is done differently for sparse and non-sparse resources. 8018 8019Resources created with any of the sparse creation flags are considered 8020sparse resources. 8021Resources created without these flags are non-sparse. 8022The details on resource memory association for sparse resources is described 8023in <<sparsememory>>. 8024 8025Non-sparse resources must: be bound completely and contiguously to a single 8026sname:VkDeviceMemory object before the resource is passed as a parameter to 8027any of the following operations: 8028 8029 * creating image or buffer views 8030 * updating descriptor sets 8031 * recording commands in a command buffer 8032 8033Once bound, the memory binding is immutable for the lifetime of the 8034resource. 8035 8036ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 8037 8038In a logical device representing more than one physical device, buffer and 8039image resources exist on all physical devices but can: be bound to memory 8040differently on each. 8041Each such replicated resource is an _instance_ of the resource. 8042For sparse resources, each instance can: be bound to memory arbitrarily 8043differently. 8044For non-sparse resources, each instance can: either be bound to the local or 8045a peer instance of the memory, or for images can: be bound to rectangular 8046regions from the local and/or peer instances. 8047When a resource is used in a descriptor set, each physical device interprets 8048the descriptor according to its own instance's binding to memory. 8049 8050[NOTE] 8051.Note 8052==== 8053There are no new copy commands to transfer data between physical devices. 8054Instead, an application can: create a resource with a peer mapping and use 8055it as the source or destination of a transfer command executed by a single 8056physical device to copy the data from one physical device to another. 8057==== 8058 8059endif::VK_VERSION_1_1,VK_KHR_device_group[] 8060 8061[open,refpage='vkGetBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 8062-- 8063To determine the memory requirements for a buffer resource, call: 8064 8065include::{generated}/api/protos/vkGetBufferMemoryRequirements.adoc[] 8066 8067 * pname:device is the logical device that owns the buffer. 8068 * pname:buffer is the buffer to query. 8069 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements 8070 structure in which the memory requirements of the buffer object are 8071 returned. 8072 8073include::{generated}/validity/protos/vkGetBufferMemoryRequirements.adoc[] 8074-- 8075 8076[open,refpage='vkGetImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 8077-- 8078ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8079To determine the memory requirements for an image resource, call: 8080endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8081ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8082To determine the memory requirements for an image resource which is not 8083created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set, call: 8084endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8085 8086include::{generated}/api/protos/vkGetImageMemoryRequirements.adoc[] 8087 8088 * pname:device is the logical device that owns the image. 8089 * pname:image is the image to query. 8090 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements 8091 structure in which the memory requirements of the image object are 8092 returned. 8093 8094.Valid Usage 8095**** 8096ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8097 * [[VUID-vkGetImageMemoryRequirements-image-01588]] 8098 pname:image must: not have been created with the 8099 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set 8100endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8101ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 8102 * [[VUID-vkGetImageMemoryRequirements-image-04004]] 8103 If pname:image was created with the 8104 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 8105 external memory handle type, then pname:image must: be bound to memory 8106endif::VK_ANDROID_external_memory_android_hardware_buffer[] 8107ifdef::VK_QNX_external_memory_screen_buffer[] 8108 * [[VUID-vkGetImageMemoryRequirements-image-08960]] 8109 If pname:image was created with the 8110 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX external 8111 memory handle type, then pname:image must: be bound to memory 8112endif::VK_QNX_external_memory_screen_buffer[] 8113**** 8114 8115include::{generated}/validity/protos/vkGetImageMemoryRequirements.adoc[] 8116-- 8117 8118[open,refpage='VkMemoryRequirements',desc='Structure specifying memory requirements',type='structs'] 8119-- 8120The sname:VkMemoryRequirements structure is defined as: 8121 8122include::{generated}/api/structs/VkMemoryRequirements.adoc[] 8123 8124 * pname:size is the size, in bytes, of the memory allocation required: for 8125 the resource. 8126 * pname:alignment is the alignment, in bytes, of the offset within the 8127 allocation required: for the resource. 8128 * pname:memoryTypeBits is a bitmask and contains one bit set for every 8129 supported memory type for the resource. 8130 Bit `i` is set if and only if the memory type `i` in the 8131 sname:VkPhysicalDeviceMemoryProperties structure for the physical device 8132 is supported for the resource. 8133 8134include::{generated}/validity/structs/VkMemoryRequirements.adoc[] 8135-- 8136 8137ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 8138The precise size of images that will be bound to external Android hardware 8139buffer memory is unknown until the memory has been imported or allocated, so 8140applications must: not call flink:vkGetImageMemoryRequirements or 8141flink:vkGetImageMemoryRequirements2 with such an slink:VkImage before it has 8142been bound to memory. 8143ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8144For this reason, applications also must: not call 8145flink:vkGetDeviceImageMemoryRequirements with a slink:VkImageCreateInfo 8146describing an external Android hardware buffer. 8147endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8148When importing Android hardware buffer memory, the pname:allocationSize can: 8149be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID. 8150When allocating new memory for a slink:VkImage that can: be exported to an 8151Android hardware buffer, the memory's pname:allocationSize must: be zero; 8152the actual size will be determined by the dedicated image's parameters. 8153After the memory has been allocated, the amount of space allocated from the 8154memory's heap can: be obtained by getting the image's memory requirements or 8155by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID with the 8156Android hardware buffer exported from the memory. 8157 8158When allocating new memory for a slink:VkBuffer that can: be exported to an 8159Android hardware buffer an application may: still call 8160flink:vkGetBufferMemoryRequirements or flink:vkGetBufferMemoryRequirements2 8161with slink:VkBuffer before it has been bound to memory. 8162endif::VK_ANDROID_external_memory_android_hardware_buffer[] 8163 8164ifdef::VK_KHR_external_memory_win32[] 8165If the resource being queried was created with the 8166ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, 8167ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or 8168ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT external memory 8169handle type, the value of pname:size has no meaning and should: be ignored. 8170endif::VK_KHR_external_memory_win32[] 8171 8172The implementation guarantees certain properties about the memory 8173requirements returned by 8174ifdef::VK_KHR_get_memory_requirements2[] 8175flink:vkGetBufferMemoryRequirements2, flink:vkGetImageMemoryRequirements2, 8176endif::VK_KHR_get_memory_requirements2[] 8177ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8178flink:vkGetDeviceBufferMemoryRequirements, 8179flink:vkGetDeviceImageMemoryRequirements, 8180endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8181flink:vkGetBufferMemoryRequirements and flink:vkGetImageMemoryRequirements: 8182 8183 * The pname:memoryTypeBits member always contains at least one bit set. 8184 * If pname:buffer is a sname:VkBuffer not created with the 8185 ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT or 8186 ename:VK_BUFFER_CREATE_PROTECTED_BIT bits set, or if pname:image is a 8187 <<glossary-linear-resource,linear>> image that was not created with the 8188 ename:VK_IMAGE_CREATE_PROTECTED_BIT bit set, then the 8189 pname:memoryTypeBits member always contains at least one bit set 8190 corresponding to a sname:VkMemoryType with a pname:propertyFlags that 8191 has both the ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the 8192 ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set. 8193 In other words, mappable coherent memory can: always be attached to 8194 these objects. 8195ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8196 * If pname:buffer was created with 8197 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes set to `0` or 8198 pname:image was created with 8199 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes set to `0`, the 8200endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8201ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 8202 * The 8203endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8204 pname:memoryTypeBits member always contains at least one bit set 8205 corresponding to a sname:VkMemoryType with a pname:propertyFlags that 8206 has the ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set. 8207 * The pname:memoryTypeBits member is identical for all sname:VkBuffer 8208 objects created with the same value for the pname:flags and pname:usage 8209 members in the slink:VkBufferCreateInfo structure 8210ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8211 and the pname:handleTypes member of the 8212 slink:VkExternalMemoryBufferCreateInfo structure 8213endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8214 passed to flink:vkCreateBuffer. 8215 Further, if code:usage1 and code:usage2 of type tlink:VkBufferUsageFlags 8216 are such that the bits set in code:usage2 are a subset of the bits set 8217 in code:usage1, and they have the same 8218ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8219 pname:flags and 8220 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes, 8221endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8222ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 8223 pname:flags, 8224endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8225 then the bits set in pname:memoryTypeBits returned for code:usage1 must: 8226 be a subset of the bits set in pname:memoryTypeBits returned for 8227 code:usage2, for all values of pname:flags. 8228 * The pname:alignment member is a power of two. 8229 * The pname:alignment member is identical for all sname:VkBuffer objects 8230 created with the same combination of values for the pname:usage and 8231 pname:flags members in the slink:VkBufferCreateInfo structure passed to 8232 flink:vkCreateBuffer. 8233ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8234 * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, 8235 then the pname:alignment member is identical for all sname:VkImage 8236 objects created with the same combination of values for the pname:flags, 8237 pname:imageType, pname:format, pname:extent, pname:mipLevels, 8238 pname:arrayLayers, pname:samples, pname:tiling and pname:usage members 8239 in the slink:VkImageCreateInfo structure passed to flink:vkCreateImage. 8240endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8241 * The pname:alignment member satisfies the buffer descriptor offset 8242 alignment requirements associated with the sname:VkBuffer's pname:usage: 8243 ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT 8244 or ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:alignment 8245 must: be an integer multiple of 8246 sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment. 8247 ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, 8248 pname:alignment must: be an integer multiple of 8249 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment. 8250 ** If pname:usage included ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, 8251 pname:alignment must: be an integer multiple of 8252 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment. 8253 * For images created with a color format, the pname:memoryTypeBits member 8254 is identical for all sname:VkImage objects created with the same 8255 combination of values for the pname:tiling member, the 8256 ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the pname:flags member, 8257ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 8258 the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the 8259 pname:flags member, 8260endif::VK_VERSION_1_1,VK_KHR_device_group[] 8261ifdef::VK_EXT_host_image_copy[] 8262 the ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT bit of the pname:usage 8263 member if the 8264 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:identicalMemoryTypeRequirements 8265 property is ename:VK_FALSE, 8266endif::VK_EXT_host_image_copy[] 8267ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8268 pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, 8269endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8270 and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage 8271 member in the slink:VkImageCreateInfo structure passed to 8272 flink:vkCreateImage. 8273 * For images created with a depth/stencil format, the pname:memoryTypeBits 8274 member is identical for all sname:VkImage objects created with the same 8275 combination of values for the pname:format member, the pname:tiling 8276 member, the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the 8277 pname:flags member, 8278ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 8279 the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the 8280 pname:flags member, 8281endif::VK_VERSION_1_1,VK_KHR_device_group[] 8282ifdef::VK_EXT_host_image_copy[] 8283 the ename:VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT bit of the pname:usage 8284 member if the 8285 slink:VkPhysicalDeviceHostImageCopyPropertiesEXT::pname:identicalMemoryTypeRequirements 8286 property is ename:VK_FALSE, 8287endif::VK_EXT_host_image_copy[] 8288ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8289 pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, 8290endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8291 and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage 8292 member in the slink:VkImageCreateInfo structure passed to 8293 flink:vkCreateImage. 8294 * If the memory requirements are for a sname:VkImage, the 8295 pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with 8296 a pname:propertyFlags that has the 8297 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set if the pname:image 8298 did not have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in 8299 the pname:usage member of the slink:VkImageCreateInfo structure passed 8300 to flink:vkCreateImage. 8301 * If the memory requirements are for a sname:VkBuffer, the 8302 pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with 8303 a pname:propertyFlags that has the 8304 ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set. 8305+ 8306[NOTE] 8307.Note 8308==== 8309The implication of this requirement is that lazily allocated memory is 8310disallowed for buffers in all cases. 8311==== 8312 * The pname:size member is identical for all sname:VkBuffer objects 8313 created with the same combination of creation parameters specified in 8314 slink:VkBufferCreateInfo and its pname:pNext chain. 8315 * The pname:size member is identical for all sname:VkImage objects created 8316 with the same combination of creation parameters specified in 8317 slink:VkImageCreateInfo and its pname:pNext chain. 8318+ 8319[NOTE] 8320.Note 8321==== 8322This, however, does not imply that they interpret the contents of the bound 8323memory identically with each other. 8324ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8325That additional guarantee, however, can: be explicitly requested using 8326ename:VK_IMAGE_CREATE_ALIAS_BIT. 8327endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8328==== 8329ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8330 * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, 8331 these additional guarantees apply: 8332 ** For a sname:VkBuffer, the pname:size memory requirement is never 8333 greater than that of another sname:VkBuffer created with a greater or 8334 equal pname:size specified in slink:VkBufferCreateInfo, all other 8335 creation parameters being identical. 8336 ** For a sname:VkBuffer, the pname:size memory requirement is never 8337 greater than the result of aligning 8338 slink:VkBufferCreateInfo::pname:size with the pname:alignment memory 8339 requirement. 8340 ** For a slink:VkImage, the pname:size memory requirement is never greater 8341 than that of another slink:VkImage created with a greater or equal 8342 value in each of pname:extent.width, pname:extent.height, and 8343 pname:extent.depth; all other creation parameters being identical. 8344 ** The memory requirements returned by 8345 flink:vkGetDeviceBufferMemoryRequirements are identical to those that 8346 would be returned by flink:vkGetBufferMemoryRequirements2 if it were 8347 called with a sname:VkBuffer created with the same 8348 slink:VkBufferCreateInfo values. 8349 ** The memory requirements returned by 8350 flink:vkGetDeviceImageMemoryRequirements are identical to those that 8351 would be returned by flink:vkGetImageMemoryRequirements2 if it were 8352 called with a sname:VkImage created with the same 8353 slink:VkImageCreateInfo values. 8354endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8355 8356ifdef::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 8357[open,refpage='vkGetBufferMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 8358-- 8359To determine the memory requirements for a buffer resource, call: 8360 8361ifdef::VK_VERSION_1_1[] 8362include::{generated}/api/protos/vkGetBufferMemoryRequirements2.adoc[] 8363endif::VK_VERSION_1_1[] 8364 8365ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] 8366 8367ifdef::VK_KHR_get_memory_requirements2[] 8368include::{generated}/api/protos/vkGetBufferMemoryRequirements2KHR.adoc[] 8369endif::VK_KHR_get_memory_requirements2[] 8370 8371 * pname:device is the logical device that owns the buffer. 8372 * pname:pInfo is a pointer to a slink:VkBufferMemoryRequirementsInfo2 8373 structure containing parameters required for the memory requirements 8374 query. 8375 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 8376 structure in which the memory requirements of the buffer object are 8377 returned. 8378 8379include::{generated}/validity/protos/vkGetBufferMemoryRequirements2.adoc[] 8380-- 8381 8382ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8383[open,refpage='vkGetDeviceBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos',alias='vkGetDeviceBufferMemoryRequirementsKHR'] 8384-- 8385To determine the memory requirements for a buffer resource without creating 8386an object, call: 8387 8388ifdef::VK_VERSION_1_3[] 8389include::{generated}/api/protos/vkGetDeviceBufferMemoryRequirements.adoc[] 8390endif::VK_VERSION_1_3[] 8391 8392ifdef::VK_VERSION_1_3+VK_KHR_maintenance4[or the equivalent command] 8393 8394ifdef::VK_KHR_maintenance4[] 8395include::{generated}/api/protos/vkGetDeviceBufferMemoryRequirementsKHR.adoc[] 8396endif::VK_KHR_maintenance4[] 8397 8398 * pname:device is the logical device intended to own the buffer. 8399 * pname:pInfo is a pointer to a slink:VkDeviceBufferMemoryRequirements 8400 structure containing parameters required for the memory requirements 8401 query. 8402 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 8403 structure in which the memory requirements of the buffer object are 8404 returned. 8405 8406include::{generated}/validity/protos/vkGetDeviceBufferMemoryRequirements.adoc[] 8407-- 8408endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8409 8410[open,refpage='VkBufferMemoryRequirementsInfo2',desc='(None)',type='structs'] 8411-- 8412The sname:VkBufferMemoryRequirementsInfo2 structure is defined as: 8413 8414include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2.adoc[] 8415 8416ifdef::VK_KHR_get_memory_requirements2[] 8417or the equivalent 8418 8419include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2KHR.adoc[] 8420endif::VK_KHR_get_memory_requirements2[] 8421 8422 * pname:sType is a elink:VkStructureType value identifying this structure. 8423 * pname:pNext is `NULL` or a pointer to a structure extending this 8424 structure. 8425 * pname:buffer is the buffer to query. 8426 8427include::{generated}/validity/structs/VkBufferMemoryRequirementsInfo2.adoc[] 8428-- 8429 8430ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8431[open,refpage='VkDeviceBufferMemoryRequirements',desc='(None)',type='structs',alias='VkDeviceBufferMemoryRequirementsKHR'] 8432-- 8433The sname:VkDeviceBufferMemoryRequirements structure is defined as: 8434 8435include::{generated}/api/structs/VkDeviceBufferMemoryRequirements.adoc[] 8436 8437ifdef::VK_KHR_maintenance4[] 8438or the equivalent 8439 8440include::{generated}/api/structs/VkDeviceBufferMemoryRequirementsKHR.adoc[] 8441endif::VK_KHR_maintenance4[] 8442 8443 * pname:sType is a elink:VkStructureType value identifying this structure. 8444 * pname:pNext is `NULL` or a pointer to a structure extending this 8445 structure. 8446 * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure 8447 containing parameters affecting creation of the buffer to query. 8448 8449include::{generated}/validity/structs/VkDeviceBufferMemoryRequirements.adoc[] 8450-- 8451endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8452 8453[open,refpage='vkGetImageMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] 8454-- 8455To determine the memory requirements for an image resource, call: 8456 8457ifdef::VK_VERSION_1_1[] 8458include::{generated}/api/protos/vkGetImageMemoryRequirements2.adoc[] 8459endif::VK_VERSION_1_1[] 8460 8461ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] 8462 8463ifdef::VK_KHR_get_memory_requirements2[] 8464include::{generated}/api/protos/vkGetImageMemoryRequirements2KHR.adoc[] 8465endif::VK_KHR_get_memory_requirements2[] 8466 8467 * pname:device is the logical device that owns the image. 8468 * pname:pInfo is a pointer to a slink:VkImageMemoryRequirementsInfo2 8469 structure containing parameters required for the memory requirements 8470 query. 8471 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 8472 structure in which the memory requirements of the image object are 8473 returned. 8474 8475include::{generated}/validity/protos/vkGetImageMemoryRequirements2.adoc[] 8476-- 8477 8478ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8479[open,refpage='vkGetDeviceImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos',alias='vkGetDeviceImageMemoryRequirementsKHR'] 8480-- 8481To determine the memory requirements for an image resource without creating 8482an object, call: 8483 8484ifdef::VK_VERSION_1_3[] 8485include::{generated}/api/protos/vkGetDeviceImageMemoryRequirements.adoc[] 8486endif::VK_VERSION_1_3[] 8487 8488ifdef::VK_VERSION_1_3+VK_KHR_maintenance4[or the equivalent command] 8489 8490ifdef::VK_KHR_maintenance4[] 8491include::{generated}/api/protos/vkGetDeviceImageMemoryRequirementsKHR.adoc[] 8492endif::VK_KHR_maintenance4[] 8493 8494 * pname:device is the logical device intended to own the image. 8495 * pname:pInfo is a pointer to a slink:VkDeviceImageMemoryRequirements 8496 structure containing parameters required for the memory requirements 8497 query. 8498 * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 8499 structure in which the memory requirements of the image object are 8500 returned. 8501 8502include::{generated}/validity/protos/vkGetDeviceImageMemoryRequirements.adoc[] 8503-- 8504endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8505 8506[open,refpage='VkImageMemoryRequirementsInfo2',desc='(None)',type='structs'] 8507-- 8508The sname:VkImageMemoryRequirementsInfo2 structure is defined as: 8509 8510include::{generated}/api/structs/VkImageMemoryRequirementsInfo2.adoc[] 8511 8512ifdef::VK_KHR_get_memory_requirements2[] 8513or the equivalent 8514 8515include::{generated}/api/structs/VkImageMemoryRequirementsInfo2KHR.adoc[] 8516endif::VK_KHR_get_memory_requirements2[] 8517 8518 * pname:sType is a elink:VkStructureType value identifying this structure. 8519 * pname:pNext is `NULL` or a pointer to a structure extending this 8520 structure. 8521 * pname:image is the image to query. 8522 8523ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8524 8525.Valid Usage 8526**** 8527 * [[VUID-VkImageMemoryRequirementsInfo2-image-01589]] 8528 If pname:image was created with a _multi-planar_ format and the 8529 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: be a 8530 slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 8531 chain of the slink:VkImageMemoryRequirementsInfo2 structure 8532ifdef::VK_EXT_image_drm_format_modifier[] 8533 * [[VUID-VkImageMemoryRequirementsInfo2-image-02279]] 8534 If pname:image was created with ename:VK_IMAGE_CREATE_DISJOINT_BIT and 8535 with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then there must: be 8536 a slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 8537 chain of the slink:VkImageMemoryRequirementsInfo2 structure 8538endif::VK_EXT_image_drm_format_modifier[] 8539 * [[VUID-VkImageMemoryRequirementsInfo2-image-01590]] 8540 If pname:image was not created with the 8541 ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: not be a 8542 slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext 8543 chain of the slink:VkImageMemoryRequirementsInfo2 structure 8544ifndef::VK_EXT_image_drm_format_modifier[] 8545 * [[VUID-VkImageMemoryRequirementsInfo2-image-01591]] 8546 If pname:image was created with a single-plane format, there must: not 8547 be a slink:VkImagePlaneMemoryRequirementsInfo included in the 8548 pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure 8549endif::VK_EXT_image_drm_format_modifier[] 8550ifdef::VK_EXT_image_drm_format_modifier[] 8551 * [[VUID-VkImageMemoryRequirementsInfo2-image-02280]] 8552 If pname:image was created with a single-plane format and with any 8553 pname:tiling other than ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, 8554 then there must: not be a slink:VkImagePlaneMemoryRequirementsInfo 8555 included in the pname:pNext chain of the 8556 slink:VkImageMemoryRequirementsInfo2 structure 8557endif::VK_EXT_image_drm_format_modifier[] 8558ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 8559 * [[VUID-VkImageMemoryRequirementsInfo2-image-01897]] 8560 If pname:image was created with the 8561 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID 8562 external memory handle type, then pname:image must: be bound to memory 8563endif::VK_ANDROID_external_memory_android_hardware_buffer[] 8564ifdef::VK_QNX_external_memory_screen_buffer[] 8565 * [[VUID-VkImageMemoryRequirementsInfo2-image-08961]] 8566 If pname:image was created with the 8567 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX external 8568 memory handle type, then pname:image must: be bound to memory 8569endif::VK_QNX_external_memory_screen_buffer[] 8570**** 8571 8572endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8573 8574include::{generated}/validity/structs/VkImageMemoryRequirementsInfo2.adoc[] 8575-- 8576 8577ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8578[open,refpage='VkDeviceImageMemoryRequirements',desc='(None)',type='structs',alias='VkDeviceImageMemoryRequirementsKHR'] 8579-- 8580The sname:VkDeviceImageMemoryRequirements structure is defined as: 8581 8582include::{generated}/api/structs/VkDeviceImageMemoryRequirements.adoc[] 8583 8584ifdef::VK_KHR_maintenance4[] 8585or the equivalent 8586 8587include::{generated}/api/structs/VkDeviceImageMemoryRequirementsKHR.adoc[] 8588endif::VK_KHR_maintenance4[] 8589 8590 * pname:sType is a elink:VkStructureType value identifying this structure. 8591 * pname:pNext is `NULL` or a pointer to a structure extending this 8592 structure. 8593 * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure 8594 containing parameters affecting creation of the image to query. 8595 * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the 8596 aspect corresponding to the image plane to query. 8597 This parameter is ignored unless 8598ifdef::VK_EXT_image_drm_format_modifier[] 8599 pname:pCreateInfo->tiling is 8600 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, or 8601endif::VK_EXT_image_drm_format_modifier[] 8602 pname:pCreateInfo->flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT set. 8603 8604.Valid Usage 8605**** 8606 * [[VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06416]] 8607 The pname:pCreateInfo->pNext chain must: not contain a 8608 slink:VkImageSwapchainCreateInfoKHR structure 8609ifdef::VK_EXT_image_drm_format_modifier[] 8610 * [[VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06776]] 8611 The pname:pCreateInfo->pNext chain must: not contain a 8612 slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure 8613endif::VK_EXT_image_drm_format_modifier[] 8614ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] 8615ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8616 * [[VUID-VkDeviceImageMemoryRequirements-pNext-06996]] 8617 Applications also must: not call 8618 flink:vkGetDeviceImageMemoryRequirements with a slink:VkImageCreateInfo 8619 whose pname:pNext chain includes a slink:VkExternalFormatANDROID 8620 structure with non-zero pname:externalFormat 8621endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8622endif::VK_ANDROID_external_memory_android_hardware_buffer[] 8623ifdef::VK_QNX_external_memory_screen_buffer[] 8624ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 8625 * [[VUID-VkDeviceImageMemoryRequirements-pNext-08962]] 8626 Applications also must: not call 8627 flink:vkGetDeviceImageMemoryRequirements with a slink:VkImageCreateInfo 8628 whose pname:pNext chain includes a slink:VkExternalFormatQNX structure 8629 with non-zero pname:externalFormat 8630endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8631endif::VK_QNX_external_memory_screen_buffer[] 8632 * [[VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06417]] 8633 If pname:pCreateInfo->format specifies a _multi-planar_ format and 8634 pname:pCreateInfo->flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT set then 8635 pname:planeAspect must: not be ename:VK_IMAGE_ASPECT_NONE_KHR 8636 * [[VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06419]] 8637 If pname:pCreateInfo->flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT set 8638 and if the pname:pCreateInfo->tiling is ename:VK_IMAGE_TILING_LINEAR or 8639 ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single 8640 valid <<formats-planes-image-aspect,multi-planar aspect mask>> bit 8641ifdef::VK_EXT_image_drm_format_modifier[] 8642 * [[VUID-VkDeviceImageMemoryRequirements-pCreateInfo-06420]] 8643 If pname:pCreateInfo->tiling is 8644 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 8645 must: be a single valid _memory plane_ for the image (that is, 8646 pname:aspectMask must: specify a plane index that is less than the 8647 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 8648 associated with the image's pname:format and 8649 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 8650endif::VK_EXT_image_drm_format_modifier[] 8651**** 8652 8653include::{generated}/validity/structs/VkDeviceImageMemoryRequirements.adoc[] 8654-- 8655endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 8656 8657ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8658[open,refpage='VkImagePlaneMemoryRequirementsInfo',desc='Structure specifying image plane for memory requirements',type='structs'] 8659-- 8660To determine the memory requirements for a plane of a disjoint image, add a 8661sname:VkImagePlaneMemoryRequirementsInfo structure to the pname:pNext chain 8662of the sname:VkImageMemoryRequirementsInfo2 structure. 8663 8664The sname:VkImagePlaneMemoryRequirementsInfo structure is defined as: 8665 8666include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfo.adoc[] 8667 8668ifdef::VK_KHR_sampler_ycbcr_conversion[] 8669or the equivalent 8670 8671include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfoKHR.adoc[] 8672endif::VK_KHR_sampler_ycbcr_conversion[] 8673 8674 * pname:sType is a elink:VkStructureType value identifying this structure. 8675 * pname:pNext is `NULL` or a pointer to a structure extending this 8676 structure. 8677 * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the 8678 aspect corresponding to the image plane to query. 8679 8680.Valid Usage 8681**** 8682 * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02281]] 8683 If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or 8684 ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single 8685 valid <<formats-planes-image-aspect,multi-planar aspect mask>> bit 8686ifdef::VK_EXT_image_drm_format_modifier[] 8687 * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02282]] 8688 If the image's pname:tiling is 8689 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 8690 must: be a single valid _memory plane_ for the image (that is, 8691 pname:aspectMask must: specify a plane index that is less than the 8692 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 8693 associated with the image's pname:format and 8694 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 8695endif::VK_EXT_image_drm_format_modifier[] 8696**** 8697 8698include::{generated}/validity/structs/VkImagePlaneMemoryRequirementsInfo.adoc[] 8699-- 8700endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 8701 8702[open,refpage='VkMemoryRequirements2',desc='Structure specifying memory requirements',type='structs'] 8703-- 8704The sname:VkMemoryRequirements2 structure is defined as: 8705 8706include::{generated}/api/structs/VkMemoryRequirements2.adoc[] 8707 8708ifdef::VK_KHR_get_memory_requirements2[] 8709or the equivalent 8710 8711include::{generated}/api/structs/VkMemoryRequirements2KHR.adoc[] 8712endif::VK_KHR_get_memory_requirements2[] 8713 8714 * pname:sType is a elink:VkStructureType value identifying this structure. 8715 * pname:pNext is `NULL` or a pointer to a structure extending this 8716 structure. 8717 * pname:memoryRequirements is a slink:VkMemoryRequirements structure 8718 describing the memory requirements of the resource. 8719 8720include::{generated}/validity/structs/VkMemoryRequirements2.adoc[] 8721-- 8722endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] 8723 8724ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 8725[open,refpage='VkMemoryDedicatedRequirements',desc='Structure describing dedicated allocation requirements of buffer and image resources',type='structs'] 8726-- 8727The sname:VkMemoryDedicatedRequirements structure is defined as: 8728 8729include::{generated}/api/structs/VkMemoryDedicatedRequirements.adoc[] 8730 8731ifdef::VK_KHR_dedicated_allocation[] 8732or the equivalent 8733 8734include::{generated}/api/structs/VkMemoryDedicatedRequirementsKHR.adoc[] 8735endif::VK_KHR_dedicated_allocation[] 8736 8737 * pname:sType is a elink:VkStructureType value identifying this structure. 8738 * pname:pNext is `NULL` or a pointer to a structure extending this 8739 structure. 8740 * pname:prefersDedicatedAllocation specifies that the implementation would 8741 prefer a dedicated allocation for this resource. 8742 The application is still free to suballocate the resource but it may: 8743 get better performance if a dedicated allocation is used. 8744 * pname:requiresDedicatedAllocation specifies that a dedicated allocation 8745 is required for this resource. 8746 8747To determine the dedicated allocation requirements of a buffer or image 8748resource, add a slink:VkMemoryDedicatedRequirements structure to the 8749pname:pNext chain of the slink:VkMemoryRequirements2 structure passed as the 8750pname:pMemoryRequirements parameter of flink:vkGetBufferMemoryRequirements2 8751or flink:vkGetImageMemoryRequirements2, respectively. 8752 8753Constraints on the values returned for buffer resources are: 8754 8755ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8756 * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the 8757 pname:pNext chain of slink:VkBufferCreateInfo for the call to 8758 fname:vkCreateBuffer used to create the buffer being queried included a 8759 slink:VkExternalMemoryBufferCreateInfo structure, and any of the handle 8760 types specified in 8761 slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes requires 8762 dedicated allocation, as reported by 8763 flink:vkGetPhysicalDeviceExternalBufferProperties in 8764 sname:VkExternalBufferProperties::pname:externalMemoryProperties.externalMemoryFeatures. 8765 Otherwise, pname:requiresDedicatedAllocation will be ename:VK_FALSE. 8766 8767endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8768ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 8769 * pname:requiresDedicatedAllocation will be ename:VK_FALSE 8770endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8771 * When the implementation sets pname:requiresDedicatedAllocation to 8772 ename:VK_TRUE, it must: also set pname:prefersDedicatedAllocation to 8773 ename:VK_TRUE. 8774 * If ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in 8775 slink:VkBufferCreateInfo::pname:flags when pname:buffer was created, 8776 then both pname:prefersDedicatedAllocation and 8777 pname:requiresDedicatedAllocation will be ename:VK_FALSE. 8778 8779Constraints on the values returned for image resources are: 8780 8781ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 8782 * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the 8783 pname:pNext chain of slink:VkImageCreateInfo for the call to 8784 flink:vkCreateImage used to create the image being queried included a 8785 slink:VkExternalMemoryImageCreateInfo structure, and any of the handle 8786 types specified in 8787 slink:VkExternalMemoryImageCreateInfo::pname:handleTypes requires 8788 dedicated allocation, as reported by 8789 flink:vkGetPhysicalDeviceImageFormatProperties2 in 8790 sname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures. 8791endif::VK_VERSION_1_1,VK_KHR_external_memory[] 8792ifdef::VK_EXT_image_drm_format_modifier[] 8793 * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the image's 8794 tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. 8795endif::VK_EXT_image_drm_format_modifier[] 8796 * pname:requiresDedicatedAllocation will 8797ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_EXT_image_drm_format_modifier[] 8798 otherwise 8799endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_EXT_image_drm_format_modifier[] 8800 be ename:VK_FALSE 8801 * If ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in 8802 slink:VkImageCreateInfo::pname:flags when pname:image was created, then 8803 both pname:prefersDedicatedAllocation and 8804 pname:requiresDedicatedAllocation will be ename:VK_FALSE. 8805 8806include::{generated}/validity/structs/VkMemoryDedicatedRequirements.adoc[] 8807-- 8808endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] 8809 8810[open,refpage='vkBindBufferMemory',desc='Bind device memory to a buffer object',type='protos'] 8811-- 8812:refpage: vkBindBufferMemory 8813 8814To attach memory to a buffer object, call: 8815 8816include::{generated}/api/protos/vkBindBufferMemory.adoc[] 8817 8818 * pname:device is the logical device that owns the buffer and memory. 8819 * pname:buffer is the buffer to be attached to memory. 8820 * pname:memory is a slink:VkDeviceMemory object describing the device 8821 memory to attach. 8822 * pname:memoryOffset is the start offset of the region of pname:memory 8823 which is to be bound to the buffer. 8824 The number of bytes returned in the 8825 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 8826 from pname:memoryOffset bytes, will be bound to the specified buffer. 8827 8828ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8829fname:vkBindBufferMemory is equivalent to passing the same parameters 8830through slink:VkBindBufferMemoryInfo to flink:vkBindBufferMemory2. 8831endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8832 8833ifdef::VK_NV_external_memory_sci_buf[] 8834If the pname:memory was obtained by a memory import operation with 8835slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes assigned to 8836ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV, the properties of 8837pname:buffer and the pname:memoryoffset must: be compatible with the 8838attributes used to create stext:NvSciBufObj, otherwise the implementation 8839will return ename:VK_ERROR_VALIDATION_FAILED. 8840endif::VK_NV_external_memory_sci_buf[] 8841 8842include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 8843 8844.Valid Usage 8845**** 8846include::{chapters}/commonvalidity/bind_buffer_common.adoc[] 8847**** 8848 8849include::{generated}/validity/protos/vkBindBufferMemory.adoc[] 8850-- 8851 8852ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8853[open,refpage='vkBindBufferMemory2',desc='Bind device memory to buffer objects',type='protos'] 8854-- 8855:refpage: vkBindBufferMemory2 8856 8857To attach memory to buffer objects for one or more buffers at a time, call: 8858 8859ifdef::VK_VERSION_1_1[] 8860include::{generated}/api/protos/vkBindBufferMemory2.adoc[] 8861endif::VK_VERSION_1_1[] 8862 8863ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] 8864 8865ifdef::VK_KHR_bind_memory2[] 8866include::{generated}/api/protos/vkBindBufferMemory2KHR.adoc[] 8867endif::VK_KHR_bind_memory2[] 8868 8869 * pname:device is the logical device that owns the buffers and memory. 8870 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 8871 * pname:pBindInfos is a pointer to an array of pname:bindInfoCount 8872 slink:VkBindBufferMemoryInfo structures describing buffers and memory to 8873 bind. 8874 8875On some implementations, it may: be more efficient to batch memory bindings 8876into a single command. 8877 8878ifdef::VK_KHR_maintenance6[] 8879If the <<features-maintenance6, pname:maintenance6>> feature is enabled, 8880this command must: attempt to perform all of the memory binding operations 8881described by pname:pBindInfos, and must: not early exit on the first 8882failure. 8883endif::VK_KHR_maintenance6[] 8884 8885If any of the memory binding operations described by pname:pBindInfos fail, 8886the elink:VkResult returned by this command must: be the return value of any 8887one of the memory binding operations which did not return ename:VK_SUCCESS. 8888 8889[NOTE] 8890.Note 8891==== 8892If the fname:vkBindBufferMemory2 command failed, 8893ifdef::VK_KHR_maintenance6[] 8894slink:VkBindMemoryStatusKHR structures were not included in the pname:pNext 8895chains of each element of pname:pBindInfos, 8896endif::VK_KHR_maintenance6[] 8897and pname:bindInfoCount was greater than one, then the buffers referenced by 8898pname:pBindInfos will be in an indeterminate state, and must not be used. 8899 8900Applications should destroy these buffers. 8901==== 8902 8903include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 8904 8905include::{generated}/validity/protos/vkBindBufferMemory2.adoc[] 8906-- 8907 8908[open,refpage='VkBindBufferMemoryInfo',desc='Structure specifying how to bind a buffer to memory',type='structs'] 8909-- 8910:refpage: VkBindBufferMemoryInfo 8911 8912sname:VkBindBufferMemoryInfo contains members corresponding to the 8913parameters of flink:vkBindBufferMemory. 8914 8915The sname:VkBindBufferMemoryInfo structure is defined as: 8916 8917include::{generated}/api/structs/VkBindBufferMemoryInfo.adoc[] 8918 8919ifdef::VK_KHR_bind_memory2[] 8920or the equivalent 8921 8922include::{generated}/api/structs/VkBindBufferMemoryInfoKHR.adoc[] 8923endif::VK_KHR_bind_memory2[] 8924 8925 * pname:sType is a elink:VkStructureType value identifying this structure. 8926 * pname:pNext is `NULL` or a pointer to a structure extending this 8927 structure. 8928 * pname:buffer is the buffer to be attached to memory. 8929 * pname:memory is a slink:VkDeviceMemory object describing the device 8930 memory to attach. 8931 * pname:memoryOffset is the start offset of the region of pname:memory 8932 which is to be bound to the buffer. 8933 The number of bytes returned in the 8934 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 8935 from pname:memoryOffset bytes, will be bound to the specified buffer. 8936 8937.Valid Usage 8938**** 8939include::{chapters}/commonvalidity/bind_buffer_common.adoc[] 8940ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 8941 * [[VUID-VkBindBufferMemoryInfo-pNext-01605]] 8942 If the pname:pNext chain includes a 8943 slink:VkBindBufferMemoryDeviceGroupInfo structure, all instances of 8944 pname:memory specified by 8945 slink:VkBindBufferMemoryDeviceGroupInfo::pname:pDeviceIndices must: have 8946 been allocated 8947endif::VK_VERSION_1_1,VK_KHR_device_group[] 8948**** 8949 8950include::{generated}/validity/structs/VkBindBufferMemoryInfo.adoc[] 8951-- 8952 8953ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 8954[open,refpage='VkBindBufferMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] 8955-- 8956The sname:VkBindBufferMemoryDeviceGroupInfo structure is defined as: 8957 8958include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfo.adoc[] 8959 8960ifdef::VK_KHR_device_group[] 8961ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8962or the equivalent 8963 8964include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfoKHR.adoc[] 8965endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 8966endif::VK_KHR_device_group[] 8967 8968 * pname:sType is a elink:VkStructureType value identifying this structure. 8969 * pname:pNext is `NULL` or a pointer to a structure extending this 8970 structure. 8971 * pname:deviceIndexCount is the number of elements in 8972 pname:pDeviceIndices. 8973 * pname:pDeviceIndices is a pointer to an array of device indices. 8974 8975If the pname:pNext chain of slink:VkBindBufferMemoryInfo includes a 8976sname:VkBindBufferMemoryDeviceGroupInfo structure, then that structure 8977determines how memory is bound to buffers across multiple devices in a 8978device group. 8979 8980If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# 8981the buffer is attached to the instance of pname:memory on the physical 8982device with device index [eq]#pname:pDeviceIndices[i]#. 8983 8984If pname:deviceIndexCount is zero and pname:memory comes from a memory heap 8985with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 8986pname:pDeviceIndices contains consecutive indices from zero to the number of 8987physical devices in the logical device, minus one. 8988In other words, by default each physical device attaches to its own instance 8989of pname:memory. 8990 8991If pname:deviceIndexCount is zero and pname:memory comes from a memory heap 8992without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as 8993if pname:pDeviceIndices contains an array of zeros. 8994In other words, by default each physical device attaches to instance zero. 8995 8996.Valid Usage 8997**** 8998 * [[VUID-VkBindBufferMemoryDeviceGroupInfo-deviceIndexCount-01606]] 8999 pname:deviceIndexCount must: either be zero or equal to the number of 9000 physical devices in the logical device 9001 * [[VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-01607]] 9002 All elements of pname:pDeviceIndices must: be valid device indices 9003**** 9004 9005include::{generated}/validity/structs/VkBindBufferMemoryDeviceGroupInfo.adoc[] 9006-- 9007endif::VK_VERSION_1_1,VK_KHR_device_group[] 9008 9009ifdef::VK_KHR_maintenance6[] 9010[open,refpage='VkBindMemoryStatusKHR',desc='Structure specifying where to return memory binding status',type='structs'] 9011-- 9012The sname:VkBindMemoryStatusKHR structure is defined as: 9013 9014include::{generated}/api/structs/VkBindMemoryStatusKHR.adoc[] 9015 9016 * pname:sType is a elink:VkStructureType value identifying this structure. 9017 * pname:pNext is `NULL` or a pointer to a structure extending this 9018 structure. 9019 * pname:pResult is a pointer to a ename:VkResult value. 9020 9021If the pname:pNext chain of slink:VkBindBufferMemoryInfo or 9022slink:VkBindImageMemoryInfo includes a sname:VkBindMemoryStatusKHR 9023structure, then the sname:VkBindMemoryStatusKHR::pname:pResult will be 9024populated with a value describing the result of the corresponding memory 9025binding operation. 9026 9027include::{generated}/validity/structs/VkBindMemoryStatusKHR.adoc[] 9028-- 9029endif::VK_KHR_maintenance6[] 9030endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9031 9032[open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos'] 9033-- 9034:refpage: vkBindImageMemory 9035 9036ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9037To attach memory to an image object, call: 9038endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9039ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9040To attach memory to a sname:VkImage object created without the 9041ename:VK_IMAGE_CREATE_DISJOINT_BIT set, call: 9042endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9043 9044include::{generated}/api/protos/vkBindImageMemory.adoc[] 9045 9046 * pname:device is the logical device that owns the image and memory. 9047 * pname:image is the image. 9048 * pname:memory is the slink:VkDeviceMemory object describing the device 9049 memory to attach. 9050 * pname:memoryOffset is the start offset of the region of pname:memory 9051 which is to be bound to the image. 9052 The number of bytes returned in the 9053 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 9054 from pname:memoryOffset bytes, will be bound to the specified image. 9055 9056ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9057fname:vkBindImageMemory is equivalent to passing the same parameters through 9058slink:VkBindImageMemoryInfo to flink:vkBindImageMemory2. 9059endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9060 9061ifdef::VK_NV_external_memory_sci_buf[] 9062If the pname:memory is allocated by a memory import operation with 9063slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes assigned to 9064ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV, the properties of 9065pname:image and the pname:memoryoffset must: be compatible with the 9066attributes used to create stext:NvSciBufObj, otherwise the implementation 9067will return ename:VK_ERROR_VALIDATION_FAILED. 9068endif::VK_NV_external_memory_sci_buf[] 9069 9070include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 9071 9072.Valid Usage 9073**** 9074include::{chapters}/commonvalidity/bind_image_common.adoc[] 9075ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9076 * [[VUID-vkBindImageMemory-image-01608]] 9077 pname:image must: not have been created with the 9078 ename:VK_IMAGE_CREATE_DISJOINT_BIT set 9079endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9080 * [[VUID-vkBindImageMemory-memory-01047]] 9081 pname:memory must: have been allocated using one of the memory types 9082 allowed in the pname:memoryTypeBits member of the 9083 sname:VkMemoryRequirements structure returned from a call to 9084 flink:vkGetImageMemoryRequirements with pname:image 9085 * [[VUID-vkBindImageMemory-memoryOffset-01048]] 9086 pname:memoryOffset must: be an integer multiple of the pname:alignment 9087 member of the sname:VkMemoryRequirements structure returned from a call 9088 to flink:vkGetImageMemoryRequirements with pname:image 9089 * [[VUID-vkBindImageMemory-size-01049]] 9090 The difference of the size of pname:memory and pname:memoryOffset must: 9091 be greater than or equal to the pname:size member of the 9092 slink:VkMemoryRequirements structure returned from a call to 9093 flink:vkGetImageMemoryRequirements with the same pname:image 9094ifdef::VK_FUCHSIA_buffer_collection[] 9095 * [[VUID-vkBindImageMemory-image-06392]] 9096 If pname:image was created with 9097 slink:VkBufferCollectionImageCreateInfoFUCHSIA chained to 9098 slink:VkImageCreateInfo::pname:pNext, pname:memory must: be allocated 9099 with a slink:VkImportMemoryBufferCollectionFUCHSIA chained to 9100 slink:VkMemoryAllocateInfo::pname:pNext 9101endif::VK_FUCHSIA_buffer_collection[] 9102**** 9103 9104include::{generated}/validity/protos/vkBindImageMemory.adoc[] 9105-- 9106 9107ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9108[open,refpage='vkBindImageMemory2',desc='Bind device memory to image objects',type='protos'] 9109-- 9110:refpage: vkBindImageMemory2 9111 9112To attach memory to image objects for one or more images at a time, call: 9113 9114ifdef::VK_VERSION_1_1[] 9115include::{generated}/api/protos/vkBindImageMemory2.adoc[] 9116endif::VK_VERSION_1_1[] 9117 9118ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] 9119 9120ifdef::VK_KHR_bind_memory2[] 9121include::{generated}/api/protos/vkBindImageMemory2KHR.adoc[] 9122endif::VK_KHR_bind_memory2[] 9123 9124 * pname:device is the logical device that owns the images and memory. 9125 * pname:bindInfoCount is the number of elements in pname:pBindInfos. 9126 * pname:pBindInfos is a pointer to an array of slink:VkBindImageMemoryInfo 9127 structures, describing images and memory to bind. 9128 9129On some implementations, it may: be more efficient to batch memory bindings 9130into a single command. 9131 9132ifdef::VK_KHR_maintenance6[] 9133If the <<features-maintenance6, pname:maintenance6>> feature is enabled, 9134this command must: attempt to perform all of the memory binding operations 9135described by pname:pBindInfos, and must: not early exit on the first 9136failure. 9137endif::VK_KHR_maintenance6[] 9138 9139If any of the memory binding operations described by pname:pBindInfos fail, 9140the elink:VkResult returned by this command must: be the return value of any 9141one of the memory binding operations which did not return ename:VK_SUCCESS. 9142 9143[NOTE] 9144.Note 9145==== 9146If the fname:vkBindImageMemory2 command failed, 9147ifdef::VK_KHR_maintenance6[] 9148slink:VkBindMemoryStatusKHR structures were not included in the pname:pNext 9149chains of each element of pname:pBindInfos, 9150endif::VK_KHR_maintenance6[] 9151and pname:bindInfoCount was greater than one, then the images referenced by 9152pname:pBindInfos will be in an indeterminate state, and must not be used. 9153 9154Applications should destroy these images. 9155==== 9156 9157include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 9158 9159.Valid Usage 9160**** 9161ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9162 * [[VUID-vkBindImageMemory2-pBindInfos-02858]] 9163 If any slink:VkBindImageMemoryInfo::pname:image was created with 9164 ename:VK_IMAGE_CREATE_DISJOINT_BIT then all planes of 9165 slink:VkBindImageMemoryInfo::pname:image must: be bound individually in 9166 separate pname:pBindInfos 9167 * [[VUID-vkBindImageMemory2-pBindInfos-04006]] 9168 pname:pBindInfos must: not refer to the same image subresource more than 9169 once 9170endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9171**** 9172 9173include::{generated}/validity/protos/vkBindImageMemory2.adoc[] 9174-- 9175 9176[open,refpage='VkBindImageMemoryInfo',desc='Structure specifying how to bind an image to memory',type='structs'] 9177-- 9178:refpage: VkBindImageMemoryInfo 9179 9180sname:VkBindImageMemoryInfo contains members corresponding to the parameters 9181of flink:vkBindImageMemory. 9182 9183The sname:VkBindImageMemoryInfo structure is defined as: 9184 9185include::{generated}/api/structs/VkBindImageMemoryInfo.adoc[] 9186 9187ifdef::VK_KHR_bind_memory2[] 9188or the equivalent 9189 9190include::{generated}/api/structs/VkBindImageMemoryInfoKHR.adoc[] 9191endif::VK_KHR_bind_memory2[] 9192 9193 * pname:sType is a elink:VkStructureType value identifying this structure. 9194 * pname:pNext is `NULL` or a pointer to a structure extending this 9195 structure. 9196 * pname:image is the image to be attached to memory. 9197 * pname:memory is a slink:VkDeviceMemory object describing the device 9198 memory to attach. 9199 * pname:memoryOffset is the start offset of the region of pname:memory 9200 which is to be bound to the image. 9201 The number of bytes returned in the 9202 sname:VkMemoryRequirements::pname:size member in pname:memory, starting 9203 from pname:memoryOffset bytes, will be bound to the specified image. 9204 9205.Valid Usage 9206**** 9207include::{chapters}/commonvalidity/bind_image_common.adoc[] 9208ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9209 * [[VUID-VkBindImageMemoryInfo-memory-01612]] 9210 pname:memory must: have been allocated using one of the memory types 9211 allowed in the pname:memoryTypeBits member of the 9212 slink:VkMemoryRequirements structure returned from a call to 9213 flink:vkGetImageMemoryRequirements with pname:image 9214 * [[VUID-VkBindImageMemoryInfo-memoryOffset-01613]] 9215 pname:memoryOffset must: be an integer multiple of the pname:alignment 9216 member of the slink:VkMemoryRequirements structure returned from a call 9217 to flink:vkGetImageMemoryRequirements with pname:image 9218 * [[VUID-VkBindImageMemoryInfo-memory-01614]] 9219 The difference of the size of pname:memory and pname:memoryOffset must: 9220 be greater than or equal to the pname:size member of the 9221 slink:VkMemoryRequirements structure returned from a call to 9222 flink:vkGetImageMemoryRequirements with the same pname:image 9223endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9224ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9225 * [[VUID-VkBindImageMemoryInfo-pNext-01615]] 9226 If the pname:pNext chain does not include a 9227 slink:VkBindImagePlaneMemoryInfo structure, pname:memory must: have been 9228 allocated using one of the memory types allowed in the 9229 pname:memoryTypeBits member of the slink:VkMemoryRequirements structure 9230 returned from a call to flink:vkGetImageMemoryRequirements2 with 9231 pname:image 9232 * [[VUID-VkBindImageMemoryInfo-pNext-01616]] 9233 If the pname:pNext chain does not include a 9234 slink:VkBindImagePlaneMemoryInfo structure, pname:memoryOffset must: be 9235 an integer multiple of the pname:alignment member of the 9236 slink:VkMemoryRequirements structure returned from a call to 9237 flink:vkGetImageMemoryRequirements2 with pname:image 9238 * [[VUID-VkBindImageMemoryInfo-pNext-01617]] 9239 If the pname:pNext chain does not include a 9240 slink:VkBindImagePlaneMemoryInfo structure, the difference of the size 9241 of pname:memory and pname:memoryOffset must: be greater than or equal to 9242 the pname:size member of the slink:VkMemoryRequirements structure 9243 returned from a call to flink:vkGetImageMemoryRequirements2 with the 9244 same pname:image 9245 * [[VUID-VkBindImageMemoryInfo-pNext-01618]] 9246 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 9247 structure, pname:image must: have been created with the 9248 ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set 9249 * [[VUID-VkBindImageMemoryInfo-image-07736]] 9250 If pname:image was created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT 9251 bit set, then the pname:pNext chain must: include a 9252 slink:VkBindImagePlaneMemoryInfo structure 9253 * [[VUID-VkBindImageMemoryInfo-pNext-01619]] 9254 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 9255 structure, pname:memory must: have been allocated using one of the 9256 memory types allowed in the pname:memoryTypeBits member of the 9257 slink:VkMemoryRequirements structure returned from a call to 9258 flink:vkGetImageMemoryRequirements2 with pname:image and where 9259 slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the 9260 slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 9261 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 9262 * [[VUID-VkBindImageMemoryInfo-pNext-01620]] 9263 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 9264 structure, pname:memoryOffset must: be an integer multiple of the 9265 pname:alignment member of the slink:VkMemoryRequirements structure 9266 returned from a call to flink:vkGetImageMemoryRequirements2 with 9267 pname:image and where 9268 slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the 9269 slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 9270 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 9271 * [[VUID-VkBindImageMemoryInfo-pNext-01621]] 9272 If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo 9273 structure, the difference of the size of pname:memory and 9274 pname:memoryOffset must: be greater than or equal to the pname:size 9275 member of the slink:VkMemoryRequirements structure returned from a call 9276 to flink:vkGetImageMemoryRequirements2 with the same pname:image and 9277 where slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to 9278 the slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the 9279 slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain 9280endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9281ifndef::VK_VERSION_1_1+VK_KHR_swapchain[] 9282ifndef::VK_KHR_device_group+VK_KHR_swapchain[] 9283 * [[VUID-VkBindImageMemoryInfo-memory-01625]] 9284 pname:memory must: be a valid slink:VkDeviceMemory handle 9285endif::VK_KHR_device_group+VK_KHR_swapchain[] 9286endif::VK_VERSION_1_1+VK_KHR_swapchain[] 9287ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 9288 * [[VUID-VkBindImageMemoryInfo-pNext-01626]] 9289 If the pname:pNext chain includes a 9290 slink:VkBindImageMemoryDeviceGroupInfo structure, all instances of 9291 pname:memory specified by 9292 slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices must: have 9293 been allocated 9294ifndef::VKSC_VERSION_1_0[] 9295 * [[VUID-VkBindImageMemoryInfo-pNext-01627]] 9296 If the pname:pNext chain includes a 9297 slink:VkBindImageMemoryDeviceGroupInfo structure, and 9298 slink:VkBindImageMemoryDeviceGroupInfo::pname:splitInstanceBindRegionCount 9299 is not zero, then pname:image must: have been created with the 9300 ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set 9301 * [[VUID-VkBindImageMemoryInfo-pNext-01628]] 9302 If the pname:pNext chain includes a 9303 slink:VkBindImageMemoryDeviceGroupInfo structure, all elements of 9304 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions 9305 must: be valid rectangles contained within the dimensions of pname:image 9306 * [[VUID-VkBindImageMemoryInfo-pNext-01629]] 9307 If the pname:pNext chain includes a 9308 slink:VkBindImageMemoryDeviceGroupInfo structure, the union of the areas 9309 of all elements of 9310 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions 9311 that correspond to the same instance of pname:image must: cover the 9312 entire image 9313endif::VKSC_VERSION_1_0[] 9314ifdef::VK_KHR_swapchain[] 9315 * [[VUID-VkBindImageMemoryInfo-image-01630]] 9316 If pname:image was created with a valid swapchain handle in 9317 slink:VkImageSwapchainCreateInfoKHR::pname:swapchain, then the 9318 pname:pNext chain must: include a 9319 slink:VkBindImageMemorySwapchainInfoKHR structure containing the same 9320 swapchain handle 9321 * [[VUID-VkBindImageMemoryInfo-pNext-01631]] 9322 If the pname:pNext chain includes a 9323 slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be 9324 dlink:VK_NULL_HANDLE 9325 * [[VUID-VkBindImageMemoryInfo-pNext-01632]] 9326 If the pname:pNext chain does not include a 9327 slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be 9328 a valid slink:VkDeviceMemory handle 9329endif::VK_KHR_swapchain[] 9330endif::VK_VERSION_1_1,VK_KHR_device_group[] 9331**** 9332 9333include::{generated}/validity/structs/VkBindImageMemoryInfo.adoc[] 9334-- 9335 9336ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 9337[open,refpage='VkBindImageMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] 9338-- 9339The sname:VkBindImageMemoryDeviceGroupInfo structure is defined as: 9340 9341include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfo.adoc[] 9342 9343ifdef::VK_KHR_device_group[] 9344ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9345or the equivalent 9346 9347include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfoKHR.adoc[] 9348endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9349endif::VK_KHR_device_group[] 9350 9351 * pname:sType is a elink:VkStructureType value identifying this structure. 9352 * pname:pNext is `NULL` or a pointer to a structure extending this 9353 structure. 9354 * pname:deviceIndexCount is the number of elements in 9355 pname:pDeviceIndices. 9356 * pname:pDeviceIndices is a pointer to an array of device indices. 9357 * pname:splitInstanceBindRegionCount is the number of elements in 9358 pname:pSplitInstanceBindRegions. 9359 * pname:pSplitInstanceBindRegions is a pointer to an array of 9360 slink:VkRect2D structures describing which regions of the image are 9361 attached to each instance of memory. 9362 9363If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a 9364sname:VkBindImageMemoryDeviceGroupInfo structure, then that structure 9365determines how memory is bound to images across multiple devices in a device 9366group. 9367 9368If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# 9369pname:image is attached to the instance of the memory on the physical device 9370with device index [eq]#pname:pDeviceIndices[i]#. 9371 9372ifndef::VKSC_VERSION_1_0[] 9373Let [eq]#N# be the number of physical devices in the logical device. 9374If pname:splitInstanceBindRegionCount is greater than zero, then 9375pname:pSplitInstanceBindRegions is a pointer to an array of [eq]#N^2^# 9376rectangles, where the image region specified by the rectangle at element 9377[eq]#i*N+j# in resource instance [eq]#i# is bound to the memory instance 9378[eq]#j#. 9379The blocks of the memory that are bound to each sparse image block region 9380use an offset in memory, relative to pname:memoryOffset, computed as if the 9381whole image was being bound to a contiguous range of memory. 9382In other words, horizontally adjacent image blocks use consecutive blocks of 9383memory, vertically adjacent image blocks are separated by the number of 9384bytes per block multiplied by the width in blocks of pname:image, and the 9385block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset. 9386endif::VKSC_VERSION_1_0[] 9387ifdef::VKSC_VERSION_1_0[] 9388In Vulkan SC, pname:splitInstanceBindRegionCount must: be zero because 9389sparse allocations are not supported <<SCID-8>>. 9390endif::VKSC_VERSION_1_0[] 9391 9392If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero 9393and the memory comes from a memory heap with the 9394ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 9395pname:pDeviceIndices contains consecutive indices from zero to the number of 9396physical devices in the logical device, minus one. 9397In other words, by default each physical device attaches to its own instance 9398of the memory. 9399 9400If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero 9401and the memory comes from a memory heap without the 9402ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if 9403pname:pDeviceIndices contains an array of zeros. 9404In other words, by default each physical device attaches to instance zero. 9405 9406.Valid Usage 9407**** 9408ifndef::VKSC_VERSION_1_0[] 9409 * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01633]] 9410 At least one of pname:deviceIndexCount and 9411 pname:splitInstanceBindRegionCount must: be zero 9412endif::VKSC_VERSION_1_0[] 9413 * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01634]] 9414 pname:deviceIndexCount must: either be zero or equal to the number of 9415 physical devices in the logical device 9416 * [[VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-01635]] 9417 All elements of pname:pDeviceIndices must: be valid device indices 9418ifdef::VKSC_VERSION_1_0[] 9419 * [[VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-05067]] 9420 pname:splitInstanceBindRegionCount must: be zero 9421endif::VKSC_VERSION_1_0[] 9422ifndef::VKSC_VERSION_1_0[] 9423 * [[VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-01636]] 9424 pname:splitInstanceBindRegionCount must: either be zero or equal to the 9425 number of physical devices in the logical device squared 9426 * [[VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-01637]] 9427 Elements of pname:pSplitInstanceBindRegions that correspond to the same 9428 instance of an image must: not overlap 9429 * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01638]] 9430 The pname:offset.x member of any element of 9431 pname:pSplitInstanceBindRegions must: be a multiple of the sparse image 9432 block width 9433 (sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of 9434 all non-metadata aspects of the image 9435 * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01639]] 9436 The pname:offset.y member of any element of 9437 pname:pSplitInstanceBindRegions must: be a multiple of the sparse image 9438 block height 9439 (sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of 9440 all non-metadata aspects of the image 9441 * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01640]] 9442 The pname:extent.width member of any element of 9443 pname:pSplitInstanceBindRegions must: either be a multiple of the sparse 9444 image block width of all non-metadata aspects of the image, or else 9445 pname:extent.width {plus} pname:offset.x must: equal the width of the 9446 image subresource 9447 * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01641]] 9448 The pname:extent.height member of any element of 9449 pname:pSplitInstanceBindRegions must: either be a multiple of the sparse 9450 image block height of all non-metadata aspects of the image, or else 9451 pname:extent.height {plus} pname:offset.y must: equal the height of the 9452 image subresource 9453endif::VKSC_VERSION_1_0[] 9454**** 9455ifdef::VKSC_VERSION_1_0[] 9456ifdef::hidden[] 9457// tag::scdeviation[] 9458 * slink:VkBindImageMemoryDeviceGroupInfo::pname:splitInstanceBindRegionCount 9459 must: be zero <<SCID-8>>. 9460// end::scdeviation[] 9461endif::hidden[] 9462endif::VKSC_VERSION_1_0[] 9463 9464include::{generated}/validity/structs/VkBindImageMemoryDeviceGroupInfo.adoc[] 9465-- 9466 9467ifdef::VK_KHR_swapchain[] 9468[open,refpage='VkBindImageMemorySwapchainInfoKHR',desc='Structure specifying swapchain image memory to bind to',type='structs'] 9469-- 9470If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a 9471sname:VkBindImageMemorySwapchainInfoKHR structure, then that structure 9472includes a swapchain handle and image index indicating that the image will 9473be bound to memory from that swapchain. 9474 9475The sname:VkBindImageMemorySwapchainInfoKHR structure is defined as: 9476 9477include::{generated}/api/structs/VkBindImageMemorySwapchainInfoKHR.adoc[] 9478 9479 * pname:sType is a elink:VkStructureType value identifying this structure. 9480 * pname:pNext is `NULL` or a pointer to a structure extending this 9481 structure. 9482 * pname:swapchain is dlink:VK_NULL_HANDLE or a swapchain handle. 9483 * pname:imageIndex is an image index within pname:swapchain. 9484 9485If pname:swapchain is not `NULL`, the pname:swapchain and pname:imageIndex 9486are used to determine the memory that the image is bound to, instead of 9487pname:memory and pname:memoryOffset. 9488 9489Memory can: be bound to a swapchain and use the pname:pDeviceIndices or 9490pname:pSplitInstanceBindRegions members of 9491slink:VkBindImageMemoryDeviceGroupInfo. 9492 9493.Valid Usage 9494**** 9495 * [[VUID-VkBindImageMemorySwapchainInfoKHR-imageIndex-01644]] 9496 pname:imageIndex must: be less than the number of images in 9497 pname:swapchain 9498ifdef::VK_EXT_swapchain_maintenance1[] 9499ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 9500 * [[VUID-VkBindImageMemorySwapchainInfoKHR-swapchain-07756]] 9501 If the pname:swapchain has been created with 9502 ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT, 9503 pname:imageIndex must: be one that has previously been returned by 9504 flink:vkAcquireNextImageKHR or flink:vkAcquireNextImage2KHR 9505endif::VK_VERSION_1_1,VK_KHR_device_group[] 9506ifndef::VK_VERSION_1_1,VK_KHR_device_group[] 9507 * [[VUID-VkBindImageMemorySwapchainInfoKHR-swapchain-07910]] 9508 If the pname:swapchain has been created with 9509 ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT, 9510 pname:imageIndex must: be one that has previously been returned by 9511 flink:vkAcquireNextImageKHR 9512endif::VK_VERSION_1_1,VK_KHR_device_group[] 9513endif::VK_EXT_swapchain_maintenance1[] 9514**** 9515 9516include::{generated}/validity/structs/VkBindImageMemorySwapchainInfoKHR.adoc[] 9517-- 9518endif::VK_KHR_swapchain[] 9519endif::VK_VERSION_1_1,VK_KHR_device_group[] 9520 9521ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9522[open,refpage='VkBindImagePlaneMemoryInfo',desc='Structure specifying how to bind an image plane to memory',type='structs'] 9523-- 9524In order to bind _planes_ of a _disjoint image_, add a 9525sname:VkBindImagePlaneMemoryInfo structure to the pname:pNext chain of 9526slink:VkBindImageMemoryInfo. 9527 9528The sname:VkBindImagePlaneMemoryInfo structure is defined as: 9529 9530include::{generated}/api/structs/VkBindImagePlaneMemoryInfo.adoc[] 9531 9532ifdef::VK_KHR_sampler_ycbcr_conversion[] 9533or the equivalent 9534 9535include::{generated}/api/structs/VkBindImagePlaneMemoryInfoKHR.adoc[] 9536endif::VK_KHR_sampler_ycbcr_conversion[] 9537 9538 * pname:sType is a elink:VkStructureType value identifying this structure. 9539 * pname:pNext is `NULL` or a pointer to a structure extending this 9540 structure. 9541 * pname:planeAspect is a ename:VkImageAspectFlagBits value specifying the 9542 aspect of the disjoint image plane to bind. 9543 9544.Valid Usage 9545**** 9546 * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02283]] 9547 If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or 9548 ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single 9549 valid <<formats-planes-image-aspect,multi-planar aspect mask>> bit 9550ifdef::VK_EXT_image_drm_format_modifier[] 9551 * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02284]] 9552 If the image's pname:tiling is 9553 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect 9554 must: be a single valid _memory plane_ for the image (that is, 9555 pname:aspectMask must: specify a plane index that is less than the 9556 slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount 9557 associated with the image's pname:format and 9558 slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) 9559endif::VK_EXT_image_drm_format_modifier[] 9560**** 9561 9562include::{generated}/validity/structs/VkBindImagePlaneMemoryInfo.adoc[] 9563-- 9564endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9565endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9566 9567 9568[[resources-bufferimagegranularity,Buffer-Image Granularity]] 9569.Buffer-Image Granularity 9570The implementation-dependent limit <<limits-bufferImageGranularity, 9571pname:bufferImageGranularity>> specifies a page-like granularity at which 9572linear and non-linear resources must: be placed in adjacent memory locations 9573to avoid aliasing. 9574Two resources which do not satisfy this granularity requirement are said to 9575<<resources-memory-aliasing,alias>>. 9576pname:bufferImageGranularity is specified in bytes, and must: be a power of 9577two. 9578Implementations which do not impose a granularity restriction may: report a 9579pname:bufferImageGranularity value of one. 9580 9581[NOTE] 9582.Note 9583==== 9584Despite its name, pname:bufferImageGranularity is really a granularity 9585between "`linear`" and "`non-linear`" resources. 9586==== 9587 9588Given resourceA at the lower memory offset and resourceB at the higher 9589memory offset in the same sname:VkDeviceMemory object, where one resource is 9590linear and the other is non-linear (as defined in the 9591<<glossary-linear-resource,Glossary>>), and the following: 9592 9593[source,c] 9594---- 9595resourceA.end = resourceA.memoryOffset + resourceA.size - 1 9596resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1) 9597resourceB.start = resourceB.memoryOffset 9598resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1) 9599---- 9600 9601The following property must: hold: 9602 9603[source,c] 9604---- 9605resourceA.endPage < resourceB.startPage 9606---- 9607 9608That is, the end of the first resource (A) and the beginning of the second 9609resource (B) must: be on separate "`pages`" of size 9610pname:bufferImageGranularity. 9611pname:bufferImageGranularity may: be different than the physical page size 9612of the memory heap. 9613This restriction is only needed when a linear resource and a non-linear 9614resource are adjacent in memory and will be used simultaneously. 9615The memory ranges of adjacent resources can: be closer than 9616pname:bufferImageGranularity, provided they meet the pname:alignment 9617requirement for the objects in question. 9618 9619Sparse block size in bytes and sparse image and buffer memory alignments 9620must: all be multiples of the pname:bufferImageGranularity. 9621Therefore, memory bound to sparse resources naturally satisfies the 9622pname:bufferImageGranularity. 9623 9624 9625[[resources-sharing]] 9626== Resource Sharing Mode 9627 9628[open,refpage='VkSharingMode',desc='Buffer and image sharing modes',type='enums'] 9629-- 9630Buffer and image objects are created with a _sharing mode_ controlling how 9631they can: be accessed from queues. 9632The supported sharing modes are: 9633 9634include::{generated}/api/enums/VkSharingMode.adoc[] 9635 9636 * ename:VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or 9637 image subresource of the object will be exclusive to a single queue 9638 family at a time. 9639 * ename:VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any 9640 range or image subresource of the object from multiple queue families is 9641 supported. 9642 9643[NOTE] 9644.Note 9645==== 9646ename:VK_SHARING_MODE_CONCURRENT may: result in lower performance access to 9647the buffer or image than ename:VK_SHARING_MODE_EXCLUSIVE. 9648==== 9649 9650Ranges of buffers and image subresources of image objects created using 9651ename:VK_SHARING_MODE_EXCLUSIVE must: only be accessed by queues in the 9652queue family that has _ownership_ of the resource. 9653Upon creation, such resources are not owned by any queue family; ownership 9654is implicitly acquired upon first use within a queue. 9655Once a resource using ename:VK_SHARING_MODE_EXCLUSIVE is owned by some queue 9656family, the application must: perform a 9657<<synchronization-queue-transfers,queue family ownership transfer>> to make 9658the memory contents of a range or image subresource accessible to a 9659different queue family. 9660 9661[NOTE] 9662.Note 9663==== 9664Images still require a <<resources-image-layouts, layout transition>> from 9665ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED 9666before being used on the first queue. 9667==== 9668 9669A queue family can: take ownership of an image subresource or buffer range 9670of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an 9671ownership transfer, in the same way as for a resource that was just created; 9672however, taking ownership in this way has the effect that the contents of 9673the image subresource or buffer range are undefined:. 9674 9675Ranges of buffers and image subresources of image objects created using 9676ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the 9677queue families specified through the pname:queueFamilyIndexCount and 9678pname:pQueueFamilyIndices members of the corresponding create info 9679structures. 9680-- 9681 9682 9683ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 9684[[resources-external-sharing]] 9685=== External Resource Sharing 9686 9687Resources should: only be accessed in the Vulkan instance that has exclusive 9688ownership of their underlying memory. 9689Only one Vulkan instance has exclusive ownership of a resource's underlying 9690memory at a given time, regardless of whether the resource was created using 9691ename:VK_SHARING_MODE_EXCLUSIVE or ename:VK_SHARING_MODE_CONCURRENT. 9692Applications can transfer ownership of a resource's underlying memory only 9693if the memory has been imported from or exported to another instance or 9694external API using external memory handles. 9695The semantics for transferring ownership outside of the instance are similar 9696to those used for transferring ownership of ename:VK_SHARING_MODE_EXCLUSIVE 9697resources between queues, and is also accomplished using 9698slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier operations. 9699To make the contents of the underlying memory accessible in the destination 9700instance or API, applications must: 9701 9702 . Release exclusive ownership from the source instance or API. 9703 . Ensure the release operation has completed using semaphores or fences. 9704 . Acquire exclusive ownership in the destination instance or API 9705 9706Unlike queue ownership transfers, the destination instance or API is not 9707specified explicitly when releasing ownership, nor is the source instance or 9708API specified when acquiring ownership. 9709Instead, the image or memory barrier's pname:dstQueueFamilyIndex or 9710pname:srcQueueFamilyIndex parameters are set to the reserved queue family 9711index ename:VK_QUEUE_FAMILY_EXTERNAL 9712ifdef::VK_EXT_queue_family_foreign[] 9713or ename:VK_QUEUE_FAMILY_FOREIGN_EXT 9714endif::VK_EXT_queue_family_foreign[] 9715to represent the external destination or source respectively. 9716 9717Binding a resource to a memory object shared between multiple Vulkan 9718instances or other APIs does not change the ownership of the underlying 9719memory. 9720The first entity to access the resource implicitly acquires ownership. 9721An entity can: also implicitly take ownership from another entity in the 9722same way without an explicit ownership transfer. 9723However, taking ownership in this way has the effect that the contents of 9724the underlying memory are undefined:. 9725 9726Accessing a resource backed by memory that is owned by a particular instance 9727or API has the same semantics as accessing a ename:VK_SHARING_MODE_EXCLUSIVE 9728resource, with one exception: Implementations must: ensure layout 9729transitions performed on one member of a set of identical subresources of 9730identical images that alias the same range of an underlying memory object 9731affect the layout of all the subresources in the set. 9732 9733As a corollary, writes to any image subresources in such a set must: not 9734make the contents of memory used by other subresources in the set 9735undefined:. 9736An application can: define the content of a subresource of one image by 9737performing device writes to an identical subresource of another image 9738provided both images are bound to the same region of external memory. 9739Applications may: also add resources to such a set after the content of the 9740existing set members has been defined without making the content undefined: 9741by creating a new image with the initial layout 9742ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of 9743external memory as the existing images. 9744 9745[NOTE] 9746.Note 9747==== 9748Because layout transitions apply to all identical images aliasing the same 9749region of external memory, the actual layout of the memory backing a new 9750image as well as an existing image with defined content will not be 9751undefined:. 9752Such an image is not usable until it acquires ownership of its memory from 9753the existing owner. 9754Therefore, the layout specified as part of this transition will be the true 9755initial layout of the image. 9756The undefined: layout specified when creating it is a placeholder to 9757simplify valid usage requirements. 9758==== 9759endif::VK_VERSION_1_1,VK_KHR_external_memory[] 9760 9761 9762[[resources-memory-aliasing]] 9763== Memory Aliasing 9764 9765A range of a sname:VkDeviceMemory allocation is _aliased_ if it is bound to 9766multiple resources simultaneously, as described below, via 9767flink:vkBindImageMemory, flink:vkBindBufferMemory, 9768ifdef::VK_NV_ray_tracing[] 9769flink:vkBindAccelerationStructureMemoryNV, 9770endif::VK_NV_ray_tracing[] 9771ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] 9772or via <<sparsememory-resource-binding,sparse memory bindings>>. 9773endif::VK_VERSION_1_1,VK_KHR_external_memory[] 9774ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 9775ifndef::VKSC_VERSION_1_0[via <<sparsememory-resource-binding,sparse memory bindings>>,] 9776or by binding the memory to resources in multiple Vulkan instances or 9777external APIs using external memory handle export and import mechanisms. 9778endif::VK_VERSION_1_1,VK_KHR_external_memory[] 9779 9780Consider two resources, resource~A~ and resource~B~, bound respectively to 9781memory range~A~ and range~B~. 9782Let paddedRange~A~ and paddedRange~B~ be, respectively, range~A~ and 9783range~B~ aligned to pname:bufferImageGranularity. 9784If the resources are both linear or both non-linear (as defined in the 9785<<glossary-linear-resource,Glossary>>), then the resources _alias_ the 9786memory in the intersection of range~A~ and range~B~. 9787If one resource is linear and the other is non-linear, then the resources 9788_alias_ the memory in the intersection of paddedRange~A~ and paddedRange~B~. 9789 9790Applications can: alias memory, but use of multiple aliases is subject to 9791several constraints. 9792 9793[NOTE] 9794.Note 9795==== 9796Memory aliasing can: be useful to reduce the total device memory footprint 9797of an application, if some large resources are used for disjoint periods of 9798time. 9799==== 9800 9801When a <<glossary-linear-resource,non-linear>>, 9802non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased 9803range, all image subresources of the image _overlap_ the range. 9804When a linear image is bound to an aliased range, the image subresources 9805that (according to the image's advertised layout) include bytes from the 9806aliased range overlap the range. 9807When a ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image 9808blocks bound to an aliased range, only image subresources including those 9809sparse image blocks overlap the range, and when the memory bound to the 9810image's mip tail overlaps an aliased range all image subresources in the mip 9811tail overlap the range. 9812 9813Buffers, and linear image subresources in either the 9814ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL 9815layouts, are _host-accessible subresources_. 9816That is, the host has a well-defined addressing scheme to interpret the 9817contents, and thus the layout of the data in memory can: be consistently 9818interpreted across aliases if each of those aliases is a host-accessible 9819subresource. 9820Non-linear images, and linear image subresources in other layouts, are not 9821host-accessible. 9822 9823If two aliases are both host-accessible, then they interpret the contents of 9824the memory in consistent ways, and data written to one alias can: be read by 9825the other alias. 9826 9827ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9828[[resources-memory-aliasing-consistency]] 9829If two aliases are both images that were created with identical creation 9830parameters, both were created with the ename:VK_IMAGE_CREATE_ALIAS_BIT flag 9831set, and both are bound identically to memory 9832ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 9833except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices and 9834slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions, 9835endif::VK_VERSION_1_1,VK_KHR_device_group[] 9836then they interpret the contents of the memory in consistent ways, and data 9837written to one alias can: be read by the other alias. 9838 9839ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9840[[resources-memory-aliasing-consistency-planes]] 9841Additionally, if an individual plane of a multi-planar image and a 9842single-plane image alias the same memory, then they also interpret the 9843contents of the memory in consistent ways under the same conditions, but 9844with the following modifications: 9845 9846 * Both must: have been created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT 9847 flag. 9848 * The single-plane image must: have a elink:VkFormat that is 9849 <<formats-compatible-planes,equivalent>> to that of the multi-planar 9850 image's individual plane. 9851 * The single-plane image and the individual plane of the multi-planar 9852 image must: be bound identically to memory 9853ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 9854 except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices 9855 and 9856 slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions. 9857endif::VK_VERSION_1_1,VK_KHR_device_group[] 9858 * The pname:width and pname:height of the single-plane image are derived 9859 from the multi-planar image's dimensions in the manner listed for 9860 <<formats-compatible-planes,plane compatibility>> for the aliased plane. 9861ifdef::VK_EXT_image_drm_format_modifier[] 9862 * If either image's pname:tiling is 9863 ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must: be 9864 <<glossary-linear-resource,linear>>. 9865endif::VK_EXT_image_drm_format_modifier[] 9866 * All other creation parameters must: be identical 9867 9868endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 9869endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] 9870 9871ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 9872Aliases created by binding the same memory to resources in multiple Vulkan 9873instances or external APIs using external memory handle export and import 9874mechanisms interpret the contents of the memory in consistent ways, and data 9875written to one alias can: be read by the other alias. 9876endif::VK_VERSION_1_1,VK_KHR_external_memory[] 9877 9878Otherwise, the aliases interpret the contents of the memory differently, and 9879writes via one alias make the contents of memory partially or completely 9880undefined: to the other alias. 9881If the first alias is a host-accessible subresource, then the bytes affected 9882are those written by the memory operations according to its addressing 9883scheme. 9884If the first alias is not host-accessible, then the bytes affected are those 9885overlapped by the image subresources that were written. 9886If the second alias is a host-accessible subresource, the affected bytes 9887become undefined:. 9888If the second alias is not host-accessible, all sparse image blocks (for 9889sparse partially-resident images) or all image subresources (for non-sparse 9890image and fully resident sparse images) that overlap the affected bytes 9891become undefined:. 9892 9893If any image subresources are made undefined: due to writes to an alias, 9894then each of those image subresources must: have its layout transitioned 9895from ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or 9896from ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by 9897the host. 9898If any sparse blocks of a sparse image have been made undefined:, then only 9899the image subresources containing them must: be transitioned. 9900 9901Use of an overlapping range by two aliases must: be separated by a memory 9902dependency using the appropriate <<synchronization-access-types, access 9903types>> if at least one of those uses performs writes, whether the aliases 9904interpret memory consistently or not. 9905If buffer or image memory barriers are used, the scope of the barrier must: 9906contain the entire range and/or set of image subresources that overlap. 9907 9908If two aliasing image views are used in the same framebuffer, then the 9909render pass must: declare the attachments using the 9910<<renderpass-aliasing,ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT>>, and 9911follow the other rules listed in that section. 9912 9913[NOTE] 9914.Note 9915==== 9916Memory recycled via an application suballocator (i.e. without freeing and 9917reallocating the memory objects) is not substantially different from memory 9918aliasing. 9919However, a suballocator usually waits on a fence before recycling a region 9920of memory, and signaling a fence involves sufficient implicit dependencies 9921to satisfy all the above requirements. 9922==== 9923 9924[[resources-memory-overlap]] 9925=== Resource Memory Overlap 9926 9927Applications can: safely access a resource concurrently as long as the 9928memory locations do not overlap as defined in 9929<<memory-model-memory-location,Memory Location>>. 9930This includes aliased resources if such aliasing is well-defined. 9931It also includes access from different queues and/or queue families if such 9932concurrent access is supported by the resource. 9933Transfer commands only access memory locations specified by the range of the 9934transfer command. 9935 9936[NOTE] 9937.Note 9938==== 9939The intent is that buffers (or linear images) can be accessed concurrently, 9940even when they share cache lines, but otherwise do not access the same 9941memory range. 9942The concept of a device cache line size is not exposed in the memory model. 9943==== 9944 9945ifdef::VK_FUCHSIA_buffer_collection[] 9946[[resources-buffer-collection-fuchsia]] 9947== Buffer Collections 9948 9949[open,refpage='VkBufferCollectionFUCHSIA',desc='Opaque handle to a buffer collection object',type='handles'] 9950-- 9951Fuchsia's FIDL-based Sysmem service interoperates with Vulkan via the 9952`apiext:VK_FUCHSIA_buffer_collection` extension. 9953 9954A buffer collection is a set of one or more buffers which were allocated 9955together as a group and which all have the same properties. 9956These properties describe the buffers' internal representation, such as its 9957dimensions and memory layout. 9958This ensures that all of the buffers can be used interchangeably by tasks 9959that require swapping among multiple buffers, such as double-buffered 9960graphics rendering. 9961 9962On Fuchsia, the Sysmem service uses buffer collections as a core construct 9963in its design. 9964 9965Buffer collections are represented by sname:VkBufferCollectionFUCHSIA 9966handles: 9967 9968include::{generated}/api/handles/VkBufferCollectionFUCHSIA.adoc[] 9969-- 9970 9971 9972=== Definitions 9973 9974 * FIDL - Fuchsia Interface Definition Language. 9975 The declarative language used to define FIDL interprocess communication 9976 interfaces on Fuchsia. 9977 FIDL files use the `fidl` extension. 9978 FIDL is also used to refer to the services defined by interfaces 9979 declared in the FIDL language 9980 * Sysmem - The FIDL service that facilitates optimal buffer sharing and 9981 reuse on Fuchsia 9982 * client - Any participant of the buffer collection e.g. the Vulkan 9983 application 9984 * token - A code:zx_handle_t Zircon channel object that allows 9985 participation in the buffer collection 9986 9987 9988=== Platform Initialization for Buffer Collections 9989To initialize a buffer collection on Fuchsia: 9990 9991 * Connect to the Sysmem service to initialize a Sysmem allocator 9992 * Create an initial buffer collection token using the Sysmem allocator 9993 * Duplicate the token for each participant beyond the initiator 9994 * See the Sysmem Overview and fuchsia.sysmem FIDL documentation on 9995 fuchsia.dev for more detailed information 9996 9997 9998=== Create the Buffer Collection 9999 10000[open,refpage='vkCreateBufferCollectionFUCHSIA',desc='Create a new buffer collection',type='protos'] 10001-- 10002To create an slink:VkBufferCollectionFUCHSIA for Vulkan to participate in 10003the buffer collection: 10004 10005include::{generated}/api/protos/vkCreateBufferCollectionFUCHSIA.adoc[] 10006 10007 * pname:device is the logical device that creates the 10008 sname:VkBufferCollectionFUCHSIA 10009 * pname:pCreateInfo is a pointer to a 10010 slink:VkBufferCollectionCreateInfoFUCHSIA structure containing 10011 parameters affecting creation of the buffer collection 10012 * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure 10013 controlling host memory allocation as described in the 10014 <<memory-allocation, Memory Allocation>> chapter 10015 * pname:pBufferCollection is a pointer to a 10016 slink:VkBufferCollectionFUCHSIA handle in which the resulting buffer 10017 collection object is returned 10018 10019include::{generated}/validity/protos/vkCreateBufferCollectionFUCHSIA.adoc[] 10020 10021.Host Access 10022**** 10023All functions referencing a slink:VkBufferCollectionFUCHSIA must: be 10024externally synchronized with the exception of 10025fname:vkCreateBufferCollectionFUCHSIA. 10026**** 10027-- 10028 10029 10030[open,refpage='VkBufferCollectionCreateInfoFUCHSIA',desc='Structure specifying desired parameters to create the buffer collection',type='structs'] 10031-- 10032The sname:VkBufferCollectionCreateInfoFUCHSIA structure is defined as: 10033 10034include::{generated}/api/structs/VkBufferCollectionCreateInfoFUCHSIA.adoc[] 10035 10036 * pname:sType is a elink:VkStructureType value identifying this structure. 10037 * pname:pNext is `NULL` or a pointer to a structure extending this 10038 structure 10039 * pname:collectionToken is a fname:zx_handle_t containing the Sysmem 10040 client's buffer collection token 10041 10042.Valid Usage 10043**** 10044 * [[VUID-VkBufferCollectionCreateInfoFUCHSIA-collectionToken-06393]] 10045 pname:collectionToken must: be a valid code:zx_handle_t to a Zircon 10046 channel allocated from Sysmem 10047 (code:fuchsia.sysmem.Allocator/AllocateSharedCollection) with 10048 code:ZX_DEFAULT_CHANNEL_RIGHTS rights 10049**** 10050 10051include::{generated}/validity/structs/VkBufferCollectionCreateInfoFUCHSIA.adoc[] 10052-- 10053 10054 10055=== Set the Constraints 10056Buffer collections can be established for slink:VkImage allocations or 10057slink:VkBuffer allocations. 10058 10059 10060==== Set Image-based Buffer Collection Constraints 10061 10062[open,refpage='vkSetBufferCollectionImageConstraintsFUCHSIA',desc='Set image-based constraints for a buffer collection',type='protos'] 10063-- 10064Setting the constraints on the buffer collection initiates the format 10065negotiation and allocation of the buffer collection. 10066To set the constraints on a slink:VkImage buffer collection, call: 10067 10068include::{generated}/api/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.adoc[] 10069 10070 * pname:device is the logical device 10071 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 10072 * pname:pImageConstraintsInfo is a pointer to a 10073 slink:VkImageConstraintsInfoFUCHSIA structure 10074 10075fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if 10076pname:pImageConstraintsInfo->formatConstraintsCount is larger than the 10077implementation-defined limit. 10078If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will 10079return ename:VK_ERROR_INITIALIZATION_FAILED. 10080 10081fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if the 10082implementation does not support any of the formats described by the 10083pname:pImageConstraintsInfo structure. 10084If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will 10085return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 10086 10087.Valid Usage 10088**** 10089 * [[VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-06394]] 10090 fname:vkSetBufferCollectionImageConstraintsFUCHSIA or 10091 fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have 10092 already been called on pname:collection 10093**** 10094 10095include::{generated}/validity/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.adoc[] 10096-- 10097 10098[open,refpage='VkImageConstraintsInfoFUCHSIA',desc='Structure of image-based buffer collection constraints',type='structs'] 10099-- 10100The sname:VkImageConstraintsInfoFUCHSIA structure is defined as: 10101 10102include::{generated}/api/structs/VkImageConstraintsInfoFUCHSIA.adoc[] 10103 10104 * pname:sType is a elink:VkStructureType value identifying this structure. 10105 * pname:pNext is `NULL` or a pointer to a structure extending this 10106 structure. 10107 * pname:formatConstraintsCount is the number of elements in 10108 pname:pFormatConstraints. 10109 * pname:pFormatConstraints is a pointer to an array of 10110 slink:VkImageFormatConstraintsInfoFUCHSIA structures of size 10111 pname:formatConstraintsCount that is used to further constrain buffer 10112 collection format selection for image-based buffer collections. 10113 * pname:bufferCollectionConstraints is a 10114 slink:VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply 10115 parameters for the negotiation and allocation for buffer-based buffer 10116 collections. 10117 * pname:flags is a elink:VkImageConstraintsInfoFlagBitsFUCHSIA value 10118 specifying hints about the type of memory Sysmem should allocate for the 10119 buffer collection. 10120 10121.Valid Usage 10122**** 10123 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06395]] 10124 All elements of pname:pFormatConstraints must: have at least one bit set 10125 in its 10126 slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures 10127 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06396]] 10128 If pname:pFormatConstraints->imageCreateInfo->usage contains 10129 ename:VK_IMAGE_USAGE_SAMPLED_BIT, then 10130 pname:pFormatConstraints->requiredFormatFeatures must: contain 10131 ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT 10132 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06397]] 10133 If pname:pFormatConstraints->imageCreateInfo->usage contains 10134 ename:VK_IMAGE_USAGE_STORAGE_BIT, then 10135 pname:pFormatConstraints->requiredFormatFeatures must: contain 10136 ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT 10137 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06398]] 10138 If pname:pFormatConstraints->imageCreateInfo->usage contains 10139 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then 10140 pname:pFormatConstraints->requiredFormatFeatures must: contain 10141 ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 10142 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06399]] 10143 If pname:pFormatConstraints->imageCreateInfo->usage contains 10144 ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then 10145 pname:pFormatConstraints->requiredFormatFeatures must: contain 10146 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 10147 * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06400]] 10148 If pname:pFormatConstraints->imageCreateInfo->usage contains 10149 ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then 10150 pname:pFormatConstraints->requiredFormatFeatures must: contain at least 10151 one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or 10152 ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT 10153ifdef::VK_KHR_fragment_shading_rate[] 10154 * [[VUID-VkImageConstraintsInfoFUCHSIA-attachmentFragmentShadingRate-06401]] 10155 If the <<features-attachmentFragmentShadingRate, 10156 pname:attachmentFragmentShadingRate>> feature is enabled, and 10157 pname:pFormatConstraints->imageCreateInfo->usage contains 10158 ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then 10159 pname:pFormatConstraints->requiredFormatFeatures must: contain 10160 ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR 10161endif::VK_KHR_fragment_shading_rate[] 10162**** 10163 10164include::{generated}/validity/structs/VkImageConstraintsInfoFUCHSIA.adoc[] 10165-- 10166 10167[open,refpage='VkImageConstraintsInfoFlagsFUCHSIA',desc='Reserved for future use',type='flags'] 10168-- 10169include::{generated}/api/flags/VkImageConstraintsInfoFlagsFUCHSIA.adoc[] 10170 10171tname:VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a 10172mask of zero or more elink:VkImageConstraintsInfoFlagBitsFUCHSIA bits. 10173-- 10174 10175[open,refpage='VkImageConstraintsInfoFlagBitsFUCHSIA',desc='Bitmask specifying image constraints flags',type='enums'] 10176-- 10177Bits which can: be set in 10178elink:VkImageConstraintsInfoFlagBitsFUCHSIA::pname:flags include: 10179 10180include::{generated}/api/enums/VkImageConstraintsInfoFlagBitsFUCHSIA.adoc[] 10181 10182General hints about the type of memory that should be allocated by Sysmem 10183based on the expected usage of the images in the buffer collection include: 10184 10185 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA 10186 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA 10187 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA 10188 * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA 10189 10190For protected memory: 10191 10192 * ename:VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA specifies 10193 that protected memory is optional for the buffer collection. 10194 10195Note that if all participants in the buffer collection (Vulkan or otherwise) 10196specify that protected memory is optional, Sysmem will not allocate 10197protected memory. 10198-- 10199 10200[open,refpage='VkImageFormatConstraintsInfoFUCHSIA',desc='Structure image-based buffer collection constraints',type='structs'] 10201-- 10202The sname:VkImageFormatConstraintsInfoFUCHSIA structure is defined as: 10203 10204include::{generated}/api/structs/VkImageFormatConstraintsInfoFUCHSIA.adoc[] 10205 10206 * pname:sType is a elink:VkStructureType value identifying this structure. 10207 * pname:pNext is `NULL` or a pointer to a structure extending this 10208 structure 10209 * pname:imageCreateInfo is the slink:VkImageCreateInfo used to create a 10210 slink:VkImage that is to use memory from the 10211 slink:VkBufferCollectionFUCHSIA 10212 * pname:requiredFormatFeatures is a bitmask of 10213 ename:VkFormatFeatureFlagBits specifying required features of the 10214 buffers in the buffer collection 10215 * pname:flags is reserved for future use 10216 * pname:sysmemPixelFormat is a code:PixelFormatType value from the 10217 `fuchsia.sysmem/image_formats.fidl` FIDL interface 10218 * pname:colorSpaceCount the element count of pname:pColorSpaces 10219 * pname:pColorSpaces is a pointer to an array of 10220 slink:VkSysmemColorSpaceFUCHSIA structs of size pname:colorSpaceCount 10221 10222include::{generated}/validity/structs/VkImageFormatConstraintsInfoFUCHSIA.adoc[] 10223-- 10224 10225[open,refpage='VkImageFormatConstraintsFlagsFUCHSIA',desc='Reserved for future use',type='flags'] 10226-- 10227include::{generated}/api/flags/VkImageFormatConstraintsFlagsFUCHSIA.adoc[] 10228 10229tname:VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a 10230mask, but is currently reserved for future use. 10231-- 10232 10233[open,refpage='VkBufferCollectionConstraintsInfoFUCHSIA',desc='Structure of general buffer collection constraints',type='structs'] 10234-- 10235The sname:VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as: 10236 10237include::{generated}/api/structs/VkBufferCollectionConstraintsInfoFUCHSIA.adoc[] 10238 10239 * pname:sType is a elink:VkStructureType value identifying this structure. 10240 * pname:pNext is `NULL` or a pointer to a structure extending this 10241 structure 10242 * pname:minBufferCount is the minimum number of buffers available in the 10243 collection 10244 * pname:maxBufferCount is the maximum number of buffers allowed in the 10245 collection 10246 * pname:minBufferCountForCamping is the per-participant minimum buffers 10247 for camping 10248 * pname:minBufferCountForDedicatedSlack is the per-participant minimum 10249 buffers for dedicated slack 10250 * pname:minBufferCountForSharedSlack is the per-participant minimum 10251 buffers for shared slack 10252 10253Sysmem uses all buffer count parameters in combination to determine the 10254number of buffers it will allocate. 10255Sysmem defines buffer count constraints in 10256`fuchsia.sysmem/constraints.fidl`. 10257 10258_Camping_ as referred to by pname:minBufferCountForCamping, is the number of 10259buffers that should be available for the participant that are not for 10260transient use. 10261This number of buffers is required for the participant to logically operate. 10262 10263_Slack_ as referred to by pname:minBufferCountForDedicatedSlack and 10264pname:minBufferCountForSharedSlack, refers to the number of buffers desired 10265by participants for optimal performance. 10266pname:minBufferCountForDedicatedSlack refers to the current participant. 10267pname:minBufferCountForSharedSlack refers to buffer slack for all 10268participants in the collection. 10269 10270include::{generated}/validity/structs/VkBufferCollectionConstraintsInfoFUCHSIA.adoc[] 10271-- 10272 10273[open,refpage='VkSysmemColorSpaceFUCHSIA',desc='Structure describing the buffer collections color space',type='structs'] 10274-- 10275The sname:VkSysmemColorSpaceFUCHSIA structure is defined as: 10276 10277include::{generated}/api/structs/VkSysmemColorSpaceFUCHSIA.adoc[] 10278 10279 * pname:sType is a elink:VkStructureType value identifying this structure. 10280 * pname:pNext is `NULL` or a pointer to a structure extending this 10281 structure 10282 * pname:colorSpace value of the Sysmem code:ColorSpaceType 10283 10284.Valid Usage 10285**** 10286 * [[VUID-VkSysmemColorSpaceFUCHSIA-colorSpace-06402]] 10287 pname:colorSpace must: be a code:ColorSpaceType as defined in 10288 `fuchsia.sysmem/image_formats.fidl` 10289**** 10290 10291include::{generated}/validity/structs/VkSysmemColorSpaceFUCHSIA.adoc[] 10292-- 10293 10294 10295==== Set Buffer-based Buffer Collection Constraints 10296 10297[open,refpage='vkSetBufferCollectionBufferConstraintsFUCHSIA',desc='Set buffer-based constraints for a buffer collection',type='protos'] 10298-- 10299To set the constraints on a slink:VkBuffer buffer collection, call: 10300 10301include::{generated}/api/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.adoc[] 10302 10303 * pname:device is the logical device 10304 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 10305 * pname:pBufferConstraintsInfo is a pointer to a 10306 slink:VkBufferConstraintsInfoFUCHSIA structure 10307 10308fname:vkSetBufferCollectionBufferConstraintsFUCHSIA may: fail if the 10309implementation does not support the constraints specified in the 10310pname:bufferCollectionConstraints structure. 10311If that occurs, flink:vkSetBufferCollectionBufferConstraintsFUCHSIA will 10312return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. 10313 10314.Valid Usage 10315**** 10316 * [[VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-06403]] 10317 fname:vkSetBufferCollectionImageConstraintsFUCHSIA or 10318 fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have 10319 already been called on pname:collection 10320**** 10321 10322include::{generated}/validity/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.adoc[] 10323-- 10324 10325[open,refpage='VkBufferConstraintsInfoFUCHSIA',desc='Structure buffer-based buffer collection constraints',type='structs'] 10326-- 10327The sname:VkBufferConstraintsInfoFUCHSIA structure is defined as: 10328 10329include::{generated}/api/structs/VkBufferConstraintsInfoFUCHSIA.adoc[] 10330 10331 * pname:sType is a elink:VkStructureType value identifying this structure. 10332 * pname:pNext is `NULL` or a pointer to a structure extending this 10333 structure 10334 * pname:pBufferCreateInfo a pointer to a slink:VkBufferCreateInfo struct 10335 describing the buffer attributes for the buffer collection 10336 * pname:requiredFormatFeatures bitmask of ename:VkFormatFeatureFlagBits 10337 required features of the buffers in the buffer collection 10338 * pname:bufferCollectionConstraints is used to supply parameters for the 10339 negotiation and allocation of the buffer collection 10340 10341.Valid Usage 10342**** 10343 * [[VUID-VkBufferConstraintsInfoFUCHSIA-requiredFormatFeatures-06404]] 10344 The pname:requiredFormatFeatures bitmask of 10345 ename:VkFormatFeatureFlagBits must: be chosen from among the buffer 10346 compatible format features listed in 10347 <<buffer-compatible-format-features,buffer compatible format features>> 10348**** 10349 10350include::{generated}/validity/structs/VkBufferConstraintsInfoFUCHSIA.adoc[] 10351-- 10352 10353 10354=== Retrieve Buffer Collection Properties 10355 10356[open,refpage='vkGetBufferCollectionPropertiesFUCHSIA',desc='Retrieve properties from a buffer collection',type='protos'] 10357-- 10358After constraints have been set on the buffer collection by calling 10359flink:vkSetBufferCollectionImageConstraintsFUCHSIA or 10360flink:vkSetBufferCollectionBufferConstraintsFUCHSIA, call 10361fname:vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and 10362finalized properties of the buffer collection. 10363 10364The call to fname:vkGetBufferCollectionPropertiesFUCHSIA is synchronous. 10365It waits for the Sysmem format negotiation and buffer collection allocation 10366to complete before returning. 10367 10368include::{generated}/api/protos/vkGetBufferCollectionPropertiesFUCHSIA.adoc[] 10369 10370 * pname:device is the logical device handle 10371 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 10372 * pname:pProperties is a pointer to the retrieved 10373 slink:VkBufferCollectionPropertiesFUCHSIA struct 10374 10375[[sysmem-chosen-create-infos]] 10376For image-based buffer collections, upon calling 10377fname:vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element 10378of the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos 10379established by the preceding call to 10380flink:vkSetBufferCollectionImageConstraintsFUCHSIA. 10381The index of the element chosen is stored in and can be retrieved from 10382slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex. 10383 10384For buffer-based buffer collections, a single slink:VkBufferCreateInfo is 10385specified as slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo. 10386slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex will 10387therefore always be zero. 10388 10389fname:vkGetBufferCollectionPropertiesFUCHSIA may: fail if Sysmem is unable 10390to resolve the constraints of all of the participants in the buffer 10391collection. 10392If that occurs, fname:vkGetBufferCollectionPropertiesFUCHSIA will return 10393ename:VK_ERROR_INITIALIZATION_FAILED. 10394 10395.Valid Usage 10396**** 10397 * [[VUID-vkGetBufferCollectionPropertiesFUCHSIA-None-06405]] 10398 Prior to calling flink:vkGetBufferCollectionPropertiesFUCHSIA, the 10399 constraints on the buffer collection must: have been set by either 10400 flink:vkSetBufferCollectionImageConstraintsFUCHSIA or 10401 flink:vkSetBufferCollectionBufferConstraintsFUCHSIA 10402**** 10403 10404include::{generated}/validity/protos/vkGetBufferCollectionPropertiesFUCHSIA.adoc[] 10405-- 10406 10407[open,refpage='VkBufferCollectionPropertiesFUCHSIA',desc='Structure specifying the negotiated format chosen by Sysmem',type='structs'] 10408-- 10409The sname:VkBufferCollectionPropertiesFUCHSIA structure is defined as: 10410 10411include::{generated}/api/structs/VkBufferCollectionPropertiesFUCHSIA.adoc[] 10412 10413 * pname:sType is a elink:VkStructureType value identifying this structure. 10414 * pname:pNext is `NULL` or a pointer to a structure extending this 10415 structure 10416 * pname:memoryTypeBits is a bitmask containing one bit set for every 10417 memory type which the buffer collection can be imported as buffer 10418 collection 10419 * pname:bufferCount is the number of buffers in the collection 10420 * pname:createInfoIndex as described in <<sysmem-chosen-create-infos, 10421 Sysmem chosen create infos>> 10422 * pname:sysmemPixelFormat is the Sysmem code:PixelFormatType as defined in 10423 `fuchsia.sysmem/image_formats.fidl` 10424 * pname:formatFeatures is a bitmask of elink:VkFormatFeatureFlagBits 10425 shared by the buffer collection 10426 * pname:sysmemColorSpaceIndex is a slink:VkSysmemColorSpaceFUCHSIA struct 10427 specifying the color space 10428 * pname:samplerYcbcrConversionComponents is a slink:VkComponentMapping 10429 struct specifying the component mapping 10430 * pname:suggestedYcbcrModel is a elink:VkSamplerYcbcrModelConversion value 10431 specifying the suggested {YCbCr} model 10432 * pname:suggestedYcbcrRange is a elink:VkSamplerYcbcrRange value 10433 specifying the suggested {YCbCr} range 10434 * pname:suggestedXChromaOffset is a elink:VkChromaLocation value 10435 specifying the suggested X chroma offset 10436 * pname:suggestedYChromaOffset is a elink:VkChromaLocation value 10437 specifying the suggested Y chroma offset 10438 10439pname:sysmemColorSpace is only set for image-based buffer collections where 10440the constraints were specified using slink:VkImageConstraintsInfoFUCHSIA in 10441a call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA. 10442 10443For image-based buffer collections, pname:createInfoIndex will identify both 10444the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos element and 10445the slink:VkImageConstraintsInfoFUCHSIA::pname:pFormatConstraints element 10446chosen by Sysmem when flink:vkSetBufferCollectionImageConstraintsFUCHSIA was 10447called. 10448The value of pname:sysmemColorSpaceIndex will be an index to one of the 10449color spaces provided in the 10450slink:VkImageFormatConstraintsInfoFUCHSIA::pname:pColorSpaces array. 10451 10452The implementation must have pname:formatFeatures with all bits set that 10453were set in 10454slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures, by 10455the call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA, at 10456pname:createInfoIndex (other bits could be set as well). 10457 10458include::{generated}/validity/structs/VkBufferCollectionPropertiesFUCHSIA.adoc[] 10459-- 10460 10461 10462=== Memory Allocation 10463 10464To import memory from a buffer collection into a slink:VkImage or a 10465slink:VkBuffer, chain a slink:VkImportMemoryBufferCollectionFUCHSIA 10466structure to the pname:pNext member of the slink:VkMemoryAllocateInfo in the 10467call to flink:vkAllocateMemory. 10468 10469[open,refpage='VkImportMemoryBufferCollectionFUCHSIA',desc='Structure to specify the Sysmem buffer to import',type='structs'] 10470-- 10471The sname:VkImportMemoryBufferCollectionFUCHSIA structure is defined as: 10472 10473include::{generated}/api/structs/VkImportMemoryBufferCollectionFUCHSIA.adoc[] 10474 10475 * pname:sType is a elink:VkStructureType value identifying this structure. 10476 * pname:pNext is `NULL` or a pointer to a structure extending this 10477 structure 10478 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 10479 * pname:index the index of the buffer to import from pname:collection 10480 10481.Valid Usage 10482**** 10483 * [[VUID-VkImportMemoryBufferCollectionFUCHSIA-index-06406]] 10484 pname:index must: be less than the value retrieved as 10485 slink:VkBufferCollectionPropertiesFUCHSIA:bufferCount 10486**** 10487 10488include::{generated}/validity/structs/VkImportMemoryBufferCollectionFUCHSIA.adoc[] 10489-- 10490 10491[open,refpage='vkDestroyBufferCollectionFUCHSIA',desc='Destroy a buffer collection',type='protos'] 10492-- 10493To release a slink:VkBufferCollectionFUCHSIA: 10494 10495include::{generated}/api/protos/vkDestroyBufferCollectionFUCHSIA.adoc[] 10496 10497 * pname:device is the logical device that creates the 10498 sname:VkBufferCollectionFUCHSIA 10499 * pname:collection is the slink:VkBufferCollectionFUCHSIA handle 10500 * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure 10501 controlling host memory allocation as described in the 10502 <<memory-allocation, Memory Allocation>> chapter 10503 10504.Valid Usage 10505**** 10506 * [[VUID-vkDestroyBufferCollectionFUCHSIA-collection-06407]] 10507 slink:VkImage and slink:VkBuffer objects that referenced 10508 pname:collection upon creation by inclusion of a 10509 slink:VkBufferCollectionImageCreateInfoFUCHSIA or 10510 slink:VkBufferCollectionBufferCreateInfoFUCHSIA chained to their 10511 slink:VkImageCreateInfo or slink:VkBufferCreateInfo structures 10512 respectively, may: outlive pname:collection 10513**** 10514 10515include::{generated}/validity/protos/vkDestroyBufferCollectionFUCHSIA.adoc[] 10516-- 10517endif::VK_FUCHSIA_buffer_collection[] 10518