1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[descriptorsets]] 6= Resource Descriptors 7 8A _descriptor_ is an opaque data structure representing a shader resource 9such as a buffer, buffer view, image view, sampler, or combined image 10sampler. 11Descriptors are organised into _descriptor sets_, which are bound during 12command recording for use in subsequent drawing commands. 13The arrangement of content in each descriptor set is determined by a 14_descriptor set layout_, which determines what descriptors can be stored 15within it. 16The sequence of descriptor set layouts that can: be used by a pipeline is 17specified in a _pipeline layout_. 18Each pipeline object can: use up to pname:maxBoundDescriptorSets (see 19<<limits, Limits>>) descriptor sets. 20 21Shaders access resources via variables decorated with a descriptor set and 22binding number that link them to a descriptor in a descriptor set. 23The shader interface mapping to bound descriptor sets is described in the 24<<interfaces-resources, Shader Resource Interface>> section. 25 26ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 27Shaders can: also access buffers without going through descriptors by using 28<<descriptorsets-physical-storage-buffer,Physical Storage Buffer Access>> to 29access them through 64-bit addresses. 30endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 31 32 33[[descriptorsets-types]] 34== Descriptor Types 35 36There are a number of different types of descriptor supported by Vulkan, 37corresponding to different resources or usage. 38The following sections describe the API definitions of each descriptor type. 39The mapping of each type to SPIR-V is listed in the 40<<interfaces-resources-correspondence, Shader Resource and Descriptor Type 41Correspondence>> and <<interfaces-resources-storage-class-correspondence, 42Shader Resource and Storage Class Correspondence>> tables in the 43<<interfaces, Shader Interfaces>> chapter. 44 45 46[[descriptorsets-storageimage]] 47=== Storage Image 48 49A _storage image_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE) is a descriptor 50type associated with an <<resources-images, image resource>> via an 51<<resources-image-views, image view>> that load, store, and atomic 52operations can: be performed on. 53 54Storage image loads are supported in all shader stages for image views whose 55<<resources-image-view-format-features,format features>> contain 56<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 57 58Stores to storage images are supported in compute shaders for image views 59whose <<resources-image-view-format-features,format features>> contain 60<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 61 62Atomic operations on storage images are supported in compute shaders for 63image views whose <<resources-image-view-format-features,format features>> 64contain 65<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT>>. 66 67When the <<features-fragmentStoresAndAtomics, 68pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 69operations are also supported for storage images in fragment shaders with 70the same set of image formats as supported in compute shaders. 71When the <<features-vertexPipelineStoresAndAtomics, 72pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 73operations are also supported in vertex, tessellation, and geometry shaders 74with the same set of image formats as supported in compute shaders. 75 76The image subresources for a storage image must: be in the 77ifdef::VK_KHR_shared_presentable_image[] 78ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 79endif::VK_KHR_shared_presentable_image[] 80ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 81shader. 82 83 84[[descriptorsets-sampler]] 85=== Sampler 86 87A _sampler descriptor_ (ename:VK_DESCRIPTOR_TYPE_SAMPLER) is a descriptor 88type associated with a <<samplers,sampler>> object, used to control the 89behavior of <<textures,sampling operations>> performed on a 90<<descriptorsets-sampledimage, sampled image>>. 91 92 93[[descriptorsets-sampledimage]] 94=== Sampled Image 95 96A _sampled image_ (ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE) is a descriptor 97type associated with an <<resources-images, image resource>> via an 98<<resources-image-views, image view>> that <<textures,sampling operations>> 99can: be performed on. 100 101Shaders combine a sampled image variable and a sampler variable to perform 102sampling operations. 103 104Sampled images are supported in all shader stages for image views whose 105<<resources-image-view-format-features,format features>> contain 106<<formats-properties,ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT>>. 107 108The image subresources for a sampled image must: be in the 109ifdef::VK_KHR_shared_presentable_image[] 110ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 111endif::VK_KHR_shared_presentable_image[] 112ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 113ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 114ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 115endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 116ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 117ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 118ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, 119endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 120ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 121ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 122ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 123shader. 124 125 126[[descriptorsets-combinedimagesampler]] 127=== Combined Image Sampler 128 129A _combined image sampler_ (ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER) 130is a single descriptor type associated with both a <<samplers,sampler>> and 131an <<resources-images,image resource>>, combining both a 132<<descriptorsets-sampler,sampler>> and <<descriptorsets-sampledimage, 133sampled image>> descriptor into a single descriptor. 134 135ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 136If the descriptor refers to a sampler that performs 137ifndef::VK_EXT_fragment_density_map[] 138<<samplers-YCbCr-conversion,{YCbCr} conversion>>, 139endif::VK_EXT_fragment_density_map[] 140ifdef::VK_EXT_fragment_density_map[] 141<<samplers-YCbCr-conversion,{YCbCr} conversion>> or samples a 142<<samplers-subsamplesampler,subsampled image>>, 143endif::VK_EXT_fragment_density_map[] 144the sampler must: only be used to sample the image in the same descriptor. 145Otherwise, the 146endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 147ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 148ifndef::VK_EXT_fragment_density_map[] 149The 150endif::VK_EXT_fragment_density_map[] 151ifdef::VK_EXT_fragment_density_map[] 152If the descriptor refers to a sampler that samples a 153<<samplers-subsamplesampler,subsampled image>>, the sampler must: only be 154used to sample the image in the same descriptor. 155Otherwise, the 156endif::VK_EXT_fragment_density_map[] 157endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 158sampler and image in this type of descriptor can: be used freely with any 159other samplers and images. 160 161The image subresources for a combined image sampler must: be in the 162ifdef::VK_KHR_shared_presentable_image[] 163ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 164endif::VK_KHR_shared_presentable_image[] 165ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 166ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 167ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 168endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 169ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 170ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL, 171ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL, 172endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 173ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 174ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 175ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 176shader. 177 178[NOTE] 179.Note 180==== 181On some implementations, it may: be more efficient to sample from an image 182using a combination of sampler and sampled image that are stored together in 183the descriptor set in a combined descriptor. 184==== 185 186 187[[descriptorsets-uniformtexelbuffer]] 188=== Uniform Texel Buffer 189 190A _uniform texel buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER) is 191a descriptor type associated with a <<resources-buffers,buffer resource>> 192via a <<resources-buffer-views, buffer view>> that <<textures,formatted load 193operations>> can: be performed on. 194 195Uniform texel buffers define a tightly-packed 1-dimensional linear array of 196texels, with texels going through format conversion when read in a shader in 197the same way as they are for an image. 198 199Load operations from uniform texel buffers are supported in all shader 200stages for image formats which report support for the 201<<formats-properties,ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT>> 202feature bit via flink:vkGetPhysicalDeviceFormatProperties in 203slink:VkFormatProperties::pname:bufferFeatures. 204 205 206[[descriptorsets-storagetexelbuffer]] 207=== Storage Texel Buffer 208 209A _storage texel buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER) is 210a descriptor type associated with a <<resources-buffers,buffer resource>> 211via a <<resources-buffer-views, buffer view>> that <<textures,formatted 212load, store, and atomic operations>> can: be performed on. 213 214Storage texel buffers define a tightly-packed 1-dimensional linear array of 215texels, with texels going through format conversion when read in a shader in 216the same way as they are for an image. 217Unlike <<descriptorsets-uniformtexelbuffer,uniform texel buffers>>, these 218buffers can also be written to in the same way as for 219<<descriptorsets-storageimage, storage images>>. 220 221Storage texel buffer loads are supported in all shader stages for texel 222buffer formats which report support for the 223<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT>> 224feature bit via flink:vkGetPhysicalDeviceFormatProperties in 225slink:VkFormatProperties::pname:bufferFeatures. 226 227Stores to storage texel buffers are supported in compute shaders for texel 228buffer formats which report support for the 229ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT feature via 230flink:vkGetPhysicalDeviceFormatProperties in 231slink:VkFormatProperties::pname:bufferFeatures. 232 233Atomic operations on storage texel buffers are supported in compute shaders 234for texel buffer formats which report support for the 235<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT>> 236feature via flink:vkGetPhysicalDeviceFormatProperties in 237slink:VkFormatProperties::pname:bufferFeatures. 238 239When the <<features-fragmentStoresAndAtomics, 240pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 241operations are also supported for storage texel buffers in fragment shaders 242with the same set of texel buffer formats as supported in compute shaders. 243When the <<features-vertexPipelineStoresAndAtomics, 244pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 245operations are also supported in vertex, tessellation, and geometry shaders 246with the same set of texel buffer formats as supported in compute shaders. 247 248 249[[descriptorsets-storagebuffer]] 250=== Storage Buffer 251 252A _storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER) is a descriptor 253type associated with a <<resources-buffers,buffer resource>> directly, 254described in a shader as a structure with various members that load, store, 255and atomic operations can: be performed on. 256 257[NOTE] 258.Note 259==== 260Atomic operations can: only be performed on members of certain types as 261defined in the <<spirvenv, SPIR-V environment appendix>>. 262==== 263 264 265[[descriptorsets-uniformbuffer]] 266=== Uniform Buffer 267 268A _uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER) is a descriptor 269type associated with a <<resources-buffers,buffer resource>> directly, 270described in a shader as a structure with various members that load 271operations can: be performed on. 272 273 274[[descriptorsets-uniformbufferdynamic]] 275=== Dynamic Uniform Buffer 276 277A _dynamic uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC) 278is almost identical to a <<descriptorsets-uniformbuffer, uniform buffer>>, 279and differs only in how the offset into the buffer is specified. 280The base offset calculated by the slink:VkDescriptorBufferInfo when 281initially <<descriptorsets-updates, updating the descriptor set>> is added 282to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 283the descriptor set. 284 285 286[[descriptorsets-storagebufferdynamic]] 287=== Dynamic Storage Buffer 288 289A _dynamic storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC) 290is almost identical to a <<descriptorsets-storagebuffer, storage buffer>>, 291and differs only in how the offset into the buffer is specified. 292The base offset calculated by the slink:VkDescriptorBufferInfo when 293initially <<descriptorsets-updates, updating the descriptor set>> is added 294to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 295the descriptor set. 296 297 298ifdef::VK_EXT_inline_uniform_block[] 299 300[[descriptorsets-inlineuniformblock]] 301=== Inline Uniform Block 302 303An _inline uniform block_ 304(ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT) is almost identical to a 305<<descriptorsets-uniformbuffer, uniform buffer>>, and differs only in taking 306its storage directly from the encompassing descriptor set instead of being 307backed by buffer memory. 308It is typically used to access a small set of constant data that does not 309require the additional flexibility provided by the indirection enabled when 310using a uniform buffer where the descriptor and the referenced buffer memory 311are decoupled. 312Compared to push constants, they allow reusing the same set of constant data 313across multiple disjoint sets of drawing and dispatching commands. 314 315Inline uniform block descriptors cannot: be aggregated into arrays. 316Instead, the array size specified for an inline uniform block descriptor 317binding specifies the binding's capacity in bytes. 318 319endif::VK_EXT_inline_uniform_block[] 320 321 322[[descriptorsets-inputattachment]] 323=== Input Attachment 324 325An _input attachment_ (ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT) is a 326descriptor type associated with an <<resources-images, image resource>> via 327an <<resources-image-views, image view>> that can: be used for 328<<synchronization-framebuffer-regions,framebuffer local>> load operations in 329fragment shaders. 330 331All image formats that are supported for color attachments 332(ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT) or depth/stencil attachments 333(ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT) for a given image 334tiling mode are also supported for input attachments. 335 336The image subresources for an input attachment must: be in a 337<<attachment-type-imagelayout, valid image layout>> in order to access its 338data in a shader. 339 340ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 341[[descriptorsets-accelerationstructure]] 342=== Acceleration Structure 343 344An _acceleration structure_ ( 345ifdef::VK_KHR_acceleration_structure[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR] 346ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 347ifdef::VK_NV_ray_tracing[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV] 348) is a descriptor type that is used to retrieve scene geometry from within 349shaders that are used for ray traversal. 350Shaders have read-only access to the memory. 351endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 352 353ifdef::VK_VALVE_mutable_descriptor_type[] 354[[descriptorsets-mutable]] 355=== Mutable 356 357A descriptor of _mutable_ (ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE) type 358indicates that this descriptor can: mutate to any of the descriptor types 359given in the 360slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pDescriptorTypes list of 361descriptor types in the pname:pNext chain of 362slink:VkDescriptorSetLayoutCreateInfo for this binding. 363At any point, each individual descriptor of mutable type has an active 364descriptor type. 365The active descriptor type can: be any one of the declared types in 366pname:pDescriptorTypes. 367Additionally, a mutable descriptor's active descriptor type can: be of the 368ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE type, which is the initial active 369descriptor type. 370The active descriptor type can: change when the descriptor is updated. 371When a descriptor is consumed by binding a descriptor set, the active 372descriptor type is considered, not ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE. 373 374An active descriptor type of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE is 375considered an undefined: descriptor. 376If a descriptor is consumed where the active descriptor type does not match 377what the shader expects, the descriptor is considered an undefined: 378descriptor. 379 380[NOTE] 381.Note 382==== 383To find which descriptor types are supported as 384ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the application can: use 385flink:vkGetDescriptorSetLayoutSupport with an 386ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE binding, with the list of descriptor 387types to query in the 388slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pDescriptorTypes array 389for that binding. 390==== 391 392[NOTE] 393.Note 394==== 395The intention of a mutable descriptor type is that implementations allocate 396N bytes per descriptor, where N is determined by the maximum descriptor size 397for a given descriptor binding. 398Implementations are not expected to keep track of the active descriptor 399type, and it should be considered a C-like union type. 400 401A mutable descriptor type is not considered as efficient in terms of 402run-time performance as using a non-mutable descriptor type, and 403applications are not encouraged to use them outside API layering efforts. 404Mutable descriptor types can be more efficient if the alternative is using 405many different descriptors to emulate mutable descriptor types. 406==== 407 408endif::VK_VALVE_mutable_descriptor_type[] 409 410[[descriptorsets-sets]] 411== Descriptor Sets 412 413Descriptors are grouped together into descriptor set objects. 414A descriptor set object is an opaque object containing storage for a set of 415descriptors, where the types and number of descriptors is defined by a 416descriptor set layout. 417The layout object may: be used to define the association of each descriptor 418binding with memory or other implementation resources. 419The layout is used both for determining the resources that need to be 420associated with the descriptor set, and determining the interface between 421shader stages and shader resources. 422 423 424[[descriptorsets-setlayout]] 425=== Descriptor Set Layout 426 427[open,refpage='VkDescriptorSetLayout',desc='Opaque handle to a descriptor set layout object',type='handles'] 428-- 429A descriptor set layout object is defined by an array of zero or more 430descriptor bindings. 431Each individual descriptor binding is specified by a descriptor type, a 432count (array size) of the number of descriptors in the binding, a set of 433shader stages that can: access the binding, and (if using immutable 434samplers) an array of sampler descriptors. 435 436Descriptor set layout objects are represented by sname:VkDescriptorSetLayout 437handles: 438 439include::{generated}/api/handles/VkDescriptorSetLayout.txt[] 440-- 441 442[open,refpage='vkCreateDescriptorSetLayout',desc='Create a new descriptor set layout',type='protos'] 443-- 444To create descriptor set layout objects, call: 445 446include::{generated}/api/protos/vkCreateDescriptorSetLayout.txt[] 447 448 * pname:device is the logical device that creates the descriptor set 449 layout. 450 * pname:pCreateInfo is a pointer to a 451 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 452 the descriptor set layout object. 453 * pname:pAllocator controls host memory allocation as described in the 454 <<memory-allocation, Memory Allocation>> chapter. 455 * pname:pSetLayout is a pointer to a slink:VkDescriptorSetLayout handle in 456 which the resulting descriptor set layout object is returned. 457 458include::{generated}/validity/protos/vkCreateDescriptorSetLayout.txt[] 459-- 460 461[open,refpage='VkDescriptorSetLayoutCreateInfo',desc='Structure specifying parameters of a newly created descriptor set layout',type='structs'] 462-- 463Information about the descriptor set layout is passed in a 464sname:VkDescriptorSetLayoutCreateInfo structure: 465 466include::{generated}/api/structs/VkDescriptorSetLayoutCreateInfo.txt[] 467 468 * pname:sType is the type of this structure. 469 * pname:pNext is `NULL` or a pointer to a structure extending this 470 structure. 471 * pname:flags is a bitmask 472ifdef::VK_KHR_push_descriptor[] 473 of elink:VkDescriptorSetLayoutCreateFlagBits 474endif::VK_KHR_push_descriptor[] 475 specifying options for descriptor set layout creation. 476 * pname:bindingCount is the number of elements in pname:pBindings. 477 * pname:pBindings is a pointer to an array of 478 slink:VkDescriptorSetLayoutBinding structures. 479 480.Valid Usage 481**** 482 * [[VUID-VkDescriptorSetLayoutCreateInfo-binding-00279]] 483 The slink:VkDescriptorSetLayoutBinding::pname:binding members of the 484 elements of the pname:pBindings array must: each have different values 485ifdef::VK_KHR_push_descriptor[] 486 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00280]] 487 If pname:flags contains 488 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 489 elements of pname:pBindings must: not have a pname:descriptorType of 490 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 491 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 492ifdef::VK_EXT_inline_uniform_block[] 493 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-02208]] 494 If pname:flags contains 495 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 496 elements of pname:pBindings must: not have a pname:descriptorType of 497 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 498endif::VK_EXT_inline_uniform_block[] 499 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00281]] 500 If pname:flags contains 501 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then the 502 total number of elements of all bindings must: be less than or equal to 503 slink:VkPhysicalDevicePushDescriptorPropertiesKHR::pname:maxPushDescriptors 504ifdef::VK_VALVE_mutable_descriptor_type[] 505 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04590]] 506 If pname:flags contains 507 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, 508 pname:flags must: not contain 509 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE 510 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04591]] 511 If pname:flags contains 512 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, 513 pname:pBindings must: not have a pname:descriptorType of 514 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 515endif::VK_VALVE_mutable_descriptor_type[] 516endif::VK_KHR_push_descriptor[] 517ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 518 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-03000]] 519 If any binding has the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 520 bit set, pname:flags must: include 521 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 522 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-03001]] 523 If any binding has the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 524 bit set, then all bindings must: not have pname:descriptorType of 525 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 526 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 527ifdef::VK_VALVE_mutable_descriptor_type[] 528 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04592]] 529 If pname:flags contains 530 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT, 531 pname:flags must: not contain 532 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE 533endif::VK_VALVE_mutable_descriptor_type[] 534endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 535ifdef::VK_VALVE_mutable_descriptor_type[] 536 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-04593]] 537 If any binding has a pname:descriptorType of 538 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, then a 539 slink:VkMutableDescriptorTypeCreateInfoVALVE must: be present in the 540 pname:pNext chain 541 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-04594]] 542 If a binding has a pname:descriptorType value of 543 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, then sname:pImmutableSamplers 544 must: be `NULL` 545 * [[VUID-VkDescriptorSetLayoutCreateInfo-mutableDescriptorType-04595]] 546 If 547 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::pname:mutableDescriptorType 548 is not enabled, pname:pBindings must: not contain a pname:descriptorType 549 of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 550 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04596]] 551 If pname:flags contains 552 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE, 553 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::pname:mutableDescriptorType 554 must: be enabled 555endif::VK_VALVE_mutable_descriptor_type[] 556**** 557 558include::{generated}/validity/structs/VkDescriptorSetLayoutCreateInfo.txt[] 559-- 560 561ifdef::VK_VALVE_mutable_descriptor_type[] 562 563[open,refpage='VkMutableDescriptorTypeCreateInfoVALVE',desc='Structure describing the list of possible active descriptor types for mutable type descriptors',type='structs'] 564-- 565Information about the possible descriptor types for mutable descriptor types 566is passed in a sname:VkMutableDescriptorTypeCreateInfoVALVE structure as a 567pname:pNext to a slink:VkDescriptorSetLayoutCreateInfo structure or a 568slink:VkDescriptorPoolCreateInfo structure. 569 570The sname:VkMutableDescriptorTypeCreateInfoVALVE structure is defined as: 571 572include::{generated}/api/structs/VkMutableDescriptorTypeCreateInfoVALVE.txt[] 573 574 * pname:sType is the type of this structure. 575 * pname:pNext is `NULL` or a pointer to a structure extending this 576 structure. 577 * pname:mutableDescriptorTypeListCount is the number of elements in 578 pname:pMutableDescriptorTypeLists. 579 * pname:pMutableDescriptorTypeLists is a pointer to an array of 580 sname:VkMutableDescriptorTypeListVALVE structures. 581 582If pname:mutableDescriptorTypeListCount is zero or if this structure is not 583included in the pname:pNext chain, the 584slink:VkMutableDescriptorTypeListVALVE for each element is considered to be 585zero or `NULL` for each member. 586Otherwise, the descriptor set layout binding at 587slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings[i] uses the 588descriptor type lists in 589slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pMutableDescriptorTypeLists[i]. 590 591include::{generated}/validity/structs/VkMutableDescriptorTypeCreateInfoVALVE.txt[] 592-- 593 594[open,refpage='VkMutableDescriptorTypeListVALVE',desc='Structure describing descriptor types that a given descriptor may mutate to',type='structs'] 595-- 596The list of potential descriptor types a given mutable descriptor can: 597mutate to is passed in a sname:VkMutableDescriptorTypeListVALVE structure. 598 599The sname:VkMutableDescriptorTypeListVALVE structure is defined as: 600 601include::{generated}/api/structs/VkMutableDescriptorTypeListVALVE.txt[] 602 603 * pname:descriptorTypeCount is the number of elements in 604 pname:pDescriptorTypes. 605 * pname:pDescriptorTypes is `NULL` or a pointer to an array of 606 pname:descriptorTypeCount elink:VkDescriptorType values which define 607 which descriptor types a given binding may mutate to. 608 609.Valid Usage 610**** 611 * [[VUID-VkMutableDescriptorTypeListVALVE-descriptorTypeCount-04597]] 612 pname:descriptorTypeCount must: not be `0` if the corresponding binding 613 is of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 614 * [[VUID-VkMutableDescriptorTypeListVALVE-pDescriptorTypes-04598]] 615 pname:pDescriptorTypes must: be a valid pointer to an array of 616 pname:descriptorTypeCount valid, unique elink:VkDescriptorType values if 617 the given binding is of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE type 618 * [[VUID-VkMutableDescriptorTypeListVALVE-descriptorTypeCount-04599]] 619 pname:descriptorTypeCount must: be `0` if the corresponding binding is 620 not of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 621 * [[VUID-VkMutableDescriptorTypeListVALVE-pDescriptorTypes-04600]] 622 pname:pDescriptorTypes must: not contain 623 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 624 * [[VUID-VkMutableDescriptorTypeListVALVE-pDescriptorTypes-04601]] 625 pname:pDescriptorTypes must: not contain 626 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 627 * [[VUID-VkMutableDescriptorTypeListVALVE-pDescriptorTypes-04602]] 628 pname:pDescriptorTypes must: not contain 629 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC 630ifdef::VK_EXT_inline_uniform_block[] 631 * [[VUID-VkMutableDescriptorTypeListVALVE-pDescriptorTypes-04603]] 632 pname:pDescriptorTypes must: not contain 633 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 634endif::VK_EXT_inline_uniform_block[] 635**** 636 637include::{generated}/validity/structs/VkMutableDescriptorTypeListVALVE.txt[] 638-- 639 640endif::VK_VALVE_mutable_descriptor_type[] 641 642[open,refpage='VkDescriptorSetLayoutCreateFlagBits',desc='Bitmask specifying descriptor set layout properties',type='enums'] 643-- 644Bits which can: be set in slink:VkDescriptorSetLayoutCreateInfo::pname:flags 645to specify options for descriptor set layout are: 646 647include::{generated}/api/enums/VkDescriptorSetLayoutCreateFlagBits.txt[] 648 649ifdef::VK_KHR_push_descriptor[] 650 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies 651 that descriptor sets must: not be allocated using this layout, and 652 descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. 653endif::VK_KHR_push_descriptor[] 654ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 655// Jon - "UpdateAfterBind" is a vague reference, should be more precise / 656// link to the right specification area 657 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 658 specifies that descriptor sets using this layout must: be allocated from 659 a descriptor pool created with the 660 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT bit set. 661 Descriptor set layouts created with this bit set have alternate limits 662 for the maximum number of descriptors per-stage and per-pipeline layout. 663 The non-UpdateAfterBind limits only count descriptors in sets created 664 without this flag. 665 The UpdateAfterBind limits count all descriptors, but the limits may: be 666 higher than the non-UpdateAfterBind limits. 667endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 668ifdef::VK_VALVE_mutable_descriptor_type[] 669 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE specifies 670 that descriptor sets using this layout must: be allocated from a 671 descriptor pool created with the 672 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE bit set. 673 Descriptor set layouts created with this bit have no expressable limit 674 for maximum number of descriptors per-stage. 675 Host descriptor sets are limited only by available host memory, but may: 676 be limited for implementation specific reasons. 677ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 678 Implementations may: limit the number of supported descriptors to 679 UpdateAfterBind limits or non-UpdateAfterBind limits, whichever is 680 larger. 681endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 682ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 683 Implementations may: limit the number of supported descriptors to 684 non-UpdateAfterBind limits. 685endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 686endif::VK_VALVE_mutable_descriptor_type[] 687 688ifndef::VK_KHR_push_descriptor[] 689[NOTE] 690.Note 691==== 692All bits for this type are defined by extensions, and none of those 693extensions are enabled in this build of the specification. 694==== 695endif::VK_KHR_push_descriptor[] 696-- 697 698[open,refpage='VkDescriptorSetLayoutCreateFlags',desc='Bitmask of VkDescriptorSetLayoutCreateFlagBits',type='flags'] 699-- 700include::{generated}/api/flags/VkDescriptorSetLayoutCreateFlags.txt[] 701 702tname:VkDescriptorSetLayoutCreateFlags is a bitmask type for setting a mask 703of zero or more elink:VkDescriptorSetLayoutCreateFlagBits. 704-- 705 706[open,refpage='VkDescriptorSetLayoutBinding',desc='Structure specifying a descriptor set layout binding',type='structs'] 707-- 708The sname:VkDescriptorSetLayoutBinding structure is defined as: 709 710include::{generated}/api/structs/VkDescriptorSetLayoutBinding.txt[] 711 712 * pname:binding is the binding number of this entry and corresponds to a 713 resource of the same binding number in the shader stages. 714 * pname:descriptorType is a elink:VkDescriptorType specifying which type 715 of resource descriptors are used for this binding. 716 * pname:descriptorCount is the number of descriptors contained in the 717 binding, accessed in a shader as an 718ifndef::VK_EXT_inline_uniform_block[array.] 719ifdef::VK_EXT_inline_uniform_block[] 720 array, except if pname:descriptorType is 721 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT in which case 722 pname:descriptorCount is the size in bytes of the inline uniform block. 723endif::VK_EXT_inline_uniform_block[] 724 If pname:descriptorCount is zero this binding entry is reserved and the 725 resource must: not be accessed from any stage via this binding within 726 any pipeline using the set layout. 727 * pname:stageFlags member is a bitmask of elink:VkShaderStageFlagBits 728 specifying which pipeline shader stages can: access a resource for this 729 binding. 730 ename:VK_SHADER_STAGE_ALL is a shorthand specifying that all defined 731 shader stages, including any additional stages defined by extensions, 732 can: access the resource. 733+ 734If a shader stage is not included in pname:stageFlags, then a resource must: 735not be accessed from that stage via this binding within any pipeline using 736the set layout. 737Other than input attachments which are limited to the fragment shader, there 738are no limitations on what combinations of stages can: use a descriptor 739binding, and in particular a binding can: be used by both graphics stages 740and the compute stage. 741 742 * pname:pImmutableSamplers affects initialization of samplers. 743 If pname:descriptorType specifies a ename:VK_DESCRIPTOR_TYPE_SAMPLER or 744 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then 745 pname:pImmutableSamplers can: be used to initialize a set of _immutable 746 samplers_. 747 Immutable samplers are permanently bound into the set layout and must: 748 not be changed; updating a ename:VK_DESCRIPTOR_TYPE_SAMPLER descriptor 749 with immutable samplers is not allowed and updates to a 750 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptor with 751 immutable samplers does not modify the samplers (the image views are 752 updated, but the sampler updates are ignored). 753 If pname:pImmutableSamplers is not `NULL`, then it is a pointer to an 754 array of sampler handles that will be copied into the set layout and 755 used for the corresponding binding. 756 Only the sampler handles are copied; the sampler objects must: not be 757 destroyed before the final use of the set layout and any descriptor 758 pools and sets created using it. 759 If pname:pImmutableSamplers is `NULL`, then the sampler slots are 760 dynamic and sampler handles must: be bound into descriptor sets using 761 this layout. 762 If pname:descriptorType is not one of these descriptor types, then 763 pname:pImmutableSamplers is ignored. 764 765The above layout definition allows the descriptor bindings to be specified 766sparsely such that not all binding numbers between 0 and the maximum binding 767number need to be specified in the pname:pBindings array. 768Bindings that are not specified have a pname:descriptorCount and 769pname:stageFlags of zero, and the value of pname:descriptorType is 770undefined:. 771However, all binding numbers between 0 and the maximum binding number in the 772slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings array may: consume 773memory in the descriptor set layout even if not all descriptor bindings are 774used, though it should: not consume additional memory from the descriptor 775pool. 776 777[NOTE] 778.Note 779==== 780The maximum binding number specified should: be as compact as possible to 781avoid wasted memory. 782==== 783 784.Valid Usage 785**** 786 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-00282]] 787 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 788 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 789 pname:descriptorCount is not `0` and pname:pImmutableSamplers is not 790 `NULL`, pname:pImmutableSamplers must: be a valid pointer to an array of 791 pname:descriptorCount valid sname:VkSampler handles 792ifdef::VK_EXT_inline_uniform_block[] 793 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-04604]] 794 If the <<features-inlineUniformBlock,inlineUniformBlock>> feature is not 795 enabled, pname:descriptorType must: not be 796 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 797 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-02209]] 798 If pname:descriptorType is 799 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 800 pname:descriptorCount must: be a multiple of `4` 801 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-02210]] 802 If pname:descriptorType is 803 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 804 pname:descriptorCount must: be less than or equal to 805 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxInlineUniformBlockSize 806endif::VK_EXT_inline_uniform_block[] 807 * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-00283]] 808 If pname:descriptorCount is not `0`, pname:stageFlags must: be a valid 809 combination of elink:VkShaderStageFlagBits values 810 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-01510]] 811 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and 812 pname:descriptorCount is not `0`, then pname:stageFlags must: be `0` or 813 ename:VK_SHADER_STAGE_FRAGMENT_BIT 814ifdef::VK_EXT_custom_border_color[] 815 * [[VUID-VkDescriptorSetLayoutBinding-pImmutableSamplers-04009]] 816 The sampler objects indicated by pname:pImmutableSamplers must: not have 817 a pname:borderColor with one of the values 818 ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 819 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT 820endif::VK_EXT_custom_border_color[] 821ifdef::VK_VALVE_mutable_descriptor_type[] 822 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-04605]] 823 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, then 824 sname:pImmutableSamplers must: be `NULL` 825endif::VK_VALVE_mutable_descriptor_type[] 826**** 827 828include::{generated}/validity/structs/VkDescriptorSetLayoutBinding.txt[] 829-- 830 831ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 832[open,refpage='VkDescriptorSetLayoutBindingFlagsCreateInfo',desc='Structure specifying creation flags for descriptor set layout bindings',type='structs',alias='VkDescriptorSetLayoutBindingFlagsCreateInfoEXT'] 833-- 834If the pname:pNext chain of a slink:VkDescriptorSetLayoutCreateInfo 835structure includes a slink:VkDescriptorSetLayoutBindingFlagsCreateInfo 836structure, then that structure includes an array of flags, one for each 837descriptor set layout binding. 838 839The slink:VkDescriptorSetLayoutBindingFlagsCreateInfo structure is defined 840as: 841 842include::{generated}/api/structs/VkDescriptorSetLayoutBindingFlagsCreateInfo.txt[] 843 844ifdef::VK_EXT_descriptor_indexing[] 845or the equivalent 846 847include::{generated}/api/structs/VkDescriptorSetLayoutBindingFlagsCreateInfoEXT.txt[] 848endif::VK_EXT_descriptor_indexing[] 849 850 * pname:sType is the type of this structure. 851 * pname:pNext is `NULL` or a pointer to a structure extending this 852 structure. 853 * pname:bindingCount is zero or the number of elements in 854 pname:pBindingFlags. 855 * pname:pBindingFlags is a pointer to an array of 856 tlink:VkDescriptorBindingFlags bitfields, one for each descriptor set 857 layout binding. 858 859If pname:bindingCount is zero or if this structure is not included in the 860pname:pNext chain, the tlink:VkDescriptorBindingFlags for each descriptor 861set layout binding is considered to be zero. 862Otherwise, the descriptor set layout binding at 863slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings[i] uses the flags in 864pname:pBindingFlags[i]. 865 866.Valid Usage 867**** 868 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-bindingCount-03002]] 869 If pname:bindingCount is not zero, pname:bindingCount must: equal 870 slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount 871ifdef::VK_KHR_push_descriptor[] 872 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-flags-03003]] 873 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags includes 874 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 875 elements of pname:pBindingFlags must: not include 876 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT, 877 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT, or 878 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT 879endif::VK_KHR_push_descriptor[] 880 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-pBindingFlags-03004]] 881 If an element of pname:pBindingFlags includes 882 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, then all 883 other elements of slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings 884 must: have a smaller value of pname:binding 885 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUniformBufferUpdateAfterBind-03005]] 886 If 887 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUniformBufferUpdateAfterBind 888 is not enabled, all bindings with descriptor type 889 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER must: not use 890 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 891 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingSampledImageUpdateAfterBind-03006]] 892 If 893 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingSampledImageUpdateAfterBind 894 is not enabled, all bindings with descriptor type 895 ename:VK_DESCRIPTOR_TYPE_SAMPLER, 896 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, or 897 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE must: not use 898 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 899 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageImageUpdateAfterBind-03007]] 900 If 901 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageImageUpdateAfterBind 902 is not enabled, all bindings with descriptor type 903 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE must: not use 904 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 905 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageBufferUpdateAfterBind-03008]] 906 If 907 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageBufferUpdateAfterBind 908 is not enabled, all bindings with descriptor type 909 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER must: not use 910 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 911 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUniformTexelBufferUpdateAfterBind-03009]] 912 If 913 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUniformTexelBufferUpdateAfterBind 914 is not enabled, all bindings with descriptor type 915 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER must: not use 916 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 917 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageTexelBufferUpdateAfterBind-03010]] 918 If 919 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageTexelBufferUpdateAfterBind 920 is not enabled, all bindings with descriptor type 921 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER must: not use 922 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 923ifdef::VK_EXT_inline_uniform_block[] 924 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingInlineUniformBlockUpdateAfterBind-02211]] 925 If 926 slink:VkPhysicalDeviceInlineUniformBlockFeaturesEXT::pname:descriptorBindingInlineUniformBlockUpdateAfterBind 927 is not enabled, all bindings with descriptor type 928 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT must: not use 929 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 930endif::VK_EXT_inline_uniform_block[] 931ifdef::VK_KHR_acceleration_structure[] 932 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingAccelerationStructureUpdateAfterBind-03570]] 933 If 934 slink:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:descriptorBindingAccelerationStructureUpdateAfterBind 935 is not enabled, all bindings with descriptor type 936 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR or 937 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV must: not use 938 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 939endif::VK_KHR_acceleration_structure[] 940 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-None-03011]] 941 All bindings with descriptor type 942 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 943 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 944 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: not use 945 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 946 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUpdateUnusedWhilePending-03012]] 947 If 948 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUpdateUnusedWhilePending 949 is not enabled, all elements of pname:pBindingFlags must: not include 950 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT 951 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingPartiallyBound-03013]] 952 If 953 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingPartiallyBound 954 is not enabled, all elements of pname:pBindingFlags must: not include 955 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT 956 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingVariableDescriptorCount-03014]] 957 If 958 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingVariableDescriptorCount 959 is not enabled, all elements of pname:pBindingFlags must: not include 960 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT 961 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-pBindingFlags-03015]] 962 If an element of pname:pBindingFlags includes 963 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, that 964 element's pname:descriptorType must: not be 965 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 966 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 967**** 968 969include::{generated}/validity/structs/VkDescriptorSetLayoutBindingFlagsCreateInfo.txt[] 970-- 971 972[open,refpage='VkDescriptorBindingFlagBits',desc='Bitmask specifying descriptor set layout binding properties',type='enums',alias='VkDescriptorBindingFlagBitsEXT'] 973-- 974Bits which can: be set in each element of 975slink:VkDescriptorSetLayoutBindingFlagsCreateInfo::pname:pBindingFlags to 976specify options for the corresponding descriptor set layout binding are: 977 978include::{generated}/api/enums/VkDescriptorBindingFlagBits.txt[] 979 980ifdef::VK_EXT_descriptor_indexing[] 981or the equivalent 982 983include::{generated}/api/enums/VkDescriptorBindingFlagBitsEXT.txt[] 984endif::VK_EXT_descriptor_indexing[] 985 986 * ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT indicates that if 987 descriptors in this binding are updated between when the descriptor set 988 is bound in a command buffer and when that command buffer is submitted 989 to a queue, then the submission will use the most recently set 990 descriptors for this binding and the updates do not invalidate the 991 command buffer. 992 Descriptor bindings created with this flag are also partially exempt 993 from the external synchronization requirement in 994ifdef::VK_KHR_descriptor_update_template[] 995 flink:vkUpdateDescriptorSetWithTemplateKHR and 996endif::VK_KHR_descriptor_update_template[] 997 flink:vkUpdateDescriptorSets. 998 Multiple descriptors with this flag set can: be updated concurrently in 999 different threads, though the same descriptor must: not be updated 1000 concurrently by two threads. 1001 Descriptors with this flag set can: be updated concurrently with the set 1002 being bound to a command buffer in another thread, but not concurrently 1003 with the set being reset or freed. 1004 * ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT indicates that 1005 descriptors in this binding that are not _dynamically used_ need not 1006 contain valid descriptors at the time the descriptors are consumed. 1007 A descriptor is dynamically used if any shader invocation executes an 1008 instruction that performs any memory access using the descriptor. 1009 * ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT indicates 1010 that descriptors in this binding can: be updated after a command buffer 1011 has bound this descriptor set, or while a command buffer that uses this 1012 descriptor set is pending execution, as long as the descriptors that are 1013 updated are not used by those command buffers. 1014 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT is also set, then 1015 descriptors can: be updated as long as they are not dynamically used by 1016 any shader invocations. 1017 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT is not set, then 1018 descriptors can: be updated as long as they are not statically used by 1019 any shader invocations. 1020 * ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT indicates that 1021 this descriptor binding has a variable size that will be specified when 1022 a descriptor set is allocated using this layout. 1023 The value of pname:descriptorCount is treated as an upper bound on the 1024 size of the binding. 1025 This must: only be used for the last binding in the descriptor set 1026 layout (i.e. the binding with the largest value of pname:binding). 1027 For the purposes of counting against limits such as 1028 pname:maxDescriptorSet* and pname:maxPerStageDescriptor*, the full value 1029 of pname:descriptorCount is 1030ifndef::VK_EXT_inline_uniform_block[counted.] 1031ifdef::VK_EXT_inline_uniform_block[] 1032 counted, except for descriptor bindings with a descriptor type of 1033 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT where 1034 pname:descriptorCount specifies the upper bound on the byte size of the 1035 binding, thus it counts against the <<limits-maxInlineUniformBlockSize, 1036 pname:maxInlineUniformBlockSize>> limit instead. 1037endif::VK_EXT_inline_uniform_block[] 1038 1039[NOTE] 1040.Note 1041==== 1042Note that while ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT and 1043ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT both involve 1044updates to descriptor sets after they are bound, 1045ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT is a weaker 1046requirement since it is only about descriptors that are not used, whereas 1047ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT requires the 1048implementation to observe updates to descriptors that are used. 1049==== 1050-- 1051 1052[open,refpage='VkDescriptorBindingFlags',desc='Bitmask of VkDescriptorBindingFlagBits',type='flags',alias='VkDescriptorBindingFlagsEXT'] 1053-- 1054include::{generated}/api/flags/VkDescriptorBindingFlags.txt[] 1055 1056ifdef::VK_EXT_descriptor_indexing[] 1057or the equivalent 1058 1059include::{generated}/api/flags/VkDescriptorBindingFlagsEXT.txt[] 1060endif::VK_EXT_descriptor_indexing[] 1061 1062tname:VkDescriptorBindingFlags is a bitmask type for setting a mask of zero 1063or more elink:VkDescriptorBindingFlagBits. 1064-- 1065endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1066 1067ifdef::VK_VERSION_1_1,VK_KHR_maintenance3[] 1068[open,refpage='vkGetDescriptorSetLayoutSupport',desc='Query whether a descriptor set layout can be created',type='protos'] 1069-- 1070To query information about whether a descriptor set layout can: be created, 1071call: 1072 1073ifdef::VK_VERSION_1_1[] 1074include::{generated}/api/protos/vkGetDescriptorSetLayoutSupport.txt[] 1075endif::VK_VERSION_1_1[] 1076 1077ifdef::VK_VERSION_1_1+VK_KHR_maintenance3[or the equivalent command] 1078 1079ifdef::VK_KHR_maintenance3[] 1080include::{generated}/api/protos/vkGetDescriptorSetLayoutSupportKHR.txt[] 1081endif::VK_KHR_maintenance3[] 1082 1083 * pname:device is the logical device that would create the descriptor set 1084 layout. 1085 * pname:pCreateInfo is a pointer to a 1086 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 1087 the descriptor set layout object. 1088 * pname:pSupport is a pointer to a slink:VkDescriptorSetLayoutSupport 1089 structure, in which information about support for the descriptor set 1090 layout object is returned. 1091 1092Some implementations have limitations on what fits in a descriptor set which 1093are not easily expressible in terms of existing limits like 1094pname:maxDescriptorSet*, for example if all descriptor types share a limited 1095space in memory but each descriptor is a different size or alignment. 1096This command returns information about whether a descriptor set satisfies 1097this limit. 1098If the descriptor set layout satisfies the 1099slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 1100limit, this command is guaranteed to return ename:VK_TRUE in 1101slink:VkDescriptorSetLayoutSupport::pname:supported. 1102If the descriptor set layout exceeds the 1103slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 1104limit, whether the descriptor set layout is supported is 1105implementation-dependent and may: depend on whether the descriptor sizes and 1106alignments cause the layout to exceed an internal limit. 1107 1108This command does not consider other limits such as 1109pname:maxPerStageDescriptor*, and so a descriptor set layout that is 1110supported according to this command must: still satisfy the pipeline layout 1111limits such as pname:maxPerStageDescriptor* in order to be used in a 1112pipeline layout. 1113 1114[NOTE] 1115.Note 1116==== 1117This is a sname:VkDevice query rather than sname:VkPhysicalDevice because 1118the answer may: depend on enabled features. 1119==== 1120 1121include::{generated}/validity/protos/vkGetDescriptorSetLayoutSupport.txt[] 1122-- 1123 1124[open,refpage='VkDescriptorSetLayoutSupport',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs'] 1125-- 1126Information about support for the descriptor set layout is returned in a 1127sname:VkDescriptorSetLayoutSupport structure: 1128 1129include::{generated}/api/structs/VkDescriptorSetLayoutSupport.txt[] 1130 1131ifdef::VK_KHR_maintenance3[] 1132or the equivalent 1133 1134include::{generated}/api/structs/VkDescriptorSetLayoutSupportKHR.txt[] 1135endif::VK_KHR_maintenance3[] 1136 1137 * pname:sType is the type of this structure. 1138 * pname:pNext is `NULL` or a pointer to a structure extending this 1139 structure. 1140 * pname:supported specifies whether the descriptor set layout can: be 1141 created. 1142 1143pname:supported is set to ename:VK_TRUE if the descriptor set can: be 1144created, or else is set to ename:VK_FALSE. 1145 1146include::{generated}/validity/structs/VkDescriptorSetLayoutSupport.txt[] 1147-- 1148endif::VK_VERSION_1_1,VK_KHR_maintenance3[] 1149 1150ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1151[open,refpage='VkDescriptorSetVariableDescriptorCountLayoutSupport',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs',alias='VkDescriptorSetVariableDescriptorCountLayoutSupportEXT'] 1152-- 1153If the pname:pNext chain of a slink:VkDescriptorSetLayoutSupport structure 1154includes a sname:VkDescriptorSetVariableDescriptorCountLayoutSupport 1155structure, then that structure returns additional information about whether 1156the descriptor set layout is supported. 1157 1158include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountLayoutSupport.txt[] 1159 1160ifdef::VK_EXT_descriptor_indexing[] 1161or the equivalent 1162 1163include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.txt[] 1164endif::VK_EXT_descriptor_indexing[] 1165 1166 * pname:sType is the type of this structure. 1167 * pname:pNext is `NULL` or a pointer to a structure extending this 1168 structure. 1169 * pname:maxVariableDescriptorCount indicates the maximum number of 1170 descriptors supported in the highest numbered binding of the layout, if 1171 that binding is variable-sized. 1172ifdef::VK_EXT_inline_uniform_block[] 1173 If the highest numbered binding of the layout has a descriptor type of 1174 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 1175 pname:maxVariableDescriptorCount indicates the maximum byte size 1176 supported for the binding, if that binding is variable-sized. 1177endif::VK_EXT_inline_uniform_block[] 1178 1179If the slink:VkDescriptorSetLayoutCreateInfo structure specified in 1180flink:vkGetDescriptorSetLayoutSupport::pname:pCreateInfo includes a 1181variable-sized descriptor, then pname:supported is determined assuming the 1182requested size of the variable-sized descriptor, and 1183pname:maxVariableDescriptorCount is set to the maximum size of that 1184descriptor that can: be successfully created (which is greater than or equal 1185to the requested size passed in). 1186If the slink:VkDescriptorSetLayoutCreateInfo structure does not include a 1187variable-sized descriptor, or if the 1188slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingVariableDescriptorCount 1189feature is not enabled, then pname:maxVariableDescriptorCount is set to 1190zero. 1191For the purposes of this command, a variable-sized descriptor binding with a 1192pname:descriptorCount of zero is treated as if the pname:descriptorCount is 1193one, and thus the binding is not ignored and the maximum descriptor count 1194will be returned. 1195If the layout is not supported, then the value written to 1196pname:maxVariableDescriptorCount is undefined:. 1197 1198include::{generated}/validity/structs/VkDescriptorSetVariableDescriptorCountLayoutSupport.txt[] 1199-- 1200endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1201 1202The following examples show a shader snippet using two descriptor sets, and 1203application code that creates corresponding descriptor set layouts. 1204 1205.GLSL example 1206[source,glsl] 1207--------------------------------------------------- 1208// 1209// binding to a single sampled image descriptor in set 0 1210// 1211layout (set=0, binding=0) uniform texture2D mySampledImage; 1212 1213// 1214// binding to an array of sampled image descriptors in set 0 1215// 1216layout (set=0, binding=1) uniform texture2D myArrayOfSampledImages[12]; 1217 1218// 1219// binding to a single uniform buffer descriptor in set 1 1220// 1221layout (set=1, binding=0) uniform myUniformBuffer 1222{ 1223 vec4 myElement[32]; 1224}; 1225--------------------------------------------------- 1226 1227.SPIR-V example 1228[source,spirv] 1229--------------------------------------------------- 1230 ... 1231 %1 = OpExtInstImport "GLSL.std.450" 1232 ... 1233 OpName %9 "mySampledImage" 1234 OpName %14 "myArrayOfSampledImages" 1235 OpName %18 "myUniformBuffer" 1236 OpMemberName %18 0 "myElement" 1237 OpName %20 "" 1238 OpDecorate %9 DescriptorSet 0 1239 OpDecorate %9 Binding 0 1240 OpDecorate %14 DescriptorSet 0 1241 OpDecorate %14 Binding 1 1242 OpDecorate %17 ArrayStride 16 1243 OpMemberDecorate %18 0 Offset 0 1244 OpDecorate %18 Block 1245 OpDecorate %20 DescriptorSet 1 1246 OpDecorate %20 Binding 0 1247 %2 = OpTypeVoid 1248 %3 = OpTypeFunction %2 1249 %6 = OpTypeFloat 32 1250 %7 = OpTypeImage %6 2D 0 0 0 1 Unknown 1251 %8 = OpTypePointer UniformConstant %7 1252 %9 = OpVariable %8 UniformConstant 1253 %10 = OpTypeInt 32 0 1254 %11 = OpConstant %10 12 1255 %12 = OpTypeArray %7 %11 1256 %13 = OpTypePointer UniformConstant %12 1257 %14 = OpVariable %13 UniformConstant 1258 %15 = OpTypeVector %6 4 1259 %16 = OpConstant %10 32 1260 %17 = OpTypeArray %15 %16 1261 %18 = OpTypeStruct %17 1262 %19 = OpTypePointer Uniform %18 1263 %20 = OpVariable %19 Uniform 1264 ... 1265--------------------------------------------------- 1266 1267.API example 1268[source,c++] 1269--------------------------------------------------- 1270VkResult myResult; 1271 1272const VkDescriptorSetLayoutBinding myDescriptorSetLayoutBinding[] = 1273{ 1274 // binding to a single image descriptor 1275 { 1276 0, // binding 1277 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType 1278 1, // descriptorCount 1279 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 1280 NULL // pImmutableSamplers 1281 }, 1282 1283 // binding to an array of image descriptors 1284 { 1285 1, // binding 1286 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType 1287 12, // descriptorCount 1288 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 1289 NULL // pImmutableSamplers 1290 }, 1291 1292 // binding to a single uniform buffer descriptor 1293 { 1294 0, // binding 1295 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType 1296 1, // descriptorCount 1297 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 1298 NULL // pImmutableSamplers 1299 } 1300}; 1301 1302const VkDescriptorSetLayoutCreateInfo myDescriptorSetLayoutCreateInfo[] = 1303{ 1304 // Information for first descriptor set with two descriptor bindings 1305 { 1306 VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType 1307 NULL, // pNext 1308 0, // flags 1309 2, // bindingCount 1310 &myDescriptorSetLayoutBinding[0] // pBindings 1311 }, 1312 1313 // Information for second descriptor set with one descriptor binding 1314 { 1315 VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType 1316 NULL, // pNext 1317 0, // flags 1318 1, // bindingCount 1319 &myDescriptorSetLayoutBinding[2] // pBindings 1320 } 1321}; 1322 1323VkDescriptorSetLayout myDescriptorSetLayout[2]; 1324 1325// 1326// Create first descriptor set layout 1327// 1328myResult = vkCreateDescriptorSetLayout( 1329 myDevice, 1330 &myDescriptorSetLayoutCreateInfo[0], 1331 NULL, 1332 &myDescriptorSetLayout[0]); 1333 1334// 1335// Create second descriptor set layout 1336// 1337myResult = vkCreateDescriptorSetLayout( 1338 myDevice, 1339 &myDescriptorSetLayoutCreateInfo[1], 1340 NULL, 1341 &myDescriptorSetLayout[1]); 1342--------------------------------------------------- 1343 1344[open,refpage='vkDestroyDescriptorSetLayout',desc='Destroy a descriptor set layout object',type='protos'] 1345-- 1346To destroy a descriptor set layout, call: 1347 1348include::{generated}/api/protos/vkDestroyDescriptorSetLayout.txt[] 1349 1350 * pname:device is the logical device that destroys the descriptor set 1351 layout. 1352 * pname:descriptorSetLayout is the descriptor set layout to destroy. 1353 * pname:pAllocator controls host memory allocation as described in the 1354 <<memory-allocation, Memory Allocation>> chapter. 1355 1356.Valid Usage 1357**** 1358 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00284]] 1359 If sname:VkAllocationCallbacks were provided when 1360 pname:descriptorSetLayout was created, a compatible set of callbacks 1361 must: be provided here 1362 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00285]] 1363 If no sname:VkAllocationCallbacks were provided when 1364 pname:descriptorSetLayout was created, pname:pAllocator must: be `NULL` 1365**** 1366 1367include::{generated}/validity/protos/vkDestroyDescriptorSetLayout.txt[] 1368-- 1369 1370 1371[[descriptorsets-pipelinelayout]] 1372=== Pipeline Layouts 1373 1374[open,refpage='VkPipelineLayout',desc='Opaque handle to a pipeline layout object',type='handles'] 1375-- 1376Access to descriptor sets from a pipeline is accomplished through a 1377_pipeline layout_. 1378Zero or more descriptor set layouts and zero or more push constant ranges 1379are combined to form a pipeline layout object describing the complete set of 1380resources that can: be accessed by a pipeline. 1381The pipeline layout represents a sequence of descriptor sets with each 1382having a specific layout. 1383This sequence of layouts is used to determine the interface between shader 1384stages and shader resources. 1385Each pipeline is created using a pipeline layout. 1386 1387Pipeline layout objects are represented by sname:VkPipelineLayout handles: 1388 1389include::{generated}/api/handles/VkPipelineLayout.txt[] 1390-- 1391 1392[open,refpage='vkCreatePipelineLayout',desc='Creates a new pipeline layout object',type='protos'] 1393-- 1394To create a pipeline layout, call: 1395 1396include::{generated}/api/protos/vkCreatePipelineLayout.txt[] 1397 1398 * pname:device is the logical device that creates the pipeline layout. 1399 * pname:pCreateInfo is a pointer to a slink:VkPipelineLayoutCreateInfo 1400 structure specifying the state of the pipeline layout object. 1401 * pname:pAllocator controls host memory allocation as described in the 1402 <<memory-allocation, Memory Allocation>> chapter. 1403 * pname:pPipelineLayout is a pointer to a slink:VkPipelineLayout handle in 1404 which the resulting pipeline layout object is returned. 1405 1406include::{generated}/validity/protos/vkCreatePipelineLayout.txt[] 1407-- 1408 1409[open,refpage='VkPipelineLayoutCreateInfo',desc='Structure specifying the parameters of a newly created pipeline layout object',type='structs'] 1410-- 1411The slink:VkPipelineLayoutCreateInfo structure is defined as: 1412 1413include::{generated}/api/structs/VkPipelineLayoutCreateInfo.txt[] 1414 1415 * pname:sType is the type of this structure. 1416 * pname:pNext is `NULL` or a pointer to a structure extending this 1417 structure. 1418 * pname:flags is reserved for future use. 1419 * pname:setLayoutCount is the number of descriptor sets included in the 1420 pipeline layout. 1421 * pname:pSetLayouts is a pointer to an array of 1422 sname:VkDescriptorSetLayout objects. 1423 * pname:pushConstantRangeCount is the number of push constant ranges 1424 included in the pipeline layout. 1425 * pname:pPushConstantRanges is a pointer to an array of 1426 sname:VkPushConstantRange structures defining a set of push constant 1427 ranges for use in a single pipeline layout. 1428 In addition to descriptor set layouts, a pipeline layout also describes 1429 how many push constants can: be accessed by each stage of the pipeline. 1430+ 1431[NOTE] 1432.Note 1433==== 1434Push constants represent a high speed path to modify constant data in 1435pipelines that is expected to outperform memory-backed resource updates. 1436==== 1437 1438.Valid Usage 1439**** 1440 * [[VUID-VkPipelineLayoutCreateInfo-setLayoutCount-00286]] 1441 pname:setLayoutCount must: be less than or equal to 1442 sname:VkPhysicalDeviceLimits::pname:maxBoundDescriptorSets 1443ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1444 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00287]] 1445 The total number of descriptors of the type 1446 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1447 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any shader 1448 stage across all elements of pname:pSetLayouts must: be less than or 1449 equal to 1450 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSamplers 1451 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00288]] 1452 The total number of descriptors of the type 1453 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1454 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any shader 1455 stage across all elements of pname:pSetLayouts must: be less than or 1456 equal to 1457 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorUniformBuffers 1458 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00289]] 1459 The total number of descriptors of the type 1460 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1461 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any shader 1462 stage across all elements of pname:pSetLayouts must: be less than or 1463 equal to 1464 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageBuffers 1465 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00290]] 1466 The total number of descriptors of the type 1467 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1468 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1469 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any shader 1470 stage across all elements of pname:pSetLayouts must: be less than or 1471 equal to 1472 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSampledImages 1473 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00291]] 1474 The total number of descriptors of the type 1475 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1476 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any shader 1477 stage across all elements of pname:pSetLayouts must: be less than or 1478 equal to 1479 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageImages 1480 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01676]] 1481 The total number of descriptors of the type 1482 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1483 stage across all elements of pname:pSetLayouts must: be less than or 1484 equal to 1485 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorInputAttachments 1486ifdef::VK_EXT_inline_uniform_block[] 1487 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02212]] 1488 The total number of bindings with a pname:descriptorType of 1489 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible to any 1490 given shader stage across all elements of pname:pSetLayouts must: be 1491 less than or equal to 1492 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxPerStageDescriptorInlineUniformBlocks 1493endif::VK_EXT_inline_uniform_block[] 1494 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01677]] 1495 The total number of descriptors of the type 1496 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1497 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1498 shader stages and across all elements of pname:pSetLayouts must: be less 1499 than or equal to 1500 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSamplers 1501 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01678]] 1502 The total number of descriptors of the type 1503 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1504 stages and across all elements of pname:pSetLayouts must: be less than 1505 or equal to 1506 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffers 1507 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01679]] 1508 The total number of descriptors of the type 1509 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1510 shader stages and across all elements of pname:pSetLayouts must: be less 1511 than or equal to 1512 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffersDynamic 1513 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01680]] 1514 The total number of descriptors of the type 1515 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1516 stages and across all elements of pname:pSetLayouts must: be less than 1517 or equal to 1518 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffers 1519 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01681]] 1520 The total number of descriptors of the type 1521 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1522 shader stages and across all elements of pname:pSetLayouts must: be less 1523 than or equal to 1524 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffersDynamic 1525 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01682]] 1526 The total number of descriptors of the type 1527 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1528 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1529 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1530 shader stages and across all elements of pname:pSetLayouts must: be less 1531 than or equal to 1532 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSampledImages 1533 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01683]] 1534 The total number of descriptors of the type 1535 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1536 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1537 shader stages and across all elements of pname:pSetLayouts must: be less 1538 than or equal to 1539 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageImages 1540 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01684]] 1541 The total number of descriptors of the type 1542 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1543 stages and across all elements of pname:pSetLayouts must: be less than 1544 or equal to 1545 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetInputAttachments 1546ifdef::VK_EXT_inline_uniform_block[] 1547 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02213]] 1548 The total number of bindings with a pname:descriptorType of 1549 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible across all 1550 shader stages and across all elements of pname:pSetLayouts must: be less 1551 than or equal to 1552 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxDescriptorSetInlineUniformBlocks 1553endif::VK_EXT_inline_uniform_block[] 1554endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1555ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1556 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03016]] 1557 The total number of descriptors in descriptor set layouts created 1558 without the 1559 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1560 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1561 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1562 shader stage across all elements of pname:pSetLayouts must: be less than 1563 or equal to 1564 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSamplers 1565 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03017]] 1566 The total number of descriptors in descriptor set layouts created 1567 without the 1568 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1569 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER 1570 and ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any 1571 given shader stage across all elements of pname:pSetLayouts must: be 1572 less than or equal to 1573 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorUniformBuffers 1574 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03018]] 1575 The total number of descriptors in descriptor set layouts created 1576 without the 1577 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1578 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER 1579 and ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any 1580 given shader stage across all elements of pname:pSetLayouts must: be 1581 less than or equal to 1582 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageBuffers 1583 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03019]] 1584 The total number of descriptors in descriptor set layouts created 1585 without the 1586 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1587 with a pname:descriptorType of 1588 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1589 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1590 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any given 1591 shader stage across all elements of pname:pSetLayouts must: be less than 1592 or equal to 1593 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSampledImages 1594 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03020]] 1595 The total number of descriptors in descriptor set layouts created 1596 without the 1597 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1598 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 1599 and ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any 1600 given shader stage across all elements of pname:pSetLayouts must: be 1601 less than or equal to 1602 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageImages 1603 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03021]] 1604 The total number of descriptors in descriptor set layouts created 1605 without the 1606 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1607 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 1608 accessible to any given shader stage across all elements of 1609 pname:pSetLayouts must: be less than or equal to 1610 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorInputAttachments 1611ifdef::VK_EXT_inline_uniform_block[] 1612 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02214]] 1613 The total number of bindings in descriptor set layouts created without 1614 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 1615 set with a pname:descriptorType of 1616 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible to any 1617 given shader stage across all elements of pname:pSetLayouts must: be 1618 less than or equal to 1619 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxPerStageDescriptorInlineUniformBlocks 1620endif::VK_EXT_inline_uniform_block[] 1621 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03022]] 1622 The total number of descriptors with a pname:descriptorType of 1623 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1624 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1625 shader stage across all elements of pname:pSetLayouts must: be less than 1626 or equal to 1627 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindSamplers 1628 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03023]] 1629 The total number of descriptors with a pname:descriptorType of 1630 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1631 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any given 1632 shader stage across all elements of pname:pSetLayouts must: be less than 1633 or equal to 1634 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers 1635 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03024]] 1636 The total number of descriptors with a pname:descriptorType of 1637 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1638 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any given 1639 shader stage across all elements of pname:pSetLayouts must: be less than 1640 or equal to 1641 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers 1642 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03025]] 1643 The total number of descriptors with a pname:descriptorType of 1644 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1645 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1646 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any given 1647 shader stage across all elements of pname:pSetLayouts must: be less than 1648 or equal to 1649 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindSampledImages 1650 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03026]] 1651 The total number of descriptors with a pname:descriptorType of 1652 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1653 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any given 1654 shader stage across all elements of pname:pSetLayouts must: be less than 1655 or equal to 1656 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindStorageImages 1657 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03027]] 1658 The total number of descriptors with a pname:descriptorType of 1659 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1660 stage across all elements of pname:pSetLayouts must: be less than or 1661 equal to 1662 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindInputAttachments 1663ifdef::VK_EXT_inline_uniform_block[] 1664 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02215]] 1665 The total number of bindings with a pname:descriptorType of 1666 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible to any 1667 given shader stage across all elements of pname:pSetLayouts must: be 1668 less than or equal to 1669 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks 1670endif::VK_EXT_inline_uniform_block[] 1671 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03028]] 1672 The total number of descriptors in descriptor set layouts created 1673 without the 1674 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1675 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1676 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1677 shader stages and across all elements of pname:pSetLayouts must: be less 1678 than or equal to 1679 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSamplers 1680 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03029]] 1681 The total number of descriptors in descriptor set layouts created 1682 without the 1683 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1684 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER 1685 accessible across all shader stages and across all elements of 1686 pname:pSetLayouts must: be less than or equal to 1687 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffers 1688 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03030]] 1689 The total number of descriptors in descriptor set layouts created 1690 without the 1691 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1692 with a pname:descriptorType of 1693 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1694 shader stages and across all elements of pname:pSetLayouts must: be less 1695 than or equal to 1696 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffersDynamic 1697 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03031]] 1698 The total number of descriptors in descriptor set layouts created 1699 without the 1700 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1701 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER 1702 accessible across all shader stages and across all elements of 1703 pname:pSetLayouts must: be less than or equal to 1704 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffers 1705 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03032]] 1706 The total number of descriptors in descriptor set layouts created 1707 without the 1708 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1709 with a pname:descriptorType of 1710 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1711 shader stages and across all elements of pname:pSetLayouts must: be less 1712 than or equal to 1713 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffersDynamic 1714 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03033]] 1715 The total number of descriptors in descriptor set layouts created 1716 without the 1717 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1718 with a pname:descriptorType of 1719 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1720 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1721 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1722 shader stages and across all elements of pname:pSetLayouts must: be less 1723 than or equal to 1724 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSampledImages 1725 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03034]] 1726 The total number of descriptors in descriptor set layouts created 1727 without the 1728 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1729 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 1730 and ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1731 shader stages and across all elements of pname:pSetLayouts must: be less 1732 than or equal to 1733 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageImages 1734 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03035]] 1735 The total number of descriptors in descriptor set layouts created 1736 without the 1737 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1738 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 1739 accessible across all shader stages and across all elements of 1740 pname:pSetLayouts must: be less than or equal to 1741 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetInputAttachments 1742ifdef::VK_EXT_inline_uniform_block[] 1743 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02216]] 1744 The total number of bindings in descriptor set layouts created without 1745 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 1746 set with a pname:descriptorType of 1747 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible across all 1748 shader stages and across all elements of pname:pSetLayouts must: be less 1749 than or equal to 1750 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxDescriptorSetInlineUniformBlocks 1751endif::VK_EXT_inline_uniform_block[] 1752 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03036]] 1753 The total number of descriptors of the type 1754 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1755 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1756 shader stages and across all elements of pname:pSetLayouts must: be less 1757 than or equal to 1758 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindSamplers 1759 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03037]] 1760 The total number of descriptors of the type 1761 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1762 stages and across all elements of pname:pSetLayouts must: be less than 1763 or equal to 1764 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindUniformBuffers 1765 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03038]] 1766 The total number of descriptors of the type 1767 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1768 shader stages and across all elements of pname:pSetLayouts must: be less 1769 than or equal to 1770 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 1771 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03039]] 1772 The total number of descriptors of the type 1773 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1774 stages and across all elements of pname:pSetLayouts must: be less than 1775 or equal to 1776 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageBuffers 1777 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03040]] 1778 The total number of descriptors of the type 1779 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1780 shader stages and across all elements of pname:pSetLayouts must: be less 1781 than or equal to 1782 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 1783 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03041]] 1784 The total number of descriptors of the type 1785 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1786 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1787 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1788 shader stages and across all elements of pname:pSetLayouts must: be less 1789 than or equal to 1790 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindSampledImages 1791 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03042]] 1792 The total number of descriptors of the type 1793 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1794 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1795 shader stages and across all elements of pname:pSetLayouts must: be less 1796 than or equal to 1797 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageImages 1798 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03043]] 1799 The total number of descriptors of the type 1800 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1801 stages and across all elements of pname:pSetLayouts must: be less than 1802 or equal to 1803 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindInputAttachments 1804ifdef::VK_EXT_inline_uniform_block[] 1805 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02217]] 1806 The total number of bindings with a pname:descriptorType of 1807 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT accessible across all 1808 shader stages and across all elements of pname:pSetLayouts must: be less 1809 than or equal to 1810 sname:VkPhysicalDeviceInlineUniformBlockPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindInlineUniformBlocks 1811endif::VK_EXT_inline_uniform_block[] 1812endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1813 * [[VUID-VkPipelineLayoutCreateInfo-pPushConstantRanges-00292]] 1814 Any two elements of pname:pPushConstantRanges must: not include the same 1815 stage in pname:stageFlags 1816ifdef::VK_KHR_push_descriptor[] 1817 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00293]] 1818 pname:pSetLayouts must: not contain more than one descriptor set layout 1819 that was created with 1820 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 1821endif::VK_KHR_push_descriptor[] 1822ifdef::VK_KHR_acceleration_structure[] 1823 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03571]] 1824 The total number of bindings in descriptor set layouts created without 1825 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 1826 set with a pname:descriptorType of 1827 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible to any 1828 given shader stage across all elements of pname:pSetLayouts must: be 1829 less than or equal to 1830 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPerStageDescriptorAccelerationStructures 1831 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03572]] 1832 The total number of bindings with a pname:descriptorType of 1833 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible to any 1834 given shader stage across all elements of pname:pSetLayouts must: be 1835 less than or equal to 1836 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPerStageDescriptorUpdateAfterBindAccelerationStructures 1837 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03573]] 1838 The total number of bindings in descriptor set layouts created without 1839 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 1840 set with a pname:descriptorType of 1841 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible across 1842 all shader stages and across all elements of pname:pSetLayouts must: be 1843 less than or equal to 1844 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxDescriptorSetAccelerationStructures 1845 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03574]] 1846 The total number of bindings with a pname:descriptorType of 1847 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible across 1848 all shader stages and across all elements of pname:pSetLayouts must: be 1849 less than or equal to 1850 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxDescriptorSetUpdateAfterBindAccelerationStructures 1851endif::VK_KHR_acceleration_structure[] 1852ifdef::VK_NV_ray_tracing[] 1853 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02381]] 1854 The total number of bindings with a pname:descriptorType of 1855 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV accessible across all 1856 shader stages and across all elements of pname:pSetLayouts must: be less 1857 than or equal to 1858 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxDescriptorSetAccelerationStructures 1859endif::VK_NV_ray_tracing[] 1860ifdef::VK_EXT_fragment_density_map2[] 1861 * [[VUID-VkPipelineLayoutCreateInfo-pImmutableSamplers-03566]] 1862 The total number of pname:pImmutableSamplers created with pname:flags 1863 containing ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or 1864 ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT across 1865 all shader stages and across all elements of pname:pSetLayouts must: be 1866 less than or equal to 1867 <<limits-maxDescriptorSetSubsampledSamplers,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:maxDescriptorSetSubsampledSamplers>> 1868endif::VK_EXT_fragment_density_map2[] 1869ifdef::VK_VALVE_mutable_descriptor_type[] 1870 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-04606]] 1871 Any element of pname:pSetLayouts must: not have been created with the 1872 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE bit set 1873endif::VK_VALVE_mutable_descriptor_type[] 1874**** 1875 1876include::{generated}/validity/structs/VkPipelineLayoutCreateInfo.txt[] 1877-- 1878 1879[open,refpage='VkPipelineLayoutCreateFlags',desc='Reserved for future use',type='flags'] 1880-- 1881include::{generated}/api/flags/VkPipelineLayoutCreateFlags.txt[] 1882 1883tname:VkPipelineLayoutCreateFlags is a bitmask type for setting a mask, but 1884is currently reserved for future use. 1885-- 1886 1887[open,refpage='VkPushConstantRange',desc='Structure specifying a push constant range',type='structs'] 1888-- 1889The sname:VkPushConstantRange structure is defined as: 1890 1891include::{generated}/api/structs/VkPushConstantRange.txt[] 1892 1893 * pname:stageFlags is a set of stage flags describing the shader stages 1894 that will access a range of push constants. 1895 If a particular stage is not included in the range, then accessing 1896 members of that range of push constants from the corresponding shader 1897 stage will return undefined: values. 1898 * pname:offset and pname:size are the start offset and size, respectively, 1899 consumed by the range. 1900 Both pname:offset and pname:size are in units of bytes and must: be a 1901 multiple of 4. 1902 The layout of the push constant variables is specified in the shader. 1903 1904.Valid Usage 1905**** 1906 * [[VUID-VkPushConstantRange-offset-00294]] 1907 pname:offset must: be less than 1908 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 1909 * [[VUID-VkPushConstantRange-offset-00295]] 1910 pname:offset must: be a multiple of `4` 1911 * [[VUID-VkPushConstantRange-size-00296]] 1912 pname:size must: be greater than `0` 1913 * [[VUID-VkPushConstantRange-size-00297]] 1914 pname:size must: be a multiple of `4` 1915 * [[VUID-VkPushConstantRange-size-00298]] 1916 pname:size must: be less than or equal to 1917 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 1918 pname:offset 1919**** 1920 1921include::{generated}/validity/structs/VkPushConstantRange.txt[] 1922-- 1923 1924Once created, pipeline layouts are used as part of pipeline creation (see 1925<<pipelines, Pipelines>>), as part of binding descriptor sets (see 1926<<descriptorsets-binding, Descriptor Set Binding>>), and as part of setting 1927push constants (see <<descriptorsets-push-constants, Push Constant 1928Updates>>). 1929Pipeline creation accepts a pipeline layout as input, and the layout may: be 1930used to map (set, binding, arrayElement) tuples to implementation resources 1931or memory locations within a descriptor set. 1932The assignment of implementation resources depends only on the bindings 1933defined in the descriptor sets that comprise the pipeline layout, and not on 1934any shader source. 1935 1936[[descriptorsets-pipelinelayout-consistency]] 1937All resource variables <<shaders-staticuse,statically used>> in all shaders 1938in a pipeline must: be declared with a (set,binding,arrayElement) that 1939exists in the corresponding descriptor set layout and is of an appropriate 1940descriptor type and includes the set of shader stages it is used by in 1941pname:stageFlags. 1942The pipeline layout can: include entries that are not used by a particular 1943pipeline, or that are dead-code eliminated from any of the shaders. 1944The pipeline layout allows the application to provide a consistent set of 1945bindings across multiple pipeline compiles, which enables those pipelines to 1946be compiled in a way that the implementation may: cheaply switch pipelines 1947without reprogramming the bindings. 1948 1949Similarly, the push constant block declared in each shader (if present) 1950must: only place variables at offsets that are each included in a push 1951constant range with pname:stageFlags including the bit corresponding to the 1952shader stage that uses it. 1953The pipeline layout can: include ranges or portions of ranges that are not 1954used by a particular pipeline, or for which the variables have been 1955dead-code eliminated from any of the shaders. 1956 1957There is a limit on the total number of resources of each type that can: be 1958included in bindings in all descriptor set layouts in a pipeline layout as 1959shown in <<descriptorsets-pipelinelayout-limits,Pipeline Layout Resource 1960Limits>>. 1961The "`Total Resources Available`" column gives the limit on the number of 1962each type of resource that can: be included in bindings in all descriptor 1963sets in the pipeline layout. 1964Some resource types count against multiple limits. 1965Additionally, there are limits on the total number of each type of resource 1966that can: be used in any pipeline stage as described in 1967<<interfaces-resources-limits,Shader Resource Limits>>. 1968 1969[[descriptorsets-pipelinelayout-limits]] 1970.Pipeline Layout Resource Limits 1971[width="80%",cols="<37,<22",options="header"] 1972|==== 1973| Total Resources Available | Resource Types 1974.2+<.^| pname:maxDescriptorSetSamplers 1975ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1976or pname:maxDescriptorSetUpdateAfterBindSamplers 1977endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1978 | sampler | combined image sampler 1979.3+<.^| pname:maxDescriptorSetSampledImages 1980ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1981or pname:maxDescriptorSetUpdateAfterBindSampledImages 1982endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1983 | sampled image | combined image sampler | uniform texel buffer 1984.2+<.^| pname:maxDescriptorSetStorageImages 1985ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1986or pname:maxDescriptorSetUpdateAfterBindStorageImages 1987endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1988 | storage image | storage texel buffer 1989.2+<.^| pname:maxDescriptorSetUniformBuffers 1990ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1991or pname:maxDescriptorSetUpdateAfterBindUniformBuffers 1992endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1993 | uniform buffer | uniform buffer dynamic 1994| pname:maxDescriptorSetUniformBuffersDynamic 1995ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1996or pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 1997endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1998 | uniform buffer dynamic 1999.2+<.^| pname:maxDescriptorSetStorageBuffers 2000ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2001or pname:maxDescriptorSetUpdateAfterBindStorageBuffers 2002endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2003 | storage buffer | storage buffer dynamic 2004| pname:maxDescriptorSetStorageBuffersDynamic 2005ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2006or pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 2007endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2008 | storage buffer dynamic 2009| pname:maxDescriptorSetInputAttachments 2010ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2011or pname:maxDescriptorSetUpdateAfterBindInputAttachments 2012endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2013 | input attachment 2014ifdef::VK_EXT_inline_uniform_block[] 2015| pname:maxDescriptorSetInlineUniformBlocks 2016ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2017or pname:maxDescriptorSetUpdateAfterBindInlineUniformBlocks 2018endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2019 | inline uniform block 2020endif::VK_EXT_inline_uniform_block[] 2021ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2022| pname:maxDescriptorSetAccelerationStructures 2023ifdef::VK_KHR_acceleration_structure[] 2024or pname:maxDescriptorSetUpdateAfterBindAccelerationStructures 2025endif::VK_KHR_acceleration_structure[] 2026 | acceleration structure 2027endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2028|==== 2029 2030 2031[open,refpage='vkDestroyPipelineLayout',desc='Destroy a pipeline layout object',type='protos'] 2032-- 2033To destroy a pipeline layout, call: 2034 2035include::{generated}/api/protos/vkDestroyPipelineLayout.txt[] 2036 2037 * pname:device is the logical device that destroys the pipeline layout. 2038 * pname:pipelineLayout is the pipeline layout to destroy. 2039 * pname:pAllocator controls host memory allocation as described in the 2040 <<memory-allocation, Memory Allocation>> chapter. 2041 2042.Valid Usage 2043**** 2044 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00299]] 2045 If sname:VkAllocationCallbacks were provided when pname:pipelineLayout 2046 was created, a compatible set of callbacks must: be provided here 2047 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00300]] 2048 If no sname:VkAllocationCallbacks were provided when 2049 pname:pipelineLayout was created, pname:pAllocator must: be `NULL` 2050 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-02004]] 2051 pname:pipelineLayout must: not have been passed to any ftext:vkCmd* 2052 command for any command buffers that are still in the 2053 <<commandbuffers-lifecycle, recording state>> when 2054 fname:vkDestroyPipelineLayout is called 2055**** 2056 2057include::{generated}/validity/protos/vkDestroyPipelineLayout.txt[] 2058-- 2059 2060 2061[[descriptorsets-compatibility]] 2062==== Pipeline Layout Compatibility 2063 2064Two pipeline layouts are defined to be "`compatible for 2065<<descriptorsets-push-constants, push constants>>`" if they were created 2066with identical push constant ranges. 2067Two pipeline layouts are defined to be "`compatible for set N`" if they were 2068created with _identically defined_ descriptor set layouts for sets zero 2069through N, and if they were created with identical push constant ranges. 2070 2071When binding a descriptor set (see <<descriptorsets-binding, Descriptor Set 2072Binding>>) to set number N, if the previously bound descriptor sets for sets 2073zero through N-1 were all bound using compatible pipeline layouts, then 2074performing this binding does not disturb any of the lower numbered sets. 2075If, additionally, the previously bound descriptor set for set N was bound 2076using a pipeline layout compatible for set N, then the bindings in sets 2077numbered greater than N are also not disturbed. 2078 2079Similarly, when binding a pipeline, the pipeline can: correctly access any 2080previously bound descriptor sets which were bound with compatible pipeline 2081layouts, as long as all lower numbered sets were also bound with compatible 2082layouts. 2083 2084Layout compatibility means that descriptor sets can: be bound to a command 2085buffer for use by any pipeline created with a compatible pipeline layout, 2086and without having bound a particular pipeline first. 2087It also means that descriptor sets can: remain valid across a pipeline 2088change, and the same resources will be accessible to the newly bound 2089pipeline. 2090 2091ifdef::implementation-guide[] 2092.Implementor's Note 2093**** 2094A consequence of layout compatibility is that when the implementation 2095compiles a pipeline layout and maps pipeline resources to implementation 2096resources, the mechanism for set N should: only be a function of sets 2097[0..N]. 2098**** 2099endif::implementation-guide[] 2100 2101 2102[NOTE] 2103.Note 2104==== 2105Place the least frequently changing descriptor sets near the start of the 2106pipeline layout, and place the descriptor sets representing the most 2107frequently changing resources near the end. 2108When pipelines are switched, only the descriptor set bindings that have been 2109invalidated will need to be updated and the remainder of the descriptor set 2110bindings will remain in place. 2111==== 2112 2113The maximum number of descriptor sets that can: be bound to a pipeline 2114layout is queried from physical device properties (see 2115pname:maxBoundDescriptorSets in <<limits, Limits>>). 2116 2117.API example 2118[source,c++] 2119--------------------------------------------------- 2120const VkDescriptorSetLayout layouts[] = { layout1, layout2 }; 2121 2122const VkPushConstantRange ranges[] = 2123{ 2124 { 2125 VK_SHADER_STAGE_VERTEX_BIT, // stageFlags 2126 0, // offset 2127 4 // size 2128 }, 2129 2130 { 2131 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 2132 4, // offset 2133 4 // size 2134 }, 2135}; 2136 2137const VkPipelineLayoutCreateInfo createInfo = 2138{ 2139 VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO, // sType 2140 NULL, // pNext 2141 0, // flags 2142 2, // setLayoutCount 2143 layouts, // pSetLayouts 2144 2, // pushConstantRangeCount 2145 ranges // pPushConstantRanges 2146}; 2147 2148VkPipelineLayout myPipelineLayout; 2149myResult = vkCreatePipelineLayout( 2150 myDevice, 2151 &createInfo, 2152 NULL, 2153 &myPipelineLayout); 2154--------------------------------------------------- 2155 2156 2157[[descriptorsets-allocation]] 2158=== Allocation of Descriptor Sets 2159 2160[open,refpage='VkDescriptorPool',desc='Opaque handle to a descriptor pool object',type='handles'] 2161-- 2162A _descriptor pool_ maintains a pool of descriptors, from which descriptor 2163sets are allocated. 2164Descriptor pools are externally synchronized, meaning that the application 2165must: not allocate and/or free descriptor sets from the same pool in 2166multiple threads simultaneously. 2167 2168Descriptor pools are represented by sname:VkDescriptorPool handles: 2169 2170include::{generated}/api/handles/VkDescriptorPool.txt[] 2171 2172-- 2173 2174[open,refpage='vkCreateDescriptorPool',desc='Creates a descriptor pool object',type='protos'] 2175-- 2176To create a descriptor pool object, call: 2177 2178include::{generated}/api/protos/vkCreateDescriptorPool.txt[] 2179 2180 * pname:device is the logical device that creates the descriptor pool. 2181 * pname:pCreateInfo is a pointer to a slink:VkDescriptorPoolCreateInfo 2182 structure specifying the state of the descriptor pool object. 2183 * pname:pAllocator controls host memory allocation as described in the 2184 <<memory-allocation, Memory Allocation>> chapter. 2185 * pname:pDescriptorPool is a pointer to a slink:VkDescriptorPool handle in 2186 which the resulting descriptor pool object is returned. 2187 2188The created descriptor pool is returned in pname:pDescriptorPool. 2189 2190include::{generated}/validity/protos/vkCreateDescriptorPool.txt[] 2191-- 2192 2193[open,refpage='VkDescriptorPoolCreateInfo',desc='Structure specifying parameters of a newly created descriptor pool',type='structs'] 2194-- 2195Additional information about the pool is passed in a 2196sname:VkDescriptorPoolCreateInfo structure: 2197 2198include::{generated}/api/structs/VkDescriptorPoolCreateInfo.txt[] 2199 2200 * pname:sType is the type of this structure. 2201 * pname:pNext is `NULL` or a pointer to a structure extending this 2202 structure. 2203 * pname:flags is a bitmask of elink:VkDescriptorPoolCreateFlagBits 2204 specifying certain supported operations on the pool. 2205 * pname:maxSets is the maximum number of descriptor sets that can: be 2206 allocated from the pool. 2207 * pname:poolSizeCount is the number of elements in pname:pPoolSizes. 2208 * pname:pPoolSizes is a pointer to an array of slink:VkDescriptorPoolSize 2209 structures, each containing a descriptor type and number of descriptors 2210 of that type to be allocated in the pool. 2211 2212If multiple sname:VkDescriptorPoolSize structures containing the same 2213descriptor type appear in the pname:pPoolSizes array then the pool will be 2214created with enough storage for the total number of descriptors of each 2215type. 2216 2217Fragmentation of a descriptor pool is possible and may: lead to descriptor 2218set allocation failures. 2219A failure due to fragmentation is defined as failing a descriptor set 2220allocation despite the sum of all outstanding descriptor set allocations 2221from the pool plus the requested allocation requiring no more than the total 2222number of descriptors requested at pool creation. 2223Implementations provide certain guarantees of when fragmentation must: not 2224cause allocation failure, as described below. 2225 2226If a descriptor pool has not had any descriptor sets freed since it was 2227created or most recently reset then fragmentation must: not cause an 2228allocation failure (note that this is always the case for a pool created 2229without the ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT bit 2230set). 2231Additionally, if all sets allocated from the pool since it was created or 2232most recently reset use the same number of descriptors (of each type) and 2233the requested allocation also uses that same number of descriptors (of each 2234type), then fragmentation must: not cause an allocation failure. 2235 2236If an allocation failure occurs due to fragmentation, an application can: 2237create an additional descriptor pool to perform further descriptor set 2238allocations. 2239 2240ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2241If pname:flags has the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT 2242bit set, descriptor pool creation may: fail with the error 2243ename:VK_ERROR_FRAGMENTATION if the total number of descriptors across all 2244pools (including this one) created with this bit set exceeds 2245pname:maxUpdateAfterBindDescriptorsInAllPools, or if fragmentation of the 2246underlying hardware resources occurs. 2247endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2248 2249ifdef::VK_VALVE_mutable_descriptor_type[] 2250If a pname:pPoolSizes[i]::pname:type is 2251ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, a 2252slink:VkMutableDescriptorTypeCreateInfoVALVE struct in the pname:pNext chain 2253can: be used to specify which mutable descriptor types can: be allocated 2254from the pool. 2255If present in the pname:pNext chain, 2256slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pMutableDescriptorTypeLists[i] 2257specifies which kind of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptors 2258can: be allocated from this pool entry. 2259If slink:VkMutableDescriptorTypeCreateInfoVALVE does not exist in the 2260pname:pNext chain, or 2261slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pMutableDescriptorTypeLists[i] 2262is out of range, the descriptor pool allocates enough memory to be able to 2263allocate a ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE descriptor with any 2264supported elink:VkDescriptorType as a mutable descriptor. 2265A mutable descriptor can: be allocated from a pool entry if the type list in 2266slink:VkDescriptorSetLayoutCreateInfo is a subset of the type list declared 2267in the descriptor pool, or if the pool entry is created without a descriptor 2268type list. 2269Multiple pname:pPoolSizes entries with 2270ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE can: be declared. 2271When multiple such pool entries are present in pname:pPoolSizes, they 2272specify sets of supported descriptor types which either fully overlap, 2273partially overlap, or are disjoint. 2274Two sets fully overlap if the sets of supported descriptor types are equal. 2275If the sets are not disjoint they partially overlap. 2276A pool entry without a sname:VkMutableDescriptorTypeListVALVE assigned to it 2277is considered to partially overlap any other pool entry which has a 2278sname:VkMutableDescriptorTypeListVALVE assigned to it. 2279The application must: ensure that partial overlap does not exist in 2280pname:pPoolSizes. 2281 2282[NOTE] 2283.Note 2284==== 2285The requirement of no partial overlap is intended to resolve ambiguity for 2286validation as there is no confusion which pname:pPoolSizes entries will be 2287allocated from. 2288An implementation is not expected to depend on this requirement. 2289==== 2290endif::VK_VALVE_mutable_descriptor_type[] 2291 2292.Valid Usage 2293**** 2294 * [[VUID-VkDescriptorPoolCreateInfo-maxSets-00301]] 2295 pname:maxSets must: be greater than `0` 2296ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2297ifdef::VK_VALVE_mutable_descriptor_type[] 2298 * [[VUID-VkDescriptorPoolCreateInfo-flags-04607]] 2299 If pname:flags has the 2300 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE bit set, then the 2301 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT bit must: not be 2302 set 2303endif::VK_VALVE_mutable_descriptor_type[] 2304endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2305ifdef::VK_VALVE_mutable_descriptor_type[] 2306 * [[VUID-VkDescriptorPoolCreateInfo-mutableDescriptorType-04608]] 2307 If 2308 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::pname:mutableDescriptorType 2309 is not enabled, pname:pPoolSizes must: not contain a 2310 pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 2311 * [[VUID-VkDescriptorPoolCreateInfo-flags-04609]] 2312 If pname:flags has the 2313 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE bit set, 2314 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::pname:mutableDescriptorType 2315 must: be enabled 2316 * [[VUID-VkDescriptorPoolCreateInfo-pPoolSizes-04787]] 2317 If pname:pPoolSizes contains a pname:descriptorType of 2318 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, any other 2319 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE element in pname:pPoolSizes must: 2320 not have sets of supported descriptor types which partially overlap 2321endif::VK_VALVE_mutable_descriptor_type[] 2322**** 2323 2324include::{generated}/validity/structs/VkDescriptorPoolCreateInfo.txt[] 2325-- 2326 2327ifdef::VK_EXT_inline_uniform_block[] 2328[open,refpage='VkDescriptorPoolInlineUniformBlockCreateInfoEXT',desc='Structure specifying the maximum number of inline uniform block bindings of a newly created descriptor pool',type='structs'] 2329-- 2330In order to be able to allocate descriptor sets having 2331<<descriptorsets-inlineuniformblock, inline uniform block>> bindings the 2332descriptor pool must: be created with specifying the inline uniform block 2333binding capacity of the descriptor pool, in addition to the total inline 2334uniform data capacity in bytes which is specified through a 2335slink:VkDescriptorPoolSize structure with a pname:descriptorType value of 2336ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT. 2337This can: be done by adding a 2338sname:VkDescriptorPoolInlineUniformBlockCreateInfoEXT structure to the 2339pname:pNext chain of slink:VkDescriptorPoolCreateInfo. 2340 2341The sname:VkDescriptorPoolInlineUniformBlockCreateInfoEXT structure is 2342defined as: 2343 2344include::{generated}/api/structs/VkDescriptorPoolInlineUniformBlockCreateInfoEXT.txt[] 2345 2346 * pname:sType is the type of this structure. 2347 * pname:pNext is `NULL` or a pointer to a structure extending this 2348 structure. 2349 * pname:maxInlineUniformBlockBindings is the number of inline uniform 2350 block bindings to allocate. 2351 2352include::{generated}/validity/structs/VkDescriptorPoolInlineUniformBlockCreateInfoEXT.txt[] 2353-- 2354endif::VK_EXT_inline_uniform_block[] 2355 2356[open,refpage='VkDescriptorPoolCreateFlagBits',desc='Bitmask specifying certain supported operations on a descriptor pool',type='enums'] 2357-- 2358Bits which can: be set in slink:VkDescriptorPoolCreateInfo::pname:flags to 2359enable operations on a descriptor pool are: 2360 2361include::{generated}/api/enums/VkDescriptorPoolCreateFlagBits.txt[] 2362 2363 * ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT specifies that 2364 descriptor sets can: return their individual allocations to the pool, 2365 i.e. all of flink:vkAllocateDescriptorSets, flink:vkFreeDescriptorSets, 2366 and flink:vkResetDescriptorPool are allowed. 2367 Otherwise, descriptor sets allocated from the pool must: not be 2368 individually freed back to the pool, i.e. only 2369 flink:vkAllocateDescriptorSets and flink:vkResetDescriptorPool are 2370 allowed. 2371ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2372 * ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT specifies that 2373 descriptor sets allocated from this pool can: include bindings with the 2374 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set. 2375 It is valid to allocate descriptor sets that have bindings that do not 2376 set the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit from a 2377 pool that has ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT set. 2378endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2379ifdef::VK_VALVE_mutable_descriptor_type[] 2380 * ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE specifies that this 2381 descriptor pool and the descriptor sets allocated from it reside 2382 entirely in host memory and cannot be bound. 2383 Descriptor sets allocated from this pool are partially exempt from the 2384 external synchronization requirement in 2385ifdef::VK_KHR_descriptor_update_template[] 2386 flink:vkUpdateDescriptorSetWithTemplateKHR and 2387endif::VK_KHR_descriptor_update_template[] 2388 flink:vkUpdateDescriptorSets. 2389 Descriptor sets and their descriptors can be updated concurrently in 2390 different threads, though the same descriptor must: not be updated 2391 concurrently by two threads. 2392endif::VK_VALVE_mutable_descriptor_type[] 2393-- 2394 2395[open,refpage='VkDescriptorPoolCreateFlags',desc='Bitmask of VkDescriptorPoolCreateFlagBits',type='flags'] 2396-- 2397include::{generated}/api/flags/VkDescriptorPoolCreateFlags.txt[] 2398 2399tname:VkDescriptorPoolCreateFlags is a bitmask type for setting a mask of 2400zero or more elink:VkDescriptorPoolCreateFlagBits. 2401-- 2402 2403[open,refpage='VkDescriptorPoolSize',desc='Structure specifying descriptor pool size',type='structs'] 2404-- 2405The sname:VkDescriptorPoolSize structure is defined as: 2406 2407include::{generated}/api/structs/VkDescriptorPoolSize.txt[] 2408 2409 * pname:type is the type of descriptor. 2410 * pname:descriptorCount is the number of descriptors of that type to 2411 allocate. 2412ifdef::VK_EXT_inline_uniform_block[] 2413 If pname:type is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 2414 pname:descriptorCount is the number of bytes to allocate for descriptors 2415 of this type. 2416endif::VK_EXT_inline_uniform_block[] 2417 2418ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2419[NOTE] 2420.Note 2421==== 2422When creating a descriptor pool that will contain descriptors for combined 2423image samplers of multi-planar formats, an application needs to account for 2424non-trivial descriptor consumption when choosing the pname:descriptorCount 2425value, as indicated by 2426slink:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount. 2427==== 2428endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2429 2430.Valid Usage 2431**** 2432 * [[VUID-VkDescriptorPoolSize-descriptorCount-00302]] 2433 pname:descriptorCount must: be greater than `0` 2434ifdef::VK_EXT_inline_uniform_block[] 2435 * [[VUID-VkDescriptorPoolSize-type-02218]] 2436 If pname:type is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 2437 pname:descriptorCount must: be a multiple of `4` 2438endif::VK_EXT_inline_uniform_block[] 2439**** 2440 2441include::{generated}/validity/structs/VkDescriptorPoolSize.txt[] 2442-- 2443 2444[open,refpage='vkDestroyDescriptorPool',desc='Destroy a descriptor pool object',type='protos'] 2445-- 2446To destroy a descriptor pool, call: 2447 2448include::{generated}/api/protos/vkDestroyDescriptorPool.txt[] 2449 2450 * pname:device is the logical device that destroys the descriptor pool. 2451 * pname:descriptorPool is the descriptor pool to destroy. 2452 * pname:pAllocator controls host memory allocation as described in the 2453 <<memory-allocation, Memory Allocation>> chapter. 2454 2455When a pool is destroyed, all descriptor sets allocated from the pool are 2456implicitly freed and become invalid. 2457Descriptor sets allocated from a given pool do not need to be freed before 2458destroying that descriptor pool. 2459 2460.Valid Usage 2461**** 2462 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00303]] 2463 All submitted commands that refer to pname:descriptorPool (via any 2464 allocated descriptor sets) must: have completed execution 2465 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00304]] 2466 If sname:VkAllocationCallbacks were provided when pname:descriptorPool 2467 was created, a compatible set of callbacks must: be provided here 2468 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00305]] 2469 If no sname:VkAllocationCallbacks were provided when 2470 pname:descriptorPool was created, pname:pAllocator must: be `NULL` 2471**** 2472 2473include::{generated}/validity/protos/vkDestroyDescriptorPool.txt[] 2474-- 2475 2476[open,refpage='VkDescriptorSet',desc='Opaque handle to a descriptor set object',type='handles'] 2477-- 2478Descriptor sets are allocated from descriptor pool objects, and are 2479represented by sname:VkDescriptorSet handles: 2480 2481include::{generated}/api/handles/VkDescriptorSet.txt[] 2482-- 2483 2484[open,refpage='vkAllocateDescriptorSets',desc='Allocate one or more descriptor sets',type='protos'] 2485-- 2486To allocate descriptor sets from a descriptor pool, call: 2487 2488include::{generated}/api/protos/vkAllocateDescriptorSets.txt[] 2489 2490 * pname:device is the logical device that owns the descriptor pool. 2491 * pname:pAllocateInfo is a pointer to a slink:VkDescriptorSetAllocateInfo 2492 structure describing parameters of the allocation. 2493 * pname:pDescriptorSets is a pointer to an array of slink:VkDescriptorSet 2494 handles in which the resulting descriptor set objects are returned. 2495 2496The allocated descriptor sets are returned in pname:pDescriptorSets. 2497 2498When a descriptor set is allocated, the initial state is largely 2499uninitialized and all descriptors are undefined:. 2500Descriptors also become undefined: if the underlying resource is destroyed. 2501Descriptor sets containing undefined: descriptors can: still be bound and 2502used, subject to the following conditions: 2503 2504ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2505 * For descriptor set bindings created with the 2506 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT bit set, all descriptors 2507 in that binding that are dynamically used must: have been populated 2508 before the descriptor set is <<descriptorsets-binding,consumed>>. 2509 * For descriptor set bindings created without the 2510 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT bit set, all descriptors 2511 in that binding that are statically used must: have been populated 2512 before the descriptor set is <<descriptorsets-binding,consumed>>. 2513endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2514ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2515 * Descriptors that are <<shaders-staticuse,statically used>> must: have 2516 been populated before the descriptor set is 2517 <<descriptorsets-binding,consumed>>. 2518endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2519ifdef::VK_EXT_inline_uniform_block[] 2520 * Descriptor bindings with descriptor type of 2521 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT can: be undefined: 2522 when the descriptor set is <<descriptorsets-binding,consumed>>; though 2523 values in that block will be undefined:. 2524endif::VK_EXT_inline_uniform_block[] 2525 * Entries that are not used by a pipeline can: have undefined: 2526 descriptors. 2527 2528ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2529If a call to fname:vkAllocateDescriptorSets would cause the total number of 2530descriptor sets allocated from the pool to exceed the value of 2531slink:VkDescriptorPoolCreateInfo::pname:maxSets used to create 2532pname:pAllocateInfo->descriptorPool, then the allocation may: fail due to 2533lack of space in the descriptor pool. 2534Similarly, the allocation may: fail due to lack of space if the call to 2535fname:vkAllocateDescriptorSets would cause the number of any given 2536descriptor type to exceed the sum of all the pname:descriptorCount members 2537of each element of slink:VkDescriptorPoolCreateInfo::pname:pPoolSizes with a 2538pname:type equal to that type. 2539 2540ifdef::VK_EXT_inline_uniform_block[] 2541Additionally, the allocation may: also fail if a call to 2542fname:vkAllocateDescriptorSets would cause the total number of inline 2543uniform block bindings allocated from the pool to exceed the value of 2544slink:VkDescriptorPoolInlineUniformBlockCreateInfoEXT::pname:maxInlineUniformBlockBindings 2545used to create the descriptor pool. 2546endif::VK_EXT_inline_uniform_block[] 2547 2548If the allocation fails due to no more space in the descriptor pool, and not 2549because of system or device memory exhaustion, then 2550ename:VK_ERROR_OUT_OF_POOL_MEMORY must: be returned. 2551endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2552 2553ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2554If an allocation fails due to fragmentation, an indeterminate error is 2555returned with an unspecified error code. 2556Any returned error other than 2557ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2558ename:VK_ERROR_OUT_OF_POOL_MEMORY or 2559endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2560ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: 2561applications should: assume that the allocation failed due to fragmentation, 2562and create a new descriptor pool. 2563endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2564 2565ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2566fname:vkAllocateDescriptorSets can: be used to create multiple descriptor 2567sets. 2568If the creation of any of those descriptor sets fails, then the 2569implementation must: destroy all successfully created descriptor set objects 2570from this command, set all entries of the pname:pDescriptorSets array to 2571dlink:VK_NULL_HANDLE and return the error. 2572endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2573 2574ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2575[NOTE] 2576.Note 2577==== 2578Applications should: check for a negative return value when allocating new 2579descriptor sets, assume that any error 2580ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2581other than ename:VK_ERROR_OUT_OF_POOL_MEMORY 2582endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2583effectively means ename:VK_ERROR_FRAGMENTED_POOL, and try to create a new 2584descriptor pool. 2585If ename:VK_ERROR_FRAGMENTED_POOL is the actual return value, it adds 2586certainty to that decision. 2587 2588The reason for this is that ename:VK_ERROR_FRAGMENTED_POOL was only added in 2589a later version of the 1.0 specification, and so drivers may: return other 2590errors if they were written against earlier versions. 2591To ensure full compatibility with earlier patch versions, these other errors 2592are allowed. 2593==== 2594endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2595 2596include::{generated}/validity/protos/vkAllocateDescriptorSets.txt[] 2597-- 2598 2599[open,refpage='VkDescriptorSetAllocateInfo',desc='Structure specifying the allocation parameters for descriptor sets',type='structs'] 2600-- 2601The sname:VkDescriptorSetAllocateInfo structure is defined as: 2602 2603include::{generated}/api/structs/VkDescriptorSetAllocateInfo.txt[] 2604 2605 * pname:sType is the type of this structure. 2606 * pname:pNext is `NULL` or a pointer to a structure extending this 2607 structure. 2608 * pname:descriptorPool is the pool which the sets will be allocated from. 2609 * pname:descriptorSetCount determines the number of descriptor sets to be 2610 allocated from the pool. 2611 * pname:pSetLayouts is a pointer to an array of descriptor set layouts, 2612 with each member specifying how the corresponding descriptor set is 2613 allocated. 2614 2615.Valid Usage 2616**** 2617ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2618 * [[VUID-VkDescriptorSetAllocateInfo-descriptorSetCount-00306]] 2619 pname:descriptorSetCount must: not be greater than the number of sets 2620 that are currently available for allocation in pname:descriptorPool 2621 * [[VUID-VkDescriptorSetAllocateInfo-descriptorPool-00307]] 2622 pname:descriptorPool must: have enough free descriptor capacity 2623 remaining to allocate the descriptor sets of the specified layouts 2624endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2625ifdef::VK_KHR_push_descriptor[] 2626 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-00308]] 2627 Each element of pname:pSetLayouts must: not have been created with 2628 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 2629endif::VK_KHR_push_descriptor[] 2630ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2631 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-03044]] 2632 If any element of pname:pSetLayouts was created with the 2633 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 2634 set, pname:descriptorPool must: have been created with the 2635 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 2636endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2637ifdef::VK_VALVE_mutable_descriptor_type[] 2638 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-04610]] 2639 If any element of pname:pSetLayouts was created with the 2640 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE bit set, 2641 pname:descriptorPool must: have been created with the 2642 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE flag set 2643endif::VK_VALVE_mutable_descriptor_type[] 2644**** 2645 2646include::{generated}/validity/structs/VkDescriptorSetAllocateInfo.txt[] 2647-- 2648 2649ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2650[open,refpage='VkDescriptorSetVariableDescriptorCountAllocateInfo',desc='Structure specifying additional allocation parameters for descriptor sets',type='structs',alias='VkDescriptorSetVariableDescriptorCountAllocateInfoEXT'] 2651-- 2652If the pname:pNext chain of a slink:VkDescriptorSetAllocateInfo structure 2653includes a sname:VkDescriptorSetVariableDescriptorCountAllocateInfo 2654structure, then that structure includes an array of descriptor counts for 2655variable descriptor count bindings, one for each descriptor set being 2656allocated. 2657 2658The sname:VkDescriptorSetVariableDescriptorCountAllocateInfo structure is 2659defined as: 2660 2661include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountAllocateInfo.txt[] 2662 2663ifdef::VK_EXT_descriptor_indexing[] 2664or the equivalent 2665 2666include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountAllocateInfoEXT.txt[] 2667endif::VK_EXT_descriptor_indexing[] 2668 2669 * pname:sType is the type of this structure. 2670 * pname:pNext is `NULL` or a pointer to a structure extending this 2671 structure. 2672 * pname:descriptorSetCount is zero or the number of elements in 2673 pname:pDescriptorCounts. 2674 * pname:pDescriptorCounts is a pointer to an array of descriptor counts, 2675 with each member specifying the number of descriptors in a variable 2676 descriptor count binding in the corresponding descriptor set being 2677 allocated. 2678 2679If pname:descriptorSetCount is zero or this structure is not included in the 2680pname:pNext chain, then the variable lengths are considered to be zero. 2681Otherwise, pname:pDescriptorCounts[i] is the number of descriptors in the 2682variable count descriptor binding in the corresponding descriptor set 2683layout. 2684ifdef::VK_EXT_inline_uniform_block[] 2685If the variable count descriptor binding in the corresponding descriptor set 2686layout has a descriptor type of 2687ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 2688pname:pDescriptorCounts[i] specifies the binding's capacity in bytes. 2689endif::VK_EXT_inline_uniform_block[] 2690If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] does not include 2691a variable count descriptor binding, then pname:pDescriptorCounts[i] is 2692ignored. 2693 2694.Valid Usage 2695**** 2696 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfo-descriptorSetCount-03045]] 2697 If pname:descriptorSetCount is not zero, pname:descriptorSetCount must: 2698 equal slink:VkDescriptorSetAllocateInfo::pname:descriptorSetCount 2699 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfo-pSetLayouts-03046]] 2700 If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] has a 2701 variable descriptor count binding, then pname:pDescriptorCounts[i] must: 2702 be less than or equal to the descriptor count specified for that binding 2703 when the descriptor set layout was created 2704**** 2705 2706include::{generated}/validity/structs/VkDescriptorSetVariableDescriptorCountAllocateInfo.txt[] 2707-- 2708endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2709 2710[open,refpage='vkFreeDescriptorSets',desc='Free one or more descriptor sets',type='protos'] 2711-- 2712To free allocated descriptor sets, call: 2713 2714include::{generated}/api/protos/vkFreeDescriptorSets.txt[] 2715 2716 * pname:device is the logical device that owns the descriptor pool. 2717 * pname:descriptorPool is the descriptor pool from which the descriptor 2718 sets were allocated. 2719 * pname:descriptorSetCount is the number of elements in the 2720 pname:pDescriptorSets array. 2721 * pname:pDescriptorSets is a pointer to an array of handles to 2722 slink:VkDescriptorSet objects. 2723 2724After calling fname:vkFreeDescriptorSets, all descriptor sets in 2725pname:pDescriptorSets are invalid. 2726 2727.Valid Usage 2728**** 2729 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00309]] 2730 All submitted commands that refer to any element of 2731 pname:pDescriptorSets must: have completed execution 2732 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00310]] 2733 pname:pDescriptorSets must: be a valid pointer to an array of 2734 pname:descriptorSetCount sname:VkDescriptorSet handles, each element of 2735 which must: either be a valid handle or dlink:VK_NULL_HANDLE 2736 * [[VUID-vkFreeDescriptorSets-descriptorPool-00312]] 2737 pname:descriptorPool must: have been created with the 2738 ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT flag 2739**** 2740 2741include::{generated}/validity/protos/vkFreeDescriptorSets.txt[] 2742-- 2743 2744[open,refpage='vkResetDescriptorPool',desc='Resets a descriptor pool object',type='protos'] 2745-- 2746To return all descriptor sets allocated from a given pool to the pool, 2747rather than freeing individual descriptor sets, call: 2748 2749include::{generated}/api/protos/vkResetDescriptorPool.txt[] 2750 2751 * pname:device is the logical device that owns the descriptor pool. 2752 * pname:descriptorPool is the descriptor pool to be reset. 2753 * pname:flags is reserved for future use. 2754 2755Resetting a descriptor pool recycles all of the resources from all of the 2756descriptor sets allocated from the descriptor pool back to the descriptor 2757pool, and the descriptor sets are implicitly freed. 2758 2759.Valid Usage 2760**** 2761 * [[VUID-vkResetDescriptorPool-descriptorPool-00313]] 2762 All uses of pname:descriptorPool (via any allocated descriptor sets) 2763 must: have completed execution 2764**** 2765 2766include::{generated}/validity/protos/vkResetDescriptorPool.txt[] 2767-- 2768 2769[open,refpage='VkDescriptorPoolResetFlags',desc='Reserved for future use',type='flags'] 2770-- 2771include::{generated}/api/flags/VkDescriptorPoolResetFlags.txt[] 2772 2773tname:VkDescriptorPoolResetFlags is a bitmask type for setting a mask, but 2774is currently reserved for future use. 2775-- 2776 2777 2778[[descriptorsets-updates]] 2779=== Descriptor Set Updates 2780 2781[open,refpage='vkUpdateDescriptorSets',desc='Update the contents of a descriptor set object',type='protos'] 2782-- 2783Once allocated, descriptor sets can: be updated with a combination of write 2784and copy operations. 2785To update descriptor sets, call: 2786 2787include::{generated}/api/protos/vkUpdateDescriptorSets.txt[] 2788 2789 * pname:device is the logical device that updates the descriptor sets. 2790 * pname:descriptorWriteCount is the number of elements in the 2791 pname:pDescriptorWrites array. 2792 * pname:pDescriptorWrites is a pointer to an array of 2793 slink:VkWriteDescriptorSet structures describing the descriptor sets to 2794 write to. 2795 * pname:descriptorCopyCount is the number of elements in the 2796 pname:pDescriptorCopies array. 2797 * pname:pDescriptorCopies is a pointer to an array of 2798 slink:VkCopyDescriptorSet structures describing the descriptor sets to 2799 copy between. 2800 2801The operations described by pname:pDescriptorWrites are performed first, 2802followed by the operations described by pname:pDescriptorCopies. 2803Within each array, the operations are performed in the order they appear in 2804the array. 2805 2806Each element in the pname:pDescriptorWrites array describes an operation 2807updating the descriptor set using descriptors for resources specified in the 2808structure. 2809 2810Each element in the pname:pDescriptorCopies array is a 2811slink:VkCopyDescriptorSet structure describing an operation copying 2812descriptors between sets. 2813 2814If the pname:dstSet member of any element of pname:pDescriptorWrites or 2815pname:pDescriptorCopies is bound, accessed, or modified by any command that 2816was recorded to a command buffer which is currently in the 2817<<commandbuffers-lifecycle, recording or executable state>>, 2818ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2819and any of the descriptor bindings that are updated were not created with 2820the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT or 2821ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT bits set, 2822endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2823that command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2824 2825.Valid Usage 2826**** 2827 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06236]] 2828 For each element [eq]#i# where 2829 pname:pDescriptorWrites[i].pname:descriptorType is 2830 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 2831 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, elements of the 2832 pname:pTexelBufferView member of pname:pDescriptorWrites[i] must: have 2833 been created on pname:device 2834 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06237]] 2835 For each element [eq]#i# where 2836 pname:pDescriptorWrites[i].pname:descriptorType is 2837 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 2838 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 2839 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 2840 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:buffer member 2841 of any element of the pname:pBufferInfo member of 2842 pname:pDescriptorWrites[i] must: have been created on pname:device 2843 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06238]] 2844 For each element [eq]#i# where 2845 pname:pDescriptorWrites[i].pname:descriptorType is 2846 ename:VK_DESCRIPTOR_TYPE_SAMPLER or 2847 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 2848 not allocated with a layout that included immutable samplers for 2849 pname:dstBinding with pname:descriptorType, the pname:sampler member of 2850 any element of the pname:pImageInfo member of pname:pDescriptorWrites[i] 2851 must: have been created on pname:device 2852 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06239]] 2853 For each element [eq]#i# where 2854 pname:pDescriptorWrites[i].pname:descriptorType is 2855 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2856 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 2857 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, or 2858 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER the pname:imageView 2859 member of any element of pname:pDescriptorWrites[i] must: have been 2860 created on pname:device 2861ifdef::VK_KHR_acceleration_structure[] 2862 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06240]] 2863 For each element [eq]#i# where 2864 pname:pDescriptorWrites[i].pname:descriptorType is 2865 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, elements of the 2866 pname:pAccelerationStructures member of a 2867 slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 2868 pname:pNext chain of pname:pDescriptorWrites[i] must: have been created 2869 on pname:device 2870endif::VK_KHR_acceleration_structure[] 2871ifdef::VK_NV_ray_tracing[] 2872 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06241]] 2873 For each element [eq]#i# where 2874 pname:pDescriptorWrites[i].pname:descriptorType is 2875 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, elements of the 2876 pname:pAccelerationStructures member of a 2877 slink:VkWriteDescriptorSetAccelerationStructureNV structure in the 2878 pname:pNext chain of pname:pDescriptorWrites[i] must: have been created 2879 on pname:device 2880endif::VK_NV_ray_tracing[] 2881ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2882 * [[VUID-vkUpdateDescriptorSets-dstSet-00314]] 2883 The pname:dstSet member of each element of pname:pDescriptorWrites or 2884 pname:pDescriptorCopies must: not be used by any command that was 2885 recorded to a command buffer which is in the <<commandbuffers-lifecycle, 2886 pending state>> 2887endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2888ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2889 * [[VUID-vkUpdateDescriptorSets-None-03047]] 2890 Descriptor bindings updated by this command which were created without 2891 the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT or 2892 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT bits set 2893 must: not be used by any command that was recorded to a command buffer 2894 which is in the <<commandbuffers-lifecycle,pending state>> 2895endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2896**** 2897 2898include::{generated}/validity/protos/vkUpdateDescriptorSets.txt[] 2899-- 2900 2901[open,refpage='VkWriteDescriptorSet',desc='Structure specifying the parameters of a descriptor set write operation',type='structs'] 2902-- 2903The sname:VkWriteDescriptorSet structure is defined as: 2904 2905include::{generated}/api/structs/VkWriteDescriptorSet.txt[] 2906 2907 * pname:sType is the type of this structure. 2908 * pname:pNext is `NULL` or a pointer to a structure extending this 2909 structure. 2910 * pname:dstSet is the destination descriptor set to update. 2911 * pname:dstBinding is the descriptor binding within that set. 2912 * pname:dstArrayElement is the starting element in that array. 2913ifdef::VK_EXT_inline_uniform_block[] 2914 If the descriptor binding identified by pname:dstSet and 2915 pname:dstBinding has a descriptor type of 2916 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 2917 pname:dstArrayElement specifies the starting byte offset within the 2918 binding. 2919endif::VK_EXT_inline_uniform_block[] 2920 * pname:descriptorCount is the number of descriptors to update. 2921ifdef::VK_EXT_inline_uniform_block[] 2922 If the descriptor binding identified by pname:dstSet and 2923 pname:dstBinding has a descriptor type of 2924 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, then 2925 pname:descriptorCount specifies the number of bytes to update. 2926 Otherwise, 2927endif::VK_EXT_inline_uniform_block[] 2928 pname:descriptorCount is one of 2929 ** the number of elements in pname:pImageInfo 2930 ** the number of elements in pname:pBufferInfo 2931 ** the number of elements in pname:pTexelBufferView 2932ifdef::VK_EXT_inline_uniform_block[] 2933 ** a value matching the pname:dataSize member of a 2934 slink:VkWriteDescriptorSetInlineUniformBlockEXT structure in the 2935 pname:pNext chain 2936endif::VK_EXT_inline_uniform_block[] 2937ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2938 ** a value matching the pname:accelerationStructureCount of a 2939 slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 2940 pname:pNext chain 2941endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2942 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 2943 each descriptor in pname:pImageInfo, pname:pBufferInfo, or 2944 pname:pTexelBufferView, as described below. 2945ifdef::VK_VALVE_mutable_descriptor_type[] 2946 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 2947 pname:dstBinding is not equal to ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, 2948 pname:descriptorType must: 2949endif::VK_VALVE_mutable_descriptor_type[] 2950ifndef::VK_VALVE_mutable_descriptor_type[] 2951 It must: 2952endif::VK_VALVE_mutable_descriptor_type[] 2953 be the same type as that specified in sname:VkDescriptorSetLayoutBinding 2954 for pname:dstSet at pname:dstBinding. 2955 The type of the descriptor also controls which array the descriptors are 2956 taken from. 2957 * pname:pImageInfo is a pointer to an array of slink:VkDescriptorImageInfo 2958 structures or is ignored, as described below. 2959 * pname:pBufferInfo is a pointer to an array of 2960 slink:VkDescriptorBufferInfo structures or is ignored, as described 2961 below. 2962 * pname:pTexelBufferView is a pointer to an array of slink:VkBufferView 2963 handles as described in the <<resources-buffer-views,Buffer Views>> 2964 section or is ignored, as described below. 2965 2966Only one of pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView 2967members is used according to the descriptor type specified in the 2968pname:descriptorType member of the containing sname:VkWriteDescriptorSet 2969structure, 2970ifdef::VK_EXT_inline_uniform_block[] 2971or none of them in case pname:descriptorType is 2972ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, in which case the source 2973data for the descriptor writes is taken from the 2974slink:VkWriteDescriptorSetInlineUniformBlockEXT structure included in the 2975pname:pNext chain of sname:VkWriteDescriptorSet, 2976endif::VK_EXT_inline_uniform_block[] 2977ifdef::VK_KHR_acceleration_structure[] 2978or if pname:descriptorType is 2979ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, in which case the 2980source data for the descriptor writes is taken from the 2981slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 2982pname:pNext chain of sname:VkWriteDescriptorSet, 2983endif::VK_KHR_acceleration_structure[] 2984ifdef::VK_NV_ray_tracing[] 2985or if pname:descriptorType is 2986ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, in which case the source 2987data for the descriptor writes is taken from the 2988slink:VkWriteDescriptorSetAccelerationStructureNV structure in the 2989pname:pNext chain of sname:VkWriteDescriptorSet, 2990endif::VK_NV_ray_tracing[] 2991as specified below. 2992 2993ifdef::VK_EXT_robustness2[] 2994If the <<features-nullDescriptor,nullDescriptor>> feature is enabled, the 2995buffer, 2996ifdef::VK_KHR_acceleration_structure[] 2997acceleration structure, 2998endif::VK_KHR_acceleration_structure[] 2999imageView, or bufferView can: be dlink:VK_NULL_HANDLE. 3000Loads from a null descriptor return zero values and stores and atomics to a 3001null descriptor are discarded. 3002ifdef::VK_KHR_acceleration_structure[] 3003A null acceleration structure descriptor results in the miss shader being 3004invoked. 3005endif::VK_KHR_acceleration_structure[] 3006endif::VK_EXT_robustness2[] 3007 3008ifdef::VK_VALVE_mutable_descriptor_type[] 3009If the destination descriptor is a mutable descriptor, the active descriptor 3010type for the destination descriptor becomes pname:descriptorType. 3011endif::VK_VALVE_mutable_descriptor_type[] 3012 3013[[descriptorsets-updates-consecutive, consecutive binding updates]] 3014If the pname:dstBinding has fewer than pname:descriptorCount array elements 3015remaining starting from pname:dstArrayElement, then the remainder will be 3016used to update the subsequent binding - [eq]#pname:dstBinding+1# starting at 3017array element zero. 3018If a binding has a pname:descriptorCount of zero, it is skipped. 3019This behavior applies recursively, with the update affecting consecutive 3020bindings as needed to update all pname:descriptorCount descriptors. 3021Consecutive bindings must: have identical elink:VkDescriptorType, 3022tlink:VkShaderStageFlags, 3023ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3024elink:VkDescriptorBindingFlagBits, 3025endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3026and immutable samplers references. 3027 3028ifdef::VK_EXT_inline_uniform_block[] 3029[NOTE] 3030.Note 3031==== 3032The same behavior applies to bindings with a descriptor type of 3033ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT where 3034pname:descriptorCount specifies the number of bytes to update while 3035pname:dstArrayElement specifies the starting byte offset, thus in this case 3036if the pname:dstBinding has a smaller byte size than the sum of 3037pname:dstArrayElement and pname:descriptorCount, then the remainder will be 3038used to update the subsequent binding - [eq]#pname:dstBinding+1# starting at 3039offset zero. 3040This falls out as a special case of the above rule. 3041==== 3042endif::VK_EXT_inline_uniform_block[] 3043 3044.Valid Usage 3045**** 3046 * [[VUID-VkWriteDescriptorSet-dstBinding-00315]] 3047 pname:dstBinding must: be less than or equal to the maximum value of 3048 pname:binding of all slink:VkDescriptorSetLayoutBinding structures 3049 specified when pname:dstSet's descriptor set layout was created 3050 * [[VUID-VkWriteDescriptorSet-dstBinding-00316]] 3051 pname:dstBinding must: be a binding with a non-zero 3052 pname:descriptorCount 3053 * [[VUID-VkWriteDescriptorSet-descriptorCount-00317]] 3054 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 3055 structure, except those with a pname:descriptorCount of zero, must: have 3056 identical pname:descriptorType and pname:stageFlags 3057 * [[VUID-VkWriteDescriptorSet-descriptorCount-00318]] 3058 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 3059 structure, except those with a pname:descriptorCount of zero, must: all 3060 either use immutable samplers or must: all not use immutable samplers 3061 * [[VUID-VkWriteDescriptorSet-descriptorType-00319]] 3062 pname:descriptorType must: match the type of pname:dstBinding within 3063 pname:dstSet 3064 * [[VUID-VkWriteDescriptorSet-dstSet-00320]] 3065 pname:dstSet must: be a valid slink:VkDescriptorSet handle 3066 * [[VUID-VkWriteDescriptorSet-dstArrayElement-00321]] 3067 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 3068 than or equal to the number of array elements in the descriptor set 3069 binding specified by pname:dstBinding, and all applicable consecutive 3070 bindings, as described by <<descriptorsets-updates-consecutive>> 3071ifdef::VK_EXT_inline_uniform_block[] 3072 * [[VUID-VkWriteDescriptorSet-descriptorType-02219]] 3073 If pname:descriptorType is 3074 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:dstArrayElement 3075 must: be an integer multiple of `4` 3076 * [[VUID-VkWriteDescriptorSet-descriptorType-02220]] 3077 If pname:descriptorType is 3078 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:descriptorCount 3079 must: be an integer multiple of `4` 3080endif::VK_EXT_inline_uniform_block[] 3081 * [[VUID-VkWriteDescriptorSet-descriptorType-00322]] 3082 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER, 3083 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3084 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3085 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3086 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, pname:pImageInfo must: be a 3087 valid pointer to an array of pname:descriptorCount valid 3088 sname:VkDescriptorImageInfo structures 3089 * [[VUID-VkWriteDescriptorSet-descriptorType-02994]] 3090 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 3091 or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 3092 pname:pTexelBufferView must: be either a valid sname:VkBufferView handle 3093 or dlink:VK_NULL_HANDLE 3094 * [[VUID-VkWriteDescriptorSet-descriptorType-02995]] 3095 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 3096 or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER and the 3097 <<features-nullDescriptor,nullDescriptor>> feature is not enabled, each 3098 element of pname:pTexelBufferView must: not be dlink:VK_NULL_HANDLE 3099 * [[VUID-VkWriteDescriptorSet-descriptorType-00324]] 3100 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3101 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3102 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3103 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, pname:pBufferInfo must: 3104 be a valid pointer to an array of pname:descriptorCount valid 3105 sname:VkDescriptorBufferInfo structures 3106 * [[VUID-VkWriteDescriptorSet-descriptorType-00325]] 3107 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 3108 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 3109 not allocated with a layout that included immutable samplers for 3110 pname:dstBinding with pname:descriptorType, the pname:sampler member of 3111 each element of pname:pImageInfo must: be a valid sname:VkSampler object 3112 * [[VUID-VkWriteDescriptorSet-descriptorType-02996]] 3113 If pname:descriptorType is 3114 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3115 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3116 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3117 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of 3118 each element of pname:pImageInfo must: be either a valid 3119 sname:VkImageView handle or dlink:VK_NULL_HANDLE 3120 * [[VUID-VkWriteDescriptorSet-descriptorType-02997]] 3121 If pname:descriptorType is 3122 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3123 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3124 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3125 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and the 3126 <<features-nullDescriptor,nullDescriptor>> feature is not enabled, the 3127 pname:imageView member of each element of pname:pImageInfo must: not be 3128 dlink:VK_NULL_HANDLE 3129ifdef::VK_EXT_inline_uniform_block[] 3130 * [[VUID-VkWriteDescriptorSet-descriptorType-02221]] 3131 If pname:descriptorType is 3132 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, the pname:pNext chain 3133 must: include a slink:VkWriteDescriptorSetInlineUniformBlockEXT 3134 structure whose pname:dataSize member equals pname:descriptorCount 3135endif::VK_EXT_inline_uniform_block[] 3136ifdef::VK_KHR_acceleration_structure[] 3137 * [[VUID-VkWriteDescriptorSet-descriptorType-02382]] 3138 If pname:descriptorType is 3139 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, the pname:pNext 3140 chain must: include a slink:VkWriteDescriptorSetAccelerationStructureKHR 3141 structure whose pname:accelerationStructureCount member equals 3142 pname:descriptorCount 3143endif::VK_KHR_acceleration_structure[] 3144ifdef::VK_NV_ray_tracing[] 3145 * [[VUID-VkWriteDescriptorSet-descriptorType-03817]] 3146 If pname:descriptorType is 3147 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, the pname:pNext 3148 chain must: include a slink:VkWriteDescriptorSetAccelerationStructureNV 3149 structure whose pname:accelerationStructureCount member equals 3150 pname:descriptorCount 3151endif::VK_NV_ray_tracing[] 3152ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 3153 * [[VUID-VkWriteDescriptorSet-descriptorType-01946]] 3154 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, then 3155 the pname:imageView member of each pname:pImageInfo element must: have 3156 been created without a sname:VkSamplerYcbcrConversionInfo structure in 3157 its pname:pNext chain 3158 * [[VUID-VkWriteDescriptorSet-descriptorType-02738]] 3159 If pname:descriptorType is 3160 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and if any element of 3161 pname:pImageInfo has a pname:imageView member that was created with a 3162 sname:VkSamplerYcbcrConversionInfo structure in its pname:pNext chain, 3163 then pname:dstSet must: have been allocated with a layout that included 3164 immutable samplers for pname:dstBinding, and the corresponding immutable 3165 sampler must: have been created with an _identically defined_ 3166 sname:VkSamplerYcbcrConversionInfo object 3167 * [[VUID-VkWriteDescriptorSet-descriptorType-01948]] 3168 If pname:descriptorType is 3169 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 3170 allocated with a layout that included immutable samplers for 3171 pname:dstBinding, then the pname:imageView member of each element of 3172 pname:pImageInfo which corresponds to an immutable sampler that enables 3173 <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> must: have been 3174 created with a sname:VkSamplerYcbcrConversionInfo structure in its 3175 pname:pNext chain with an _identically defined_ 3176 sname:VkSamplerYcbcrConversionInfo to the corresponding immutable 3177 sampler 3178endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 3179 * [[VUID-VkWriteDescriptorSet-descriptorType-00327]] 3180 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3181 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:offset member 3182 of each element of pname:pBufferInfo must: be a multiple of 3183 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 3184 * [[VUID-VkWriteDescriptorSet-descriptorType-00328]] 3185 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3186 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:offset member 3187 of each element of pname:pBufferInfo must: be a multiple of 3188 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 3189 * [[VUID-VkWriteDescriptorSet-descriptorType-00329]] 3190 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3191 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, 3192 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, or 3193 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, and the pname:buffer 3194 member of any element of pname:pBufferInfo is the handle of a non-sparse 3195 buffer, then that buffer must: be bound completely and contiguously to a 3196 single sname:VkDeviceMemory object 3197 * [[VUID-VkWriteDescriptorSet-descriptorType-00330]] 3198 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3199 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:buffer member 3200 of each element of pname:pBufferInfo must: have been created with 3201 ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT set 3202 * [[VUID-VkWriteDescriptorSet-descriptorType-00331]] 3203 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3204 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:buffer member 3205 of each element of pname:pBufferInfo must: have been created with 3206 ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT set 3207 * [[VUID-VkWriteDescriptorSet-descriptorType-00332]] 3208 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3209 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:range member 3210 of each element of pname:pBufferInfo, or the effective range if 3211 pname:range is ename:VK_WHOLE_SIZE, must: be less than or equal to 3212 sname:VkPhysicalDeviceLimits::pname:maxUniformBufferRange 3213 * [[VUID-VkWriteDescriptorSet-descriptorType-00333]] 3214 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3215 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:range member 3216 of each element of pname:pBufferInfo, or the effective range if 3217 pname:range is ename:VK_WHOLE_SIZE, must: be less than or equal to 3218 sname:VkPhysicalDeviceLimits::pname:maxStorageBufferRange 3219 * [[VUID-VkWriteDescriptorSet-descriptorType-00334]] 3220 If pname:descriptorType is 3221 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, the sname:VkBuffer that 3222 each element of pname:pTexelBufferView was created from must: have been 3223 created with ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT set 3224 * [[VUID-VkWriteDescriptorSet-descriptorType-00335]] 3225 If pname:descriptorType is 3226 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the sname:VkBuffer that 3227 each element of pname:pTexelBufferView was created from must: have been 3228 created with ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT set 3229 * [[VUID-VkWriteDescriptorSet-descriptorType-00336]] 3230 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE or 3231 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of 3232 each element of pname:pImageInfo must: have been created with the 3233 identity swizzle 3234 * [[VUID-VkWriteDescriptorSet-descriptorType-00337]] 3235 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 3236 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageView 3237 member of each element of pname:pImageInfo must: have been created with 3238 ename:VK_IMAGE_USAGE_SAMPLED_BIT set 3239 * [[VUID-VkWriteDescriptorSet-descriptorType-04149]] 3240 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE the 3241 pname:imageLayout member of each element of pname:pImageInfo must: be a 3242 member of the list given in <<descriptorsets-sampledimage, Sampled 3243 Image>> 3244 * [[VUID-VkWriteDescriptorSet-descriptorType-04150]] 3245 If pname:descriptorType is 3246 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER the pname:imageLayout 3247 member of each element of pname:pImageInfo must: be a member of the list 3248 given in <<descriptorsets-combinedimagesampler, Combined Image Sampler>> 3249 * [[VUID-VkWriteDescriptorSet-descriptorType-04151]] 3250 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT the 3251 pname:imageLayout member of each element of pname:pImageInfo must: be a 3252 member of the list given in <<descriptorsets-inputattachment, Input 3253 Attachment>> 3254 * [[VUID-VkWriteDescriptorSet-descriptorType-04152]] 3255 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE the 3256 pname:imageLayout member of each element of pname:pImageInfo must: be a 3257 member of the list given in <<descriptorsets-storageimage, Storage 3258 Image>> 3259 * [[VUID-VkWriteDescriptorSet-descriptorType-00338]] 3260 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3261 the pname:imageView member of each element of pname:pImageInfo must: 3262 have been created with ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set 3263 * [[VUID-VkWriteDescriptorSet-descriptorType-00339]] 3264 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the 3265 pname:imageView member of each element of pname:pImageInfo must: have 3266 been created with ename:VK_IMAGE_USAGE_STORAGE_BIT set 3267 * [[VUID-VkWriteDescriptorSet-descriptorType-02752]] 3268 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER, then 3269 pname:dstSet must: not have been allocated with a layout that included 3270 immutable samplers for pname:dstBinding 3271ifdef::VK_VALVE_mutable_descriptor_type[] 3272 * [[VUID-VkWriteDescriptorSet-dstSet-04611]] 3273 If the sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3274 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new 3275 active descriptor type pname:descriptorType must: exist in the 3276 corresponding pname:pMutableDescriptorTypeLists list for 3277 pname:dstBinding 3278endif::VK_VALVE_mutable_descriptor_type[] 3279**** 3280 3281include::{generated}/validity/structs/VkWriteDescriptorSet.txt[] 3282-- 3283 3284[open,refpage='VkDescriptorType',desc='Specifies the type of a descriptor in a descriptor set',type='enums'] 3285-- 3286The type of descriptors in a descriptor set is specified by 3287slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the 3288values: 3289 3290include::{generated}/api/enums/VkDescriptorType.txt[] 3291 3292 * ename:VK_DESCRIPTOR_TYPE_SAMPLER specifies a <<descriptorsets-sampler, 3293 sampler descriptor>>. 3294 * ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER specifies a 3295 <<descriptorsets-combinedimagesampler, combined image sampler 3296 descriptor>>. 3297 * ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE specifies a 3298 <<descriptorsets-sampledimage, sampled image descriptor>>. 3299 * ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE specifies a 3300 <<descriptorsets-storageimage, storage image descriptor>>. 3301 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER specifies a 3302 <<descriptorsets-uniformtexelbuffer, uniform texel buffer descriptor>>. 3303 * ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER specifies a 3304 <<descriptorsets-storagetexelbuffer, storage texel buffer descriptor>>. 3305 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER specifies a 3306 <<descriptorsets-uniformbuffer, uniform buffer descriptor>>. 3307 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER specifies a 3308 <<descriptorsets-storagebuffer, storage buffer descriptor>>. 3309 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC specifies a 3310 <<descriptorsets-uniformbufferdynamic, dynamic uniform buffer 3311 descriptor>>. 3312 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC specifies a 3313 <<descriptorsets-storagebufferdynamic, dynamic storage buffer 3314 descriptor>>. 3315 * ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT specifies an 3316 <<descriptorsets-inputattachment, input attachment descriptor>>. 3317ifdef::VK_EXT_inline_uniform_block[] 3318 * ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT specifies an 3319 <<descriptorsets-inlineuniformblock, inline uniform block>>. 3320endif::VK_EXT_inline_uniform_block[] 3321ifdef::VK_VALVE_mutable_descriptor_type[] 3322 * ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE specifies a 3323 <<descriptorsets-mutable, descriptor of mutable type>>. 3324endif::VK_VALVE_mutable_descriptor_type[] 3325 3326When a descriptor set is updated via elements of slink:VkWriteDescriptorSet, 3327members of pname:pImageInfo, pname:pBufferInfo and pname:pTexelBufferView 3328are only accessed by the implementation when they correspond to descriptor 3329type being defined - otherwise they are ignored. 3330The members accessed are as follows for each descriptor type: 3331 3332 * For ename:VK_DESCRIPTOR_TYPE_SAMPLER, only the pname:sampler member of 3333 each element of slink:VkWriteDescriptorSet::pname:pImageInfo is 3334 accessed. 3335 * For ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3336 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3337 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only the pname:imageView and 3338 pname:imageLayout members of each element of 3339 slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3340 * For ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each 3341 element of slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3342 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3343 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3344 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3345 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each 3346 element of slink:VkWriteDescriptorSet::pname:pBufferInfo are accessed. 3347 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 3348 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 3349 slink:VkWriteDescriptorSet::pname:pTexelBufferView is accessed. 3350 3351ifdef::VK_EXT_inline_uniform_block[] 3352When updating descriptors with a pname:descriptorType of 3353ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, none of the 3354pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3355accessed, instead the source data of the descriptor update operation is 3356taken from the slink:VkWriteDescriptorSetInlineUniformBlockEXT structure in 3357the pname:pNext chain of sname:VkWriteDescriptorSet. 3358endif::VK_EXT_inline_uniform_block[] 3359ifdef::VK_KHR_acceleration_structure[] 3360When updating descriptors with a pname:descriptorType of 3361ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, none of the 3362pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3363accessed, instead the source data of the descriptor update operation is 3364taken from the slink:VkWriteDescriptorSetAccelerationStructureKHR structure 3365in the pname:pNext chain of sname:VkWriteDescriptorSet. 3366endif::VK_KHR_acceleration_structure[] 3367ifdef::VK_NV_ray_tracing[] 3368When updating descriptors with a pname:descriptorType of 3369ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, none of the 3370pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3371accessed, instead the source data of the descriptor update operation is 3372taken from the slink:VkWriteDescriptorSetAccelerationStructureNV structure 3373in the pname:pNext chain of sname:VkWriteDescriptorSet. 3374endif::VK_NV_ray_tracing[] 3375-- 3376 3377[open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer information',type='structs'] 3378-- 3379The sname:VkDescriptorBufferInfo structure is defined as: 3380 3381include::{generated}/api/structs/VkDescriptorBufferInfo.txt[] 3382 3383 * pname:buffer is 3384ifdef::VK_EXT_robustness2[] 3385dlink:VK_NULL_HANDLE or 3386endif::VK_EXT_robustness2[] 3387the buffer resource. 3388 * pname:offset is the offset in bytes from the start of pname:buffer. 3389 Access to buffer memory via this descriptor uses addressing that is 3390 relative to this starting offset. 3391 * pname:range is the size in bytes that is used for this descriptor 3392 update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the 3393 end of the buffer. 3394 3395[NOTE] 3396.Note 3397==== 3398When setting pname:range to ename:VK_WHOLE_SIZE, the effective range must: 3399not be larger than the maximum range for the descriptor type 3400(<<limits-maxUniformBufferRange, pname:maxUniformBufferRange>> or 3401<<limits-maxStorageBufferRange, pname:maxStorageBufferRange>>). 3402This means that ename:VK_WHOLE_SIZE is not typically useful in the common 3403case where uniform buffer descriptors are suballocated from a buffer that is 3404much larger than pname:maxUniformBufferRange. 3405==== 3406 3407For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and 3408ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, 3409pname:offset is the base offset from which the dynamic offset is applied and 3410pname:range is the static size used for all dynamic offsets. 3411 3412.Valid Usage 3413**** 3414 * [[VUID-VkDescriptorBufferInfo-offset-00340]] 3415 pname:offset must: be less than the size of pname:buffer 3416 * [[VUID-VkDescriptorBufferInfo-range-00341]] 3417 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3418 greater than `0` 3419 * [[VUID-VkDescriptorBufferInfo-range-00342]] 3420 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3421 less than or equal to the size of pname:buffer minus pname:offset 3422 * [[VUID-VkDescriptorBufferInfo-buffer-02998]] 3423 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3424 enabled, pname:buffer must: not be dlink:VK_NULL_HANDLE 3425ifdef::VK_EXT_robustness2[] 3426 * [[VUID-VkDescriptorBufferInfo-buffer-02999]] 3427 If pname:buffer is dlink:VK_NULL_HANDLE, pname:offset must: be zero and 3428 pname:range must: be ename:VK_WHOLE_SIZE 3429endif::VK_EXT_robustness2[] 3430**** 3431 3432include::{generated}/validity/structs/VkDescriptorBufferInfo.txt[] 3433-- 3434 3435[open,refpage='VkDescriptorImageInfo',desc='Structure specifying descriptor image information',type='structs'] 3436-- 3437The sname:VkDescriptorImageInfo structure is defined as: 3438 3439include::{generated}/api/structs/VkDescriptorImageInfo.txt[] 3440 3441 * pname:sampler is a sampler handle, and is used in descriptor updates for 3442 types ename:VK_DESCRIPTOR_TYPE_SAMPLER and 3443 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER if the binding being 3444 updated does not use immutable samplers. 3445 * pname:imageView is 3446ifdef::VK_EXT_robustness2[] 3447 dlink:VK_NULL_HANDLE or 3448endif::VK_EXT_robustness2[] 3449 an image view handle, and is used in descriptor updates for types 3450 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3451 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3452 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3453 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3454 * pname:imageLayout is the layout that the image subresources accessible 3455 from pname:imageView will be in at the time this descriptor is accessed. 3456 pname:imageLayout is used in descriptor updates for types 3457 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3458 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3459 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3460 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3461 3462Members of sname:VkDescriptorImageInfo that are not used in an update (as 3463described above) are ignored. 3464 3465.Valid Usage 3466**** 3467ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3468 * [[VUID-VkDescriptorImageInfo-imageView-00343]] 3469 pname:imageView must: not be 2D or 2D array image view created from a 3D 3470 image 3471endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3472 * [[VUID-VkDescriptorImageInfo-imageView-01976]] 3473 If pname:imageView is created from a depth/stencil image, the 3474 pname:aspectMask used to create the pname:imageView must: include either 3475 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT but 3476 not both 3477 * [[VUID-VkDescriptorImageInfo-imageLayout-00344]] 3478 pname:imageLayout must: match the actual elink:VkImageLayout of each 3479 subresource accessible from pname:imageView at the time this descriptor 3480 is accessed as defined by the <<resources-image-layouts-matching-rule, 3481 image layout matching rules>> 3482ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3483 * [[VUID-VkDescriptorImageInfo-sampler-01564]] 3484 If pname:sampler is used and the elink:VkFormat of the image is a 3485 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, the 3486 image must: have been created with 3487 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the pname:aspectMask of 3488 the pname:imageView must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 3489 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or (for three-plane formats only) 3490 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 3491endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3492ifdef::VK_KHR_portability_subset[] 3493 * [[VUID-VkDescriptorImageInfo-mutableComparisonSamplers-04450]] 3494 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 3495 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:mutableComparisonSamplers 3496 is ename:VK_FALSE, then pname:sampler must: have been created with 3497 slink:VkSamplerCreateInfo::pname:compareEnable set to ename:VK_FALSE 3498endif::VK_KHR_portability_subset[] 3499**** 3500 3501 3502include::{generated}/validity/structs/VkDescriptorImageInfo.txt[] 3503-- 3504 3505ifdef::VK_EXT_inline_uniform_block[] 3506[open,refpage='VkWriteDescriptorSetInlineUniformBlockEXT',desc='Structure specifying inline uniform block data',type='structs'] 3507-- 3508If the pname:descriptorType member of slink:VkWriteDescriptorSet is 3509ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then the data to write to 3510the descriptor set is specified through a 3511sname:VkWriteDescriptorSetInlineUniformBlockEXT structure included in the 3512pname:pNext chain of sname:VkWriteDescriptorSet. 3513 3514The sname:VkWriteDescriptorSetInlineUniformBlockEXT structure is defined as: 3515 3516include::{generated}/api/structs/VkWriteDescriptorSetInlineUniformBlockEXT.txt[] 3517 3518 * pname:sType is the type of this structure. 3519 * pname:pNext is `NULL` or a pointer to a structure extending this 3520 structure. 3521 * pname:dataSize is the number of bytes of inline uniform block data 3522 pointed to by pname:pData. 3523 * pname:pData is a pointer to pname:dataSize number of bytes of data to 3524 write to the inline uniform block. 3525 3526.Valid Usage 3527**** 3528 * [[VUID-VkWriteDescriptorSetInlineUniformBlockEXT-dataSize-02222]] 3529 pname:dataSize must: be an integer multiple of `4` 3530**** 3531 3532include::{generated}/validity/structs/VkWriteDescriptorSetInlineUniformBlockEXT.txt[] 3533-- 3534endif::VK_EXT_inline_uniform_block[] 3535 3536ifdef::VK_KHR_acceleration_structure[] 3537[open,refpage='VkWriteDescriptorSetAccelerationStructureKHR',desc='Structure specifying acceleration structure descriptor information',type='structs'] 3538-- 3539:refpage: VkWriteDescriptorSetAccelerationStructureKHR 3540 3541The sname:VkWriteDescriptorSetAccelerationStructureKHR structure is defined 3542as: 3543 3544include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureKHR.txt[] 3545 3546 * pname:sType is the type of this structure. 3547 * pname:pNext is `NULL` or a pointer to a structure extending this 3548 structure. 3549 * pname:accelerationStructureCount is the number of elements in 3550 pname:pAccelerationStructures. 3551 * pname:pAccelerationStructures is a pointer to an array of 3552 slink:VkAccelerationStructureKHR structures specifying the acceleration 3553 structures to update. 3554 3555.Valid Usage 3556**** 3557 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-accelerationStructureCount-02236]] 3558 pname:accelerationStructureCount must: be equal to pname:descriptorCount 3559 in the extended structure 3560 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03579]] 3561 Each acceleration structure in pname:pAccelerationStructures must: have 3562 been created with a pname:type of 3563 ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or 3564 ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 3565 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03580]] 3566 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3567 enabled, each element of pname:pAccelerationStructures must: not be 3568 dlink:VK_NULL_HANDLE 3569**** 3570 3571include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureKHR.txt[] 3572-- 3573endif::VK_KHR_acceleration_structure[] 3574 3575ifdef::VK_NV_ray_tracing[] 3576[open,refpage='VkWriteDescriptorSetAccelerationStructureNV',desc='Structure specifying acceleration structure descriptor information',type='structs'] 3577-- 3578:refpage: VkWriteDescriptorSetAccelerationStructureNV 3579 3580The sname:VkWriteDescriptorSetAccelerationStructureNV structure is defined 3581as: 3582 3583include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] 3584 3585 * pname:sType is the type of this structure. 3586 * pname:pNext is `NULL` or a pointer to a structure extending this 3587 structure. 3588 * pname:accelerationStructureCount is the number of elements in 3589 pname:pAccelerationStructures. 3590 * pname:pAccelerationStructures is a pointer to an array of 3591 slink:VkAccelerationStructureNV structures specifying the acceleration 3592 structures to update. 3593 3594.Valid Usage 3595**** 3596 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-accelerationStructureCount-03747]] 3597 pname:accelerationStructureCount must: be equal to pname:descriptorCount 3598 in the extended structure 3599 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03748]] 3600 Each acceleration structure in pname:pAccelerationStructures must: have 3601 been created with ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR 3602 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03749]] 3603 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3604 enabled, each member of pname:pAccelerationStructures must: not be 3605 dlink:VK_NULL_HANDLE 3606**** 3607 3608include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] 3609-- 3610endif::VK_NV_ray_tracing[] 3611 3612[open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] 3613-- 3614The sname:VkCopyDescriptorSet structure is defined as: 3615 3616include::{generated}/api/structs/VkCopyDescriptorSet.txt[] 3617 3618 * pname:sType is the type of this structure. 3619 * pname:pNext is `NULL` or a pointer to a structure extending this 3620 structure. 3621 * pname:srcSet, pname:srcBinding, and pname:srcArrayElement are the source 3622 set, binding, and array element, respectively. 3623ifdef::VK_EXT_inline_uniform_block[] 3624 If the descriptor binding identified by pname:srcSet and 3625 pname:srcBinding has a descriptor type of 3626 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3627 pname:srcArrayElement specifies the starting byte offset within the 3628 binding to copy from. 3629endif::VK_EXT_inline_uniform_block[] 3630 * pname:dstSet, pname:dstBinding, and pname:dstArrayElement are the 3631 destination set, binding, and array element, respectively. 3632ifdef::VK_EXT_inline_uniform_block[] 3633 If the descriptor binding identified by pname:dstSet and 3634 pname:dstBinding has a descriptor type of 3635 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3636 pname:dstArrayElement specifies the starting byte offset within the 3637 binding to copy to. 3638endif::VK_EXT_inline_uniform_block[] 3639 * pname:descriptorCount is the number of descriptors to copy from the 3640 source to destination. 3641 If pname:descriptorCount is greater than the number of remaining array 3642 elements in the source or destination binding, those affect consecutive 3643 bindings in a manner similar to slink:VkWriteDescriptorSet above. 3644ifdef::VK_EXT_inline_uniform_block[] 3645 If the descriptor binding identified by pname:srcSet and 3646 pname:srcBinding has a descriptor type of 3647 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3648 pname:descriptorCount specifies the number of bytes to copy and the 3649 remaining array elements in the source or destination binding refer to 3650 the remaining number of bytes in those. 3651endif::VK_EXT_inline_uniform_block[] 3652 3653ifdef::VK_VALVE_mutable_descriptor_type[] 3654If the sname:VkDescriptorSetLayoutBinding for pname:dstBinding is 3655ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE and pname:srcBinding is not 3656ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new active descriptor type 3657becomes the descriptor type of pname:srcBinding. 3658If both sname:VkDescriptorSetLayoutBinding for pname:srcBinding and 3659pname:dstBinding are ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the active 3660descriptor type in each source descriptor is copied into the corresponding 3661destination descriptor. 3662The active descriptor type can: be different for each source descriptor. 3663 3664[NOTE] 3665.Note 3666==== 3667The intention is that copies to and from mutable descriptors is a simple 3668memcpy. 3669Copies between non-mutable and mutable descriptors are expected to require 3670one memcpy per descriptor to handle the difference in size, but this use 3671case with more than one pname:descriptorCount is considered rare. 3672==== 3673endif::VK_VALVE_mutable_descriptor_type[] 3674 3675.Valid Usage 3676**** 3677 * [[VUID-VkCopyDescriptorSet-srcBinding-00345]] 3678 pname:srcBinding must: be a valid binding within pname:srcSet 3679 * [[VUID-VkCopyDescriptorSet-srcArrayElement-00346]] 3680 The sum of pname:srcArrayElement and pname:descriptorCount must: be less 3681 than or equal to the number of array elements in the descriptor set 3682 binding specified by pname:srcBinding, and all applicable consecutive 3683 bindings, as described by <<descriptorsets-updates-consecutive>> 3684 * [[VUID-VkCopyDescriptorSet-dstBinding-00347]] 3685 pname:dstBinding must: be a valid binding within pname:dstSet 3686 * [[VUID-VkCopyDescriptorSet-dstArrayElement-00348]] 3687 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 3688 than or equal to the number of array elements in the descriptor set 3689 binding specified by pname:dstBinding, and all applicable consecutive 3690 bindings, as described by <<descriptorsets-updates-consecutive>> 3691 * [[VUID-VkCopyDescriptorSet-dstBinding-02632]] 3692 The type of pname:dstBinding within pname:dstSet must: be equal to the 3693 type of pname:srcBinding within pname:srcSet 3694 * [[VUID-VkCopyDescriptorSet-srcSet-00349]] 3695 If pname:srcSet is equal to pname:dstSet, then the source and 3696 destination ranges of descriptors must: not overlap, where the ranges 3697 may: include array elements from consecutive bindings as described by 3698 <<descriptorsets-updates-consecutive>> 3699ifdef::VK_EXT_inline_uniform_block[] 3700 * [[VUID-VkCopyDescriptorSet-srcBinding-02223]] 3701 If the descriptor type of the descriptor set binding specified by 3702 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, 3703 pname:srcArrayElement must: be an integer multiple of `4` 3704 * [[VUID-VkCopyDescriptorSet-dstBinding-02224]] 3705 If the descriptor type of the descriptor set binding specified by 3706 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, 3707 pname:dstArrayElement must: be an integer multiple of `4` 3708 * [[VUID-VkCopyDescriptorSet-srcBinding-02225]] 3709 If the descriptor type of the descriptor set binding specified by either 3710 pname:srcBinding or pname:dstBinding is 3711 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:descriptorCount 3712 must: be an integer multiple of `4` 3713endif::VK_EXT_inline_uniform_block[] 3714ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3715 * [[VUID-VkCopyDescriptorSet-srcSet-01918]] 3716 If pname:srcSet's layout was created with the 3717 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3718 set, then pname:dstSet's layout must: also have been created with the 3719 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3720 set 3721ifdef::VK_VALVE_mutable_descriptor_type[] 3722 * [[VUID-VkCopyDescriptorSet-srcSet-04885]] 3723 If pname:srcSet's layout was created with neither 3724 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT nor 3725 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE flags 3726 set, then pname:dstSet's layout must: have been created without the 3727 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3728 set 3729endif::VK_VALVE_mutable_descriptor_type[] 3730ifndef::VK_VALVE_mutable_descriptor_type[] 3731 * [[VUID-VkCopyDescriptorSet-srcSet-04886]] 3732 If pname:srcSet's layout was created without the 3733 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3734 set, then pname:dstSet's layout must: also have been created without the 3735 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3736 set 3737endif::VK_VALVE_mutable_descriptor_type[] 3738 * [[VUID-VkCopyDescriptorSet-srcSet-01920]] 3739 If the descriptor pool from which pname:srcSet was allocated was created 3740 with the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set, 3741 then the descriptor pool from which pname:dstSet was allocated must: 3742 also have been created with the 3743 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3744ifdef::VK_VALVE_mutable_descriptor_type[] 3745 * [[VUID-VkCopyDescriptorSet-srcSet-04887]] 3746 If the descriptor pool from which pname:srcSet was allocated was created 3747 with neither ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT nor 3748 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE flags set, then the 3749 descriptor pool from which pname:dstSet was allocated must: have been 3750 created without the 3751 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3752endif::VK_VALVE_mutable_descriptor_type[] 3753ifndef::VK_VALVE_mutable_descriptor_type[] 3754 * [[VUID-VkCopyDescriptorSet-srcSet-04888]] 3755 If the descriptor pool from which pname:srcSet was allocated was created 3756 without the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag 3757 set, then the descriptor pool from which pname:dstSet was allocated 3758 must: also have been created without the 3759 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3760endif::VK_VALVE_mutable_descriptor_type[] 3761endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3762 * [[VUID-VkCopyDescriptorSet-dstBinding-02753]] 3763 If the descriptor type of the descriptor set binding specified by 3764 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_SAMPLER, then pname:dstSet 3765 must: not have been allocated with a layout that included immutable 3766 samplers for pname:dstBinding 3767ifdef::VK_VALVE_mutable_descriptor_type[] 3768 * [[VUID-VkCopyDescriptorSet-dstSet-04612]] 3769 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3770 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new 3771 active descriptor type must: exist in the corresponding 3772 pname:pMutableDescriptorTypeLists list for pname:dstBinding if the new 3773 active descriptor type is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 3774 * [[VUID-VkCopyDescriptorSet-srcSet-04613]] 3775 If sname:VkDescriptorSetLayoutBinding for pname:srcSet at 3776 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE and the 3777 sname:VkDescriptorSetLayoutBinding for pname:dstSet at pname:dstBinding 3778 is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the active descriptor 3779 type for the source descriptor must: match the descriptor type of 3780 pname:dstBinding 3781 * [[VUID-VkCopyDescriptorSet-dstSet-04614]] 3782 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3783 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, and the new 3784 active descriptor type is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the 3785 pname:pMutableDescriptorTypeLists for pname:srcBinding and 3786 pname:dstBinding must: match exactly 3787endif::VK_VALVE_mutable_descriptor_type[] 3788**** 3789 3790include::{generated}/validity/structs/VkCopyDescriptorSet.txt[] 3791-- 3792 3793 3794ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 3795[[descriptorsets-updates-with-template]] 3796=== Descriptor Update Templates 3797 3798[open,refpage='VkDescriptorUpdateTemplate',desc='Opaque handle to a descriptor update template',type='handles'] 3799-- 3800A descriptor update template specifies a mapping from descriptor update 3801information in host memory to descriptors in a descriptor set. 3802It is designed to avoid passing redundant information to the driver when 3803frequently updating the same set of descriptors in descriptor sets. 3804 3805Descriptor update template objects are represented by 3806sname:VkDescriptorUpdateTemplate handles: 3807 3808include::{generated}/api/handles/VkDescriptorUpdateTemplate.txt[] 3809 3810ifdef::VK_KHR_descriptor_update_template[] 3811or the equivalent 3812 3813include::{generated}/api/handles/VkDescriptorUpdateTemplateKHR.txt[] 3814endif::VK_KHR_descriptor_update_template[] 3815-- 3816 3817 3818=== Descriptor Set Updates with Templates 3819 3820[open,refpage='vkCreateDescriptorUpdateTemplate',desc='Create a new descriptor update template',type='protos'] 3821-- 3822Updating a large sname:VkDescriptorSet array can: be an expensive operation 3823since an application must: specify one slink:VkWriteDescriptorSet structure 3824for each descriptor or descriptor array to update, each of which 3825re-specifies the same state when updating the same descriptor in multiple 3826descriptor sets. 3827For cases when an application wishes to update the same set of descriptors 3828in multiple descriptor sets allocated using the same 3829sname:VkDescriptorSetLayout, flink:vkUpdateDescriptorSetWithTemplate can: be 3830used as a replacement for flink:vkUpdateDescriptorSets. 3831 3832sname:VkDescriptorUpdateTemplate allows implementations to convert a set of 3833descriptor update operations on a single descriptor set to an internal 3834format that, in conjunction with flink:vkUpdateDescriptorSetWithTemplate 3835ifdef::VK_KHR_push_descriptor[] 3836or flink:vkCmdPushDescriptorSetWithTemplateKHR 3837endif::VK_KHR_push_descriptor[] 3838, can: be more efficient compared to calling flink:vkUpdateDescriptorSets 3839ifdef::VK_KHR_push_descriptor[] 3840or flink:vkCmdPushDescriptorSetKHR 3841endif::VK_KHR_push_descriptor[] 3842. 3843The descriptors themselves are not specified in the 3844sname:VkDescriptorUpdateTemplate, rather, offsets into an application 3845provided pointer to host memory are specified, which are combined with a 3846pointer passed to flink:vkUpdateDescriptorSetWithTemplate 3847ifdef::VK_KHR_push_descriptor[] 3848or flink:vkCmdPushDescriptorSetWithTemplateKHR 3849endif::VK_KHR_push_descriptor[] 3850. 3851This allows large batches of updates to be executed without having to 3852convert application data structures into a strictly-defined Vulkan data 3853structure. 3854 3855To create a descriptor update template, call: 3856 3857ifdef::VK_VERSION_1_1[] 3858include::{generated}/api/protos/vkCreateDescriptorUpdateTemplate.txt[] 3859endif::VK_VERSION_1_1[] 3860 3861ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 3862 3863ifdef::VK_KHR_descriptor_update_template[] 3864include::{generated}/api/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] 3865endif::VK_KHR_descriptor_update_template[] 3866 3867 * pname:device is the logical device that creates the descriptor update 3868 template. 3869 * pname:pCreateInfo is a pointer to a 3870 slink:VkDescriptorUpdateTemplateCreateInfo structure specifying the set 3871 of descriptors to update with a single call to 3872ifdef::VK_KHR_push_descriptor[] 3873 flink:vkCmdPushDescriptorSetWithTemplateKHR or 3874endif::VK_KHR_push_descriptor[] 3875 flink:vkUpdateDescriptorSetWithTemplate. 3876 * pname:pAllocator controls host memory allocation as described in the 3877 <<memory-allocation, Memory Allocation>> chapter. 3878 * pname:pDescriptorUpdateTemplate is a pointer to a 3879 sname:VkDescriptorUpdateTemplate handle in which the resulting 3880 descriptor update template object is returned. 3881 3882include::{generated}/validity/protos/vkCreateDescriptorUpdateTemplate.txt[] 3883-- 3884 3885[open,refpage='VkDescriptorUpdateTemplateCreateInfo',desc='Structure specifying parameters of a newly created descriptor update template',type='structs'] 3886-- 3887The slink:VkDescriptorUpdateTemplateCreateInfo structure is defined as: 3888include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 3889 3890ifdef::VK_KHR_descriptor_update_template[] 3891or the equivalent 3892 3893include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfoKHR.txt[] 3894endif::VK_KHR_descriptor_update_template[] 3895 3896 * pname:sType is the type of this structure. 3897 * pname:pNext is `NULL` or a pointer to a structure extending this 3898 structure. 3899 * pname:flags is reserved for future use. 3900 * pname:descriptorUpdateEntryCount is the number of elements in the 3901 pname:pDescriptorUpdateEntries array. 3902 * pname:pDescriptorUpdateEntries is a pointer to an array of 3903 slink:VkDescriptorUpdateTemplateEntry structures describing the 3904 descriptors to be updated by the descriptor update template. 3905 * pname:templateType Specifies the type of the descriptor update template. 3906 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET it 3907 can: only be used to update descriptor sets with a fixed 3908 pname:descriptorSetLayout. 3909ifdef::VK_KHR_push_descriptor[] 3910 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3911 it can: only be used to push descriptor sets using the provided 3912 pname:pipelineBindPoint, pname:pipelineLayout, and pname:set number. 3913endif::VK_KHR_push_descriptor[] 3914 * pname:descriptorSetLayout is the descriptor set layout used to build the 3915 descriptor update template. 3916 All descriptor sets which are going to be updated through the newly 3917 created descriptor update template must: be created with a layout that 3918 matches (is the same as, or defined identically to) this layout. 3919 This parameter is ignored if pname:templateType is not 3920 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET. 3921ifdef::VK_KHR_push_descriptor[] 3922 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 3923 type of the pipeline that will use the descriptors. 3924 This parameter is ignored if pname:templateType is not 3925 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3926 * pname:pipelineLayout is a slink:VkPipelineLayout object used to program 3927 the bindings. 3928 This parameter is ignored if pname:templateType is not 3929 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3930 * pname:set is the set number of the descriptor set in the pipeline layout 3931 that will be updated. 3932 This parameter is ignored if pname:templateType is not 3933 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3934endif::VK_KHR_push_descriptor[] 3935ifndef::VK_KHR_push_descriptor[] 3936 * pname:pipelineBindPoint is reserved for future use and is ignored 3937 * pname:pipelineLayout is reserved for future use and is ignored 3938 * pname:set is reserved for future use and is ignored 3939endif::VK_KHR_push_descriptor[] 3940 3941.Valid Usage 3942**** 3943 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00350]] 3944 If pname:templateType is 3945 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 3946 pname:descriptorSetLayout must: be a valid sname:VkDescriptorSetLayout 3947 handle 3948ifdef::VK_KHR_push_descriptor[] 3949 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00351]] 3950 If pname:templateType is 3951 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 3952 pname:pipelineBindPoint must: be a valid elink:VkPipelineBindPoint value 3953 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00352]] 3954 If pname:templateType is 3955 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 3956 pname:pipelineLayout must: be a valid sname:VkPipelineLayout handle 3957 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00353]] 3958 If pname:templateType is 3959 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, pname:set 3960 must: be the unique set number in the pipeline layout that uses a 3961 descriptor set layout that was created with 3962 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 3963endif::VK_KHR_push_descriptor[] 3964ifdef::VK_VALVE_mutable_descriptor_type[] 3965 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-04615]] 3966 If pname:templateType is 3967 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 3968 pname:descriptorSetLayout must: not contain a binding with type 3969 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 3970endif::VK_VALVE_mutable_descriptor_type[] 3971**** 3972 3973 3974include::{generated}/validity/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 3975-- 3976 3977[open,refpage='VkDescriptorUpdateTemplateCreateFlags',desc='Reserved for future use',type='flags'] 3978-- 3979include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlags.txt[] 3980 3981ifdef::VK_KHR_descriptor_update_template[] 3982or the equivalent 3983 3984include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlagsKHR.txt[] 3985endif::VK_KHR_descriptor_update_template[] 3986 3987tname:VkDescriptorUpdateTemplateCreateFlags is a bitmask type for setting a 3988mask, but is currently reserved for future use. 3989-- 3990 3991[open,refpage='VkDescriptorUpdateTemplateType',desc='Indicates the valid usage of the descriptor update template',type='enums'] 3992-- 3993The descriptor update template type is determined by the 3994slink:VkDescriptorUpdateTemplateCreateInfo::pname:templateType property, 3995which takes the following values: 3996 3997include::{generated}/api/enums/VkDescriptorUpdateTemplateType.txt[] 3998 3999ifdef::VK_KHR_descriptor_update_template[] 4000or the equivalent 4001 4002include::{generated}/api/enums/VkDescriptorUpdateTemplateTypeKHR.txt[] 4003endif::VK_KHR_descriptor_update_template[] 4004 4005 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET specifies that 4006 the descriptor update template will be used for descriptor set updates 4007 only. 4008ifdef::VK_KHR_push_descriptor[] 4009 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR specifies 4010 that the descriptor update template will be used for push descriptor 4011 updates only. 4012endif::VK_KHR_push_descriptor[] 4013-- 4014 4015 4016[open,refpage='VkDescriptorUpdateTemplateEntry',desc='Describes a single descriptor update of the descriptor update template',type='structs'] 4017-- 4018The sname:VkDescriptorUpdateTemplateEntry structure is defined as: 4019include::{generated}/api/structs/VkDescriptorUpdateTemplateEntry.txt[] 4020 4021ifdef::VK_KHR_descriptor_update_template[] 4022or the equivalent 4023 4024include::{generated}/api/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] 4025endif::VK_KHR_descriptor_update_template[] 4026 4027 * pname:dstBinding is the descriptor binding to update when using this 4028 descriptor update template. 4029 * pname:dstArrayElement is the starting element in the array belonging to 4030 pname:dstBinding. 4031ifdef::VK_EXT_inline_uniform_block[] 4032 If the descriptor binding identified by pname:dstBinding has a 4033 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4034 then pname:dstArrayElement specifies the starting byte offset to update. 4035endif::VK_EXT_inline_uniform_block[] 4036 * pname:descriptorCount is the number of descriptors to update. 4037 If pname:descriptorCount is greater than the number of remaining array 4038 elements in the destination binding, those affect consecutive bindings 4039 in a manner similar to slink:VkWriteDescriptorSet above. 4040ifdef::VK_EXT_inline_uniform_block[] 4041 If the descriptor binding identified by pname:dstBinding has a 4042 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4043 then pname:descriptorCount specifies the number of bytes to update and 4044 the remaining array elements in the destination binding refer to the 4045 remaining number of bytes in it. 4046endif::VK_EXT_inline_uniform_block[] 4047 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 4048 the descriptor. 4049 * pname:offset is the offset in bytes of the first binding in the raw data 4050 structure. 4051 * pname:stride is the stride in bytes between two consecutive array 4052 elements of the descriptor update informations in the raw data 4053 structure. 4054 The actual pointer ptr for each array element j of update entry i is 4055 computed using the following formula: 4056+ 4057[source,c++] 4058~~~~ 4059 const char *ptr = (const char *)pData + pDescriptorUpdateEntries[i].offset + j * pDescriptorUpdateEntries[i].stride 4060~~~~ 4061+ 4062The stride is useful in case the bindings are stored in structs along with 4063other data. 4064ifdef::VK_EXT_inline_uniform_block[] 4065If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4066then the value of pname:stride is ignored and the stride is assumed to be 4067`1`, i.e. the descriptor update information for them is always specified as 4068a contiguous range. 4069endif::VK_EXT_inline_uniform_block[] 4070 4071.Valid Usage 4072**** 4073 * [[VUID-VkDescriptorUpdateTemplateEntry-dstBinding-00354]] 4074 pname:dstBinding must: be a valid binding in the descriptor set layout 4075 implicitly specified when using a descriptor update template to update 4076 descriptors 4077 * [[VUID-VkDescriptorUpdateTemplateEntry-dstArrayElement-00355]] 4078 pname:dstArrayElement and pname:descriptorCount must: be less than or 4079 equal to the number of array elements in the descriptor set binding 4080 implicitly specified when using a descriptor update template to update 4081 descriptors, and all applicable consecutive bindings, as described by 4082 <<descriptorsets-updates-consecutive>> 4083ifdef::VK_EXT_inline_uniform_block[] 4084 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02226]] 4085 If pname:descriptor type is 4086 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:dstArrayElement 4087 must: be an integer multiple of `4` 4088 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02227]] 4089 If pname:descriptor type is 4090 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:descriptorCount 4091 must: be an integer multiple of `4` 4092endif::VK_EXT_inline_uniform_block[] 4093**** 4094 4095include::{generated}/validity/structs/VkDescriptorUpdateTemplateEntry.txt[] 4096-- 4097 4098[open,refpage='vkDestroyDescriptorUpdateTemplate',desc='Destroy a descriptor update template object',type='protos'] 4099-- 4100To destroy a descriptor update template, call: 4101 4102ifdef::VK_VERSION_1_1[] 4103include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplate.txt[] 4104endif::VK_VERSION_1_1[] 4105 4106ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4107 4108ifdef::VK_KHR_descriptor_update_template[] 4109include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplateKHR.txt[] 4110endif::VK_KHR_descriptor_update_template[] 4111 4112 * pname:device is the logical device that has been used to create the 4113 descriptor update template 4114 * pname:descriptorUpdateTemplate is the descriptor update template to 4115 destroy. 4116 * pname:pAllocator controls host memory allocation as described in the 4117 <<memory-allocation, Memory Allocation>> chapter. 4118 4119.Valid Usage 4120**** 4121 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00356]] 4122 If sname:VkAllocationCallbacks were provided when 4123 pname:descriptorUpdateTemplate was created, a compatible set of 4124 callbacks must: be provided here 4125 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00357]] 4126 If no sname:VkAllocationCallbacks were provided when 4127 pname:descriptorUpdateTemplate was created, pname:pAllocator must: be 4128 `NULL` 4129**** 4130 4131include::{generated}/validity/protos/vkDestroyDescriptorUpdateTemplate.txt[] 4132-- 4133 4134[open,refpage='vkUpdateDescriptorSetWithTemplate',desc='Update the contents of a descriptor set object using an update template',type='protos'] 4135-- 4136Once a sname:VkDescriptorUpdateTemplate has been created, descriptor sets 4137can: be updated by calling: 4138 4139ifdef::VK_VERSION_1_1[] 4140include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplate.txt[] 4141endif::VK_VERSION_1_1[] 4142 4143ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4144 4145ifdef::VK_KHR_descriptor_update_template[] 4146include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplateKHR.txt[] 4147endif::VK_KHR_descriptor_update_template[] 4148 4149 * pname:device is the logical device that updates the descriptor set. 4150 * pname:descriptorSet is the descriptor set to update 4151 * pname:descriptorUpdateTemplate is a slink:VkDescriptorUpdateTemplate 4152 object specifying the update mapping between pname:pData and the 4153 descriptor set to update. 4154 * pname:pData is a pointer to memory containing one or more 4155 slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or 4156 slink:VkBufferView structures 4157ifdef::VK_KHR_acceleration_structure[or slink:VkAccelerationStructureKHR] 4158ifdef::VK_NV_ray_tracing[or slink:VkAccelerationStructureNV] 4159ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[handles] 4160 used to write the descriptors. 4161 4162.Valid Usage 4163**** 4164 * [[VUID-vkUpdateDescriptorSetWithTemplate-pData-01685]] 4165 pname:pData must: be a valid pointer to a memory containing one or more 4166 valid instances of slink:VkDescriptorImageInfo, 4167 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 4168 by pname:descriptorUpdateTemplate when it was created with 4169 flink:vkCreateDescriptorUpdateTemplate 4170**** 4171 4172include::{generated}/validity/protos/vkUpdateDescriptorSetWithTemplate.txt[] 4173 4174.API example 4175[source,c++] 4176~~~~ 4177struct AppBufferView { 4178 VkBufferView bufferView; 4179 uint32_t applicationRelatedInformation; 4180}; 4181 4182struct AppDataStructure 4183{ 4184 VkDescriptorImageInfo imageInfo; // a single image info 4185 VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array 4186 AppBufferView bufferView[2]; // An application defined structure containing a bufferView 4187 // ... some more application related data 4188}; 4189 4190const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 4191{ 4192 // binding to a single image descriptor 4193 { 4194 0, // binding 4195 0, // dstArrayElement 4196 1, // descriptorCount 4197 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 4198 offsetof(AppDataStructure, imageInfo), // offset 4199 0 // stride is not required if descriptorCount is 1 4200 }, 4201 4202 // binding to an array of buffer descriptors 4203 { 4204 1, // binding 4205 0, // dstArrayElement 4206 3, // descriptorCount 4207 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType 4208 offsetof(AppDataStructure, bufferInfoArray), // offset 4209 sizeof(VkDescriptorBufferInfo) // stride, descriptor buffer infos are compact 4210 }, 4211 4212 // binding to an array of buffer views 4213 { 4214 2, // binding 4215 0, // dstArrayElement 4216 2, // descriptorCount 4217 VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, // descriptorType 4218 offsetof(AppDataStructure, bufferView) + 4219 offsetof(AppBufferView, bufferView), // offset 4220 sizeof(AppBufferView) // stride, bufferViews do not have to be compact 4221 }, 4222}; 4223 4224// create a descriptor update template for descriptor set updates 4225const VkDescriptorUpdateTemplateCreateInfo createInfo = 4226{ 4227 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 4228 NULL, // pNext 4229 0, // flags 4230 3, // descriptorUpdateEntryCount 4231 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 4232 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, // templateType 4233 myLayout, // descriptorSetLayout 4234 0, // pipelineBindPoint, ignored by given templateType 4235 0, // pipelineLayout, ignored by given templateType 4236 0, // set, ignored by given templateType 4237}; 4238 4239VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 4240myResult = vkCreateDescriptorUpdateTemplate( 4241 myDevice, 4242 &createInfo, 4243 NULL, 4244 &myDescriptorUpdateTemplate); 4245 4246AppDataStructure appData; 4247 4248// fill appData here or cache it in your engine 4249vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData); 4250~~~~ 4251-- 4252endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4253 4254 4255[[descriptorsets-binding]] 4256=== Descriptor Set Binding 4257 4258[open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] 4259-- 4260To bind one or more descriptor sets to a command buffer, call: 4261 4262include::{generated}/api/protos/vkCmdBindDescriptorSets.txt[] 4263 4264 * pname:commandBuffer is the command buffer that the descriptor sets will 4265 be bound to. 4266 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4267 type of the pipeline that will use the descriptors. 4268 There is a separate set of bind points for each pipeline type, so 4269 binding one does not disturb the others. 4270 * pname:layout is a slink:VkPipelineLayout object used to program the 4271 bindings. 4272 * pname:firstSet is the set number of the first descriptor set to be 4273 bound. 4274 * pname:descriptorSetCount is the number of elements in the 4275 pname:pDescriptorSets array. 4276 * pname:pDescriptorSets is a pointer to an array of handles to 4277 slink:VkDescriptorSet objects describing the descriptor sets to bind to. 4278 * pname:dynamicOffsetCount is the number of dynamic offsets in the 4279 pname:pDynamicOffsets array. 4280 * pname:pDynamicOffsets is a pointer to an array of code:uint32_t values 4281 specifying dynamic offsets. 4282 4283fname:vkCmdBindDescriptorSets causes the sets numbered [pname:firstSet.. 4284pname:firstSet+pname:descriptorSetCount-1] to use the bindings stored in 4285pname:pDescriptorSets[0..descriptorSetCount-1] for subsequent 4286<<pipeline-bindpoint-commands, bound pipeline commands>> set by 4287pname:pipelineBindPoint. 4288Any bindings that were previously applied via these sets are no longer 4289valid. 4290 4291Once bound, a descriptor set affects rendering of subsequent commands that 4292interact with the given pipeline type in the command buffer until either a 4293different set is bound to the same set number, or the set is disturbed as 4294described in <<descriptorsets-compatibility, Pipeline Layout 4295Compatibility>>. 4296 4297A compatible descriptor set must: be bound for all set numbers that any 4298shaders in a pipeline access, at the time that a drawing or dispatching 4299command is recorded to execute using that pipeline. 4300However, if none of the shaders in a pipeline statically use any bindings 4301with a particular set number, then no descriptor set need be bound for that 4302set number, even if the pipeline layout includes a non-trivial descriptor 4303set layout for that set number. 4304 4305[[descriptorsets-binding-dynamicoffsets]] 4306If any of the sets being bound include dynamic uniform or storage buffers, 4307then pname:pDynamicOffsets includes one element for each array element in 4308each dynamic descriptor type binding in each set. 4309Values are taken from pname:pDynamicOffsets in an order such that all 4310entries for set N come before set N+1; within a set, entries are ordered by 4311the binding numbers in the descriptor set layouts; and within a binding 4312array, elements are in order. 4313pname:dynamicOffsetCount must: equal the total number of dynamic descriptors 4314in the sets being bound. 4315 4316The effective offset used for dynamic uniform and storage buffer bindings is 4317the sum of the relative offset taken from pname:pDynamicOffsets, and the 4318base address of the buffer plus base offset in the descriptor set. 4319The range of the dynamic uniform and storage buffer bindings is the buffer 4320range as specified in the descriptor set. 4321 4322Each of the pname:pDescriptorSets must: be compatible with the pipeline 4323layout specified by pname:layout. 4324The layout used to program the bindings must: also be compatible with the 4325pipeline used in subsequent <<pipeline-bindpoint-commands, bound pipeline 4326commands>> with that pipeline type, as defined in the 4327<<descriptorsets-compatibility, Pipeline Layout Compatibility>> section. 4328 4329The descriptor set contents bound by a call to fname:vkCmdBindDescriptorSets 4330may: be consumed at the following times: 4331 4332ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4333 * For descriptor bindings created with the 4334 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set, the contents 4335 may: be consumed when the command buffer is submitted to a queue, or 4336 during shader execution of the resulting draws and dispatches, or any 4337 time in between. 4338 Otherwise, 4339endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4340 * during host execution of the command, or during shader execution of the 4341 resulting draws and dispatches, or any time in between. 4342 4343Thus, the contents of a descriptor set binding must: not be altered 4344(overwritten by an update command, or freed) between the first point in time 4345that it may: be consumed, and when the command completes executing on the 4346queue. 4347 4348The contents of pname:pDynamicOffsets are consumed immediately during 4349execution of fname:vkCmdBindDescriptorSets. 4350Once all pending uses have completed, it is legal to update and reuse a 4351descriptor set. 4352 4353.Valid Usage 4354**** 4355 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-00358]] 4356 Each element of pname:pDescriptorSets must: have been allocated with a 4357 sname:VkDescriptorSetLayout that matches (is the same as, or identically 4358 defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, 4359 where _n_ is the sum of pname:firstSet and the index into 4360 pname:pDescriptorSets 4361 * [[VUID-vkCmdBindDescriptorSets-dynamicOffsetCount-00359]] 4362 pname:dynamicOffsetCount must: be equal to the total number of dynamic 4363 descriptors in pname:pDescriptorSets 4364 * [[VUID-vkCmdBindDescriptorSets-firstSet-00360]] 4365 The sum of pname:firstSet and pname:descriptorSetCount must: be less 4366 than or equal to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount 4367 provided when pname:layout was created 4368 * [[VUID-vkCmdBindDescriptorSets-pipelineBindPoint-00361]] 4369 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 4370 parent sname:VkCommandPool's queue family 4371 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01971]] 4372 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4373 binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: 4374 be a multiple of 4375 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 4376 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01972]] 4377 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4378 binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: 4379 be a multiple of 4380 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 4381 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-01979]] 4382 For each dynamic uniform or storage buffer binding in 4383 pname:pDescriptorSets, the sum of the effective offset, as defined 4384 above, and the range of the binding must: be less than or equal to the 4385 size of the buffer 4386ifdef::VK_VALVE_mutable_descriptor_type[] 4387 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-04616]] 4388 Each element of pname:pDescriptorSets must: not have been allocated from 4389 a sname:VkDescriptorPool with the 4390 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE flag set 4391endif::VK_VALVE_mutable_descriptor_type[] 4392**** 4393 4394include::{generated}/validity/protos/vkCmdBindDescriptorSets.txt[] 4395-- 4396 4397 4398ifdef::VK_KHR_push_descriptor[] 4399[[descriptorsets-push-descriptors]] 4400=== Push Descriptor Updates 4401 4402[open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] 4403-- 4404In addition to allocating descriptor sets and binding them to a command 4405buffer, an application can: record descriptor updates into the command 4406buffer. 4407 4408To push descriptor updates into a command buffer, call: 4409 4410include::{generated}/api/protos/vkCmdPushDescriptorSetKHR.txt[] 4411 4412 * pname:commandBuffer is the command buffer that the descriptors will be 4413 recorded in. 4414 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4415 type of the pipeline that will use the descriptors. 4416 There is a separate set of push descriptor bindings for each pipeline 4417 type, so binding one does not disturb the others. 4418 * pname:layout is a slink:VkPipelineLayout object used to program the 4419 bindings. 4420 * pname:set is the set number of the descriptor set in the pipeline layout 4421 that will be updated. 4422 * pname:descriptorWriteCount is the number of elements in the 4423 pname:pDescriptorWrites array. 4424 * pname:pDescriptorWrites is a pointer to an array of 4425 slink:VkWriteDescriptorSet structures describing the descriptors to be 4426 updated. 4427 4428_Push descriptors_ are a small bank of descriptors whose storage is 4429internally managed by the command buffer rather than being written into a 4430descriptor set and later bound to a command buffer. 4431Push descriptors allow for incremental updates of descriptors without 4432managing the lifetime of descriptor sets. 4433 4434When a command buffer begins recording, all push descriptors are undefined:. 4435Push descriptors can: be updated incrementally and cause shaders to use the 4436updated descriptors for subsequent <<pipeline-bindpoint-commands, bound 4437pipeline commands>> with the pipeline type set by pname:pipelineBindPoint 4438until the descriptor is overwritten, or else until the set is disturbed as 4439described in <<descriptorsets-compatibility, Pipeline Layout 4440Compatibility>>. 4441When the set is disturbed or push descriptors with a different descriptor 4442set layout are set, all push descriptors are undefined:. 4443 4444Push descriptors that are <<shaders-staticuse,statically used>> by a 4445pipeline must: not be undefined: at the time that a drawing or dispatching 4446command is recorded to execute using that pipeline. 4447This includes immutable sampler descriptors, which must: be pushed before 4448they are accessed by a pipeline (the immutable samplers are pushed, rather 4449than the samplers in pname:pDescriptorWrites). 4450Push descriptors that are not statically used can: remain undefined:. 4451 4452Push descriptors do not use dynamic offsets. 4453Instead, the corresponding non-dynamic descriptor types can: be used and the 4454pname:offset member of slink:VkDescriptorBufferInfo can: be changed each 4455time the descriptor is written. 4456 4457Each element of pname:pDescriptorWrites is interpreted as in 4458slink:VkWriteDescriptorSet, except the pname:dstSet member is ignored. 4459 4460To push an immutable sampler, use a slink:VkWriteDescriptorSet with 4461pname:dstBinding and pname:dstArrayElement selecting the immutable sampler's 4462binding. 4463If the descriptor type is ename:VK_DESCRIPTOR_TYPE_SAMPLER, the 4464pname:pImageInfo parameter is ignored and the immutable sampler is taken 4465from the push descriptor set layout in the pipeline layout. 4466If the descriptor type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 4467the pname:sampler member of the pname:pImageInfo parameter is ignored and 4468the immutable sampler is taken from the push descriptor set layout in the 4469pipeline layout. 4470 4471.Valid Usage 4472**** 4473 * [[VUID-vkCmdPushDescriptorSetKHR-pipelineBindPoint-00363]] 4474 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 4475 parent sname:VkCommandPool's queue family 4476 * [[VUID-vkCmdPushDescriptorSetKHR-set-00364]] 4477 pname:set must: be less than 4478 slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 4479 pname:layout was created 4480 * [[VUID-vkCmdPushDescriptorSetKHR-set-00365]] 4481 pname:set must: be the unique set number in the pipeline layout that 4482 uses a descriptor set layout that was created with 4483 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 4484**** 4485 4486include::{generated}/validity/protos/vkCmdPushDescriptorSetKHR.txt[] 4487 4488-- 4489 4490 4491ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4492=== Push Descriptor Updates with Descriptor Update Templates 4493 4494[open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] 4495-- 4496It is also possible to use a descriptor update template to specify the push 4497descriptors to update. 4498To do so, call: 4499 4500include::{generated}/api/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 4501 4502 * pname:commandBuffer is the command buffer that the descriptors will be 4503 recorded in. 4504 * pname:descriptorUpdateTemplate is a descriptor update template defining 4505 how to interpret the descriptor information in pname:pData. 4506 * pname:layout is a slink:VkPipelineLayout object used to program the 4507 bindings. 4508 It must: be compatible with the layout used to create the 4509 pname:descriptorUpdateTemplate handle. 4510 * pname:set is the set number of the descriptor set in the pipeline layout 4511 that will be updated. 4512 This must: be the same number used to create the 4513 pname:descriptorUpdateTemplate handle. 4514 * pname:pData is a pointer to memory containing descriptors for the 4515 templated update. 4516 4517.Valid Usage 4518**** 4519 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366]] 4520 The pname:pipelineBindPoint specified during the creation of the 4521 descriptor update template must: be supported by the 4522 pname:commandBuffer's parent sname:VkCommandPool's queue family 4523 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] 4524 pname:pData must: be a valid pointer to a memory containing one or more 4525 valid instances of slink:VkDescriptorImageInfo, 4526 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 4527 by pname:descriptorUpdateTemplate when it was created with 4528 flink:vkCreateDescriptorUpdateTemplate 4529**** 4530 4531include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 4532 4533.API example 4534[source,c++] 4535~~~~ 4536 4537struct AppDataStructure 4538{ 4539 VkDescriptorImageInfo imageInfo; // a single image info 4540 // ... some more application related data 4541}; 4542 4543const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 4544{ 4545 // binding to a single image descriptor 4546 { 4547 0, // binding 4548 0, // dstArrayElement 4549 1, // descriptorCount 4550 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 4551 offsetof(AppDataStructure, imageInfo), // offset 4552 0 // stride is not required if descriptorCount is 1 4553 } 4554}; 4555 4556// create a descriptor update template for push descriptor set updates 4557const VkDescriptorUpdateTemplateCreateInfo createInfo = 4558{ 4559 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 4560 NULL, // pNext 4561 0, // flags 4562 1, // descriptorUpdateEntryCount 4563 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 4564 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, // templateType 4565 0, // descriptorSetLayout, ignored by given templateType 4566 VK_PIPELINE_BIND_POINT_GRAPHICS, // pipelineBindPoint 4567 myPipelineLayout, // pipelineLayout 4568 0, // set 4569}; 4570 4571VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 4572myResult = vkCreateDescriptorUpdateTemplate( 4573 myDevice, 4574 &createInfo, 4575 NULL, 4576 &myDescriptorUpdateTemplate); 4577 4578AppDataStructure appData; 4579// fill appData here or cache it in your engine 4580vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); 4581~~~~ 4582-- 4583endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4584endif::VK_KHR_push_descriptor[] 4585 4586 4587[[descriptorsets-push-constants]] 4588=== Push Constant Updates 4589 4590As described above in section <<descriptorsets-pipelinelayout, Pipeline 4591Layouts>>, the pipeline layout defines shader push constants which are 4592updated via Vulkan commands rather than via writes to memory or copy 4593commands. 4594 4595[NOTE] 4596.Note 4597==== 4598Push constants represent a high speed path to modify constant data in 4599pipelines that is expected to outperform memory-backed resource updates. 4600==== 4601 4602[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] 4603-- 4604To update push constants, call: 4605 4606include::{generated}/api/protos/vkCmdPushConstants.txt[] 4607 4608 * pname:commandBuffer is the command buffer in which the push constant 4609 update will be recorded. 4610 * pname:layout is the pipeline layout used to program the push constant 4611 updates. 4612 * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying 4613 the shader stages that will use the push constants in the updated range. 4614 * pname:offset is the start offset of the push constant range to update, 4615 in units of bytes. 4616 * pname:size is the size of the push constant range to update, in units of 4617 bytes. 4618 * pname:pValues is a pointer to an array of pname:size bytes containing 4619 the new push constant values. 4620 4621When a command buffer begins recording, all push constant values are 4622undefined:. 4623ifdef::VK_KHR_maintenance4[] 4624Reads of undefined: push constant values by the executing shader return 4625undefined: values. 4626endif::VK_KHR_maintenance4[] 4627 4628Push constant values can: be updated incrementally, causing shader stages in 4629pname:stageFlags to read the new data from pname:pValues for push constants 4630modified by this command, while still reading the previous data for push 4631constants not modified by this command. 4632When a <<pipeline-bindpoint-commands, bound pipeline command>> is issued, 4633the bound pipeline's layout must: be compatible with the layouts used to set 4634the values of all push constants in the pipeline layout's push constant 4635ranges, as described in <<descriptorsets-compatibility,Pipeline Layout 4636Compatibility>>. 4637Binding a pipeline with a layout that is not compatible with the push 4638constant layout does not disturb the push constant values. 4639 4640[NOTE] 4641.Note 4642==== 4643As pname:stageFlags needs to include all flags the relevant push constant 4644ranges were created with, any flags that are not supported by the queue 4645family that the slink:VkCommandPool used to allocate pname:commandBuffer was 4646created on are ignored. 4647==== 4648 4649.Valid Usage 4650**** 4651 * [[VUID-vkCmdPushConstants-offset-01795]] 4652 For each byte in the range specified by pname:offset and pname:size and 4653 for each shader stage in pname:stageFlags, there must: be a push 4654 constant range in pname:layout that includes that byte and that stage 4655 * [[VUID-vkCmdPushConstants-offset-01796]] 4656 For each byte in the range specified by pname:offset and pname:size and 4657 for each push constant range that overlaps that byte, pname:stageFlags 4658 must: include all stages in that push constant range's 4659 slink:VkPushConstantRange::pname:stageFlags 4660 * [[VUID-vkCmdPushConstants-offset-00368]] 4661 pname:offset must: be a multiple of `4` 4662 * [[VUID-vkCmdPushConstants-size-00369]] 4663 pname:size must: be a multiple of `4` 4664 * [[VUID-vkCmdPushConstants-offset-00370]] 4665 pname:offset must: be less than 4666 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 4667 * [[VUID-vkCmdPushConstants-size-00371]] 4668 pname:size must: be less than or equal to 4669 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 4670 pname:offset 4671**** 4672 4673include::{generated}/validity/protos/vkCmdPushConstants.txt[] 4674-- 4675 4676 4677ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 4678[[descriptorsets-physical-storage-buffer]] 4679== Physical Storage Buffer Access 4680 4681[open,refpage='vkGetBufferDeviceAddress',desc='Query an address of a buffer',type='protos',alias='vkGetBufferDeviceAddressKHR'] 4682-- 4683To query a 64-bit buffer device address value through which buffer memory 4684can: be accessed in a shader, call: 4685 4686ifdef::VK_VERSION_1_2[] 4687include::{generated}/api/protos/vkGetBufferDeviceAddress.txt[] 4688endif::VK_VERSION_1_2[] 4689 4690ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 4691 4692ifdef::VK_KHR_buffer_device_address[] 4693include::{generated}/api/protos/vkGetBufferDeviceAddressKHR.txt[] 4694endif::VK_KHR_buffer_device_address[] 4695 4696// @Jon: 3-way conditional logic here is wrong 4697 4698ifdef::VK_EXT_buffer_device_address[] 4699or the equivalent command 4700 4701include::{generated}/api/protos/vkGetBufferDeviceAddressEXT.txt[] 4702endif::VK_EXT_buffer_device_address[] 4703 4704 * pname:device is the logical device that the buffer was created on. 4705 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 4706 specifying the buffer to retrieve an address for. 4707 4708The 64-bit return value is an address of the start of pname:pInfo->buffer. 4709The address range starting at this value and whose size is the size of the 4710buffer can: be used in a shader to access the memory bound to that buffer, 4711using the 4712ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4713`SPV_KHR_physical_storage_buffer` extension 4714ifdef::VK_EXT_buffer_device_address[or the equivalent] 4715endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4716ifdef::VK_EXT_buffer_device_address[] 4717`SPV_EXT_physical_storage_buffer` extension 4718endif::VK_EXT_buffer_device_address[] 4719and the code:PhysicalStorageBuffer storage class. 4720For example, this value can: be stored in a uniform buffer, and the shader 4721can: read the value from the uniform buffer and use it to do a dependent 4722read/write to this buffer. 4723A value of zero is reserved as a "`null`" pointer and must: not be returned 4724as a valid buffer device address. 4725All loads, stores, and atomics in a shader through 4726code:PhysicalStorageBuffer pointers must: access addresses in the address 4727range of some buffer. 4728 4729If the buffer was created with a non-zero value of 4730ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4731slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 4732ifdef::VK_EXT_buffer_device_address[or] 4733endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4734ifdef::VK_EXT_buffer_device_address[] 4735slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress 4736endif::VK_EXT_buffer_device_address[] 4737the return value will be the same address that was returned at capture time. 4738 4739.Valid Usage 4740**** 4741 * [[VUID-vkGetBufferDeviceAddress-bufferDeviceAddress-03324]] 4742 The <<features-bufferDeviceAddress,bufferDeviceAddress>> or 4743 <<features-bufferDeviceAddressEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddress>> 4744 feature must: be enabled 4745 * [[VUID-vkGetBufferDeviceAddress-device-03325]] 4746 If pname:device was created with multiple physical devices, then the 4747 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 4748 or 4749 <<features-bufferDeviceAddressMultiDeviceEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddressMultiDevice>> 4750 feature must: be enabled 4751**** 4752 4753include::{generated}/validity/protos/vkGetBufferDeviceAddress.txt[] 4754-- 4755 4756[open,refpage='VkBufferDeviceAddressInfo',desc='Structure specifying the buffer to query an address for',type='structs',alias='VkBufferDeviceAddressInfoKHR,VkBufferDeviceAddressInfoEXT'] 4757-- 4758The sname:VkBufferDeviceAddressInfo structure is defined as: 4759 4760include::{generated}/api/structs/VkBufferDeviceAddressInfo.txt[] 4761 4762ifdef::VK_KHR_buffer_device_address[] 4763or the equivalent 4764 4765include::{generated}/api/structs/VkBufferDeviceAddressInfoKHR.txt[] 4766endif::VK_KHR_buffer_device_address[] 4767 4768// @Jon: three-way conditional logic is broken 4769ifdef::VK_EXT_buffer_device_address[] 4770or the equivalent 4771 4772include::{generated}/api/structs/VkBufferDeviceAddressInfoEXT.txt[] 4773endif::VK_EXT_buffer_device_address[] 4774 4775 * pname:sType is the type of this structure. 4776 * pname:pNext is `NULL` or a pointer to a structure extending this 4777 structure. 4778 * pname:buffer specifies the buffer whose address is being queried. 4779 4780.Valid Usage 4781**** 4782 * [[VUID-VkBufferDeviceAddressInfo-buffer-02600]] 4783 If pname:buffer is non-sparse and was not created with the 4784 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag, then it 4785 must: be bound completely and contiguously to a single 4786 sname:VkDeviceMemory object 4787 * [[VUID-VkBufferDeviceAddressInfo-buffer-02601]] 4788 pname:buffer must: have been created with 4789 ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT 4790**** 4791 4792include::{generated}/validity/structs/VkBufferDeviceAddressInfo.txt[] 4793-- 4794endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 4795 4796ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4797[open,refpage='vkGetBufferOpaqueCaptureAddress',desc='Query an opaque capture address of a buffer',type='protos',alias='vkGetBufferOpaqueCaptureAddressKHR'] 4798-- 4799To query a 64-bit buffer opaque capture address, call: 4800 4801ifdef::VK_VERSION_1_2[] 4802include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddress.txt[] 4803endif::VK_VERSION_1_2[] 4804 4805ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 4806 4807ifdef::VK_KHR_buffer_device_address[] 4808include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddressKHR.txt[] 4809endif::VK_KHR_buffer_device_address[] 4810 4811 * pname:device is the logical device that the buffer was created on. 4812 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 4813 specifying the buffer to retrieve an address for. 4814 4815The 64-bit return value is an opaque capture address of the start of 4816pname:pInfo->buffer. 4817 4818If the buffer was created with a non-zero value of 4819slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress the 4820return value must: be the same address. 4821 4822.Valid Usage 4823**** 4824 * [[VUID-vkGetBufferOpaqueCaptureAddress-None-03326]] 4825 The <<features-bufferDeviceAddress,bufferDeviceAddress>> feature must: 4826 be enabled 4827 * [[VUID-vkGetBufferOpaqueCaptureAddress-device-03327]] 4828 If pname:device was created with multiple physical devices, then the 4829 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 4830 feature must: be enabled 4831**** 4832 4833include::{generated}/validity/protos/vkGetBufferOpaqueCaptureAddress.txt[] 4834-- 4835endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4836