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 defining which 607 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 the pname:descriptorType specified in 2954 sname:VkDescriptorSetLayoutBinding 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[] 3279ifdef::VK_EXT_image_view_min_lod[] 3280 * [[VUID-VkWriteDescriptorSet-descriptorType-06450]] 3281 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3282 the pname:imageView member of each element of pname:pImageInfo must: 3283 have either been created without a slink:VkImageViewMinLodCreateInfoEXT 3284 present in the pname:pNext chain or with a 3285 slink:VkImageViewMinLodCreateInfoEXT::pname:minLod of `0.0` 3286endif::VK_EXT_image_view_min_lod[] 3287**** 3288 3289include::{generated}/validity/structs/VkWriteDescriptorSet.txt[] 3290-- 3291 3292[open,refpage='VkDescriptorType',desc='Specifies the type of a descriptor in a descriptor set',type='enums'] 3293-- 3294The type of descriptors in a descriptor set is specified by 3295slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the 3296values: 3297 3298include::{generated}/api/enums/VkDescriptorType.txt[] 3299 3300 * ename:VK_DESCRIPTOR_TYPE_SAMPLER specifies a <<descriptorsets-sampler, 3301 sampler descriptor>>. 3302 * ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER specifies a 3303 <<descriptorsets-combinedimagesampler, combined image sampler 3304 descriptor>>. 3305 * ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE specifies a 3306 <<descriptorsets-sampledimage, sampled image descriptor>>. 3307 * ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE specifies a 3308 <<descriptorsets-storageimage, storage image descriptor>>. 3309 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER specifies a 3310 <<descriptorsets-uniformtexelbuffer, uniform texel buffer descriptor>>. 3311 * ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER specifies a 3312 <<descriptorsets-storagetexelbuffer, storage texel buffer descriptor>>. 3313 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER specifies a 3314 <<descriptorsets-uniformbuffer, uniform buffer descriptor>>. 3315 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER specifies a 3316 <<descriptorsets-storagebuffer, storage buffer descriptor>>. 3317 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC specifies a 3318 <<descriptorsets-uniformbufferdynamic, dynamic uniform buffer 3319 descriptor>>. 3320 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC specifies a 3321 <<descriptorsets-storagebufferdynamic, dynamic storage buffer 3322 descriptor>>. 3323 * ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT specifies an 3324 <<descriptorsets-inputattachment, input attachment descriptor>>. 3325ifdef::VK_EXT_inline_uniform_block[] 3326 * ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT specifies an 3327 <<descriptorsets-inlineuniformblock, inline uniform block>>. 3328endif::VK_EXT_inline_uniform_block[] 3329ifdef::VK_VALVE_mutable_descriptor_type[] 3330 * ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE specifies a 3331 <<descriptorsets-mutable, descriptor of mutable type>>. 3332endif::VK_VALVE_mutable_descriptor_type[] 3333 3334When a descriptor set is updated via elements of slink:VkWriteDescriptorSet, 3335members of pname:pImageInfo, pname:pBufferInfo and pname:pTexelBufferView 3336are only accessed by the implementation when they correspond to descriptor 3337type being defined - otherwise they are ignored. 3338The members accessed are as follows for each descriptor type: 3339 3340 * For ename:VK_DESCRIPTOR_TYPE_SAMPLER, only the pname:sampler member of 3341 each element of slink:VkWriteDescriptorSet::pname:pImageInfo is 3342 accessed. 3343 * For ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3344 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3345 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only the pname:imageView and 3346 pname:imageLayout members of each element of 3347 slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3348 * For ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each 3349 element of slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3350 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3351 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3352 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3353 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each 3354 element of slink:VkWriteDescriptorSet::pname:pBufferInfo are accessed. 3355 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 3356 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 3357 slink:VkWriteDescriptorSet::pname:pTexelBufferView is accessed. 3358 3359ifdef::VK_EXT_inline_uniform_block[] 3360When updating descriptors with a pname:descriptorType of 3361ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, 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:VkWriteDescriptorSetInlineUniformBlockEXT structure in 3365the pname:pNext chain of sname:VkWriteDescriptorSet. 3366endif::VK_EXT_inline_uniform_block[] 3367ifdef::VK_KHR_acceleration_structure[] 3368When updating descriptors with a pname:descriptorType of 3369ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, 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:VkWriteDescriptorSetAccelerationStructureKHR structure 3373in the pname:pNext chain of sname:VkWriteDescriptorSet. 3374endif::VK_KHR_acceleration_structure[] 3375ifdef::VK_NV_ray_tracing[] 3376When updating descriptors with a pname:descriptorType of 3377ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, none of the 3378pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3379accessed, instead the source data of the descriptor update operation is 3380taken from the slink:VkWriteDescriptorSetAccelerationStructureNV structure 3381in the pname:pNext chain of sname:VkWriteDescriptorSet. 3382endif::VK_NV_ray_tracing[] 3383-- 3384 3385[open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer information',type='structs'] 3386-- 3387The sname:VkDescriptorBufferInfo structure is defined as: 3388 3389include::{generated}/api/structs/VkDescriptorBufferInfo.txt[] 3390 3391 * pname:buffer is 3392ifdef::VK_EXT_robustness2[] 3393dlink:VK_NULL_HANDLE or 3394endif::VK_EXT_robustness2[] 3395the buffer resource. 3396 * pname:offset is the offset in bytes from the start of pname:buffer. 3397 Access to buffer memory via this descriptor uses addressing that is 3398 relative to this starting offset. 3399 * pname:range is the size in bytes that is used for this descriptor 3400 update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the 3401 end of the buffer. 3402 3403[NOTE] 3404.Note 3405==== 3406When setting pname:range to ename:VK_WHOLE_SIZE, the effective range must: 3407not be larger than the maximum range for the descriptor type 3408(<<limits-maxUniformBufferRange, pname:maxUniformBufferRange>> or 3409<<limits-maxStorageBufferRange, pname:maxStorageBufferRange>>). 3410This means that ename:VK_WHOLE_SIZE is not typically useful in the common 3411case where uniform buffer descriptors are suballocated from a buffer that is 3412much larger than pname:maxUniformBufferRange. 3413==== 3414 3415For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and 3416ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, 3417pname:offset is the base offset from which the dynamic offset is applied and 3418pname:range is the static size used for all dynamic offsets. 3419 3420.Valid Usage 3421**** 3422 * [[VUID-VkDescriptorBufferInfo-offset-00340]] 3423 pname:offset must: be less than the size of pname:buffer 3424 * [[VUID-VkDescriptorBufferInfo-range-00341]] 3425 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3426 greater than `0` 3427 * [[VUID-VkDescriptorBufferInfo-range-00342]] 3428 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3429 less than or equal to the size of pname:buffer minus pname:offset 3430 * [[VUID-VkDescriptorBufferInfo-buffer-02998]] 3431 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3432 enabled, pname:buffer must: not be dlink:VK_NULL_HANDLE 3433ifdef::VK_EXT_robustness2[] 3434 * [[VUID-VkDescriptorBufferInfo-buffer-02999]] 3435 If pname:buffer is dlink:VK_NULL_HANDLE, pname:offset must: be zero and 3436 pname:range must: be ename:VK_WHOLE_SIZE 3437endif::VK_EXT_robustness2[] 3438**** 3439 3440include::{generated}/validity/structs/VkDescriptorBufferInfo.txt[] 3441-- 3442 3443[open,refpage='VkDescriptorImageInfo',desc='Structure specifying descriptor image information',type='structs'] 3444-- 3445The sname:VkDescriptorImageInfo structure is defined as: 3446 3447include::{generated}/api/structs/VkDescriptorImageInfo.txt[] 3448 3449 * pname:sampler is a sampler handle, and is used in descriptor updates for 3450 types ename:VK_DESCRIPTOR_TYPE_SAMPLER and 3451 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER if the binding being 3452 updated does not use immutable samplers. 3453 * pname:imageView is 3454ifdef::VK_EXT_robustness2[] 3455 dlink:VK_NULL_HANDLE or 3456endif::VK_EXT_robustness2[] 3457 an image view handle, and is used in descriptor updates for types 3458 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3459 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3460 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3461 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3462 * pname:imageLayout is the layout that the image subresources accessible 3463 from pname:imageView will be in at the time this descriptor is accessed. 3464 pname:imageLayout is used in descriptor updates for types 3465 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3466 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3467 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3468 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3469 3470Members of sname:VkDescriptorImageInfo that are not used in an update (as 3471described above) are ignored. 3472 3473.Valid Usage 3474**** 3475ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3476 * [[VUID-VkDescriptorImageInfo-imageView-00343]] 3477 pname:imageView must: not be 2D or 2D array image view created from a 3D 3478 image 3479endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3480 * [[VUID-VkDescriptorImageInfo-imageView-01976]] 3481 If pname:imageView is created from a depth/stencil image, the 3482 pname:aspectMask used to create the pname:imageView must: include either 3483 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT but 3484 not both 3485 * [[VUID-VkDescriptorImageInfo-imageLayout-00344]] 3486 pname:imageLayout must: match the actual elink:VkImageLayout of each 3487 subresource accessible from pname:imageView at the time this descriptor 3488 is accessed as defined by the <<resources-image-layouts-matching-rule, 3489 image layout matching rules>> 3490ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3491 * [[VUID-VkDescriptorImageInfo-sampler-01564]] 3492 If pname:sampler is used and the elink:VkFormat of the image is a 3493 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, the 3494 image must: have been created with 3495 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the pname:aspectMask of 3496 the pname:imageView must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 3497 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or (for three-plane formats only) 3498 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 3499endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3500ifdef::VK_KHR_portability_subset[] 3501 * [[VUID-VkDescriptorImageInfo-mutableComparisonSamplers-04450]] 3502 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 3503 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:mutableComparisonSamplers 3504 is ename:VK_FALSE, then pname:sampler must: have been created with 3505 slink:VkSamplerCreateInfo::pname:compareEnable set to ename:VK_FALSE 3506endif::VK_KHR_portability_subset[] 3507**** 3508 3509 3510include::{generated}/validity/structs/VkDescriptorImageInfo.txt[] 3511-- 3512 3513ifdef::VK_EXT_inline_uniform_block[] 3514[open,refpage='VkWriteDescriptorSetInlineUniformBlockEXT',desc='Structure specifying inline uniform block data',type='structs'] 3515-- 3516If the pname:descriptorType member of slink:VkWriteDescriptorSet is 3517ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then the data to write to 3518the descriptor set is specified through a 3519sname:VkWriteDescriptorSetInlineUniformBlockEXT structure included in the 3520pname:pNext chain of sname:VkWriteDescriptorSet. 3521 3522The sname:VkWriteDescriptorSetInlineUniformBlockEXT structure is defined as: 3523 3524include::{generated}/api/structs/VkWriteDescriptorSetInlineUniformBlockEXT.txt[] 3525 3526 * pname:sType is the type of this structure. 3527 * pname:pNext is `NULL` or a pointer to a structure extending this 3528 structure. 3529 * pname:dataSize is the number of bytes of inline uniform block data 3530 pointed to by pname:pData. 3531 * pname:pData is a pointer to pname:dataSize number of bytes of data to 3532 write to the inline uniform block. 3533 3534.Valid Usage 3535**** 3536 * [[VUID-VkWriteDescriptorSetInlineUniformBlockEXT-dataSize-02222]] 3537 pname:dataSize must: be an integer multiple of `4` 3538**** 3539 3540include::{generated}/validity/structs/VkWriteDescriptorSetInlineUniformBlockEXT.txt[] 3541-- 3542endif::VK_EXT_inline_uniform_block[] 3543 3544ifdef::VK_KHR_acceleration_structure[] 3545[open,refpage='VkWriteDescriptorSetAccelerationStructureKHR',desc='Structure specifying acceleration structure descriptor information',type='structs'] 3546-- 3547:refpage: VkWriteDescriptorSetAccelerationStructureKHR 3548 3549The sname:VkWriteDescriptorSetAccelerationStructureKHR structure is defined 3550as: 3551 3552include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureKHR.txt[] 3553 3554 * pname:sType is the type of this structure. 3555 * pname:pNext is `NULL` or a pointer to a structure extending this 3556 structure. 3557 * pname:accelerationStructureCount is the number of elements in 3558 pname:pAccelerationStructures. 3559 * pname:pAccelerationStructures is a pointer to an array of 3560 slink:VkAccelerationStructureKHR structures specifying the acceleration 3561 structures to update. 3562 3563.Valid Usage 3564**** 3565 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-accelerationStructureCount-02236]] 3566 pname:accelerationStructureCount must: be equal to pname:descriptorCount 3567 in the extended structure 3568 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03579]] 3569 Each acceleration structure in pname:pAccelerationStructures must: have 3570 been created with a pname:type of 3571 ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or 3572 ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 3573 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03580]] 3574 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3575 enabled, each element of pname:pAccelerationStructures must: not be 3576 dlink:VK_NULL_HANDLE 3577**** 3578 3579include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureKHR.txt[] 3580-- 3581endif::VK_KHR_acceleration_structure[] 3582 3583ifdef::VK_NV_ray_tracing[] 3584[open,refpage='VkWriteDescriptorSetAccelerationStructureNV',desc='Structure specifying acceleration structure descriptor information',type='structs'] 3585-- 3586:refpage: VkWriteDescriptorSetAccelerationStructureNV 3587 3588The sname:VkWriteDescriptorSetAccelerationStructureNV structure is defined 3589as: 3590 3591include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] 3592 3593 * pname:sType is the type of this structure. 3594 * pname:pNext is `NULL` or a pointer to a structure extending this 3595 structure. 3596 * pname:accelerationStructureCount is the number of elements in 3597 pname:pAccelerationStructures. 3598 * pname:pAccelerationStructures is a pointer to an array of 3599 slink:VkAccelerationStructureNV structures specifying the acceleration 3600 structures to update. 3601 3602.Valid Usage 3603**** 3604 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-accelerationStructureCount-03747]] 3605 pname:accelerationStructureCount must: be equal to pname:descriptorCount 3606 in the extended structure 3607 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03748]] 3608 Each acceleration structure in pname:pAccelerationStructures must: have 3609 been created with ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR 3610 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03749]] 3611 If the <<features-nullDescriptor,nullDescriptor>> feature is not 3612 enabled, each member of pname:pAccelerationStructures must: not be 3613 dlink:VK_NULL_HANDLE 3614**** 3615 3616include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureNV.txt[] 3617-- 3618endif::VK_NV_ray_tracing[] 3619 3620[open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] 3621-- 3622The sname:VkCopyDescriptorSet structure is defined as: 3623 3624include::{generated}/api/structs/VkCopyDescriptorSet.txt[] 3625 3626 * pname:sType is the type of this structure. 3627 * pname:pNext is `NULL` or a pointer to a structure extending this 3628 structure. 3629 * pname:srcSet, pname:srcBinding, and pname:srcArrayElement are the source 3630 set, binding, and array element, respectively. 3631ifdef::VK_EXT_inline_uniform_block[] 3632 If the descriptor binding identified by pname:srcSet and 3633 pname:srcBinding has a descriptor type of 3634 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3635 pname:srcArrayElement specifies the starting byte offset within the 3636 binding to copy from. 3637endif::VK_EXT_inline_uniform_block[] 3638 * pname:dstSet, pname:dstBinding, and pname:dstArrayElement are the 3639 destination set, binding, and array element, respectively. 3640ifdef::VK_EXT_inline_uniform_block[] 3641 If the descriptor binding identified by pname:dstSet and 3642 pname:dstBinding has a descriptor type of 3643 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3644 pname:dstArrayElement specifies the starting byte offset within the 3645 binding to copy to. 3646endif::VK_EXT_inline_uniform_block[] 3647 * pname:descriptorCount is the number of descriptors to copy from the 3648 source to destination. 3649 If pname:descriptorCount is greater than the number of remaining array 3650 elements in the source or destination binding, those affect consecutive 3651 bindings in a manner similar to slink:VkWriteDescriptorSet above. 3652ifdef::VK_EXT_inline_uniform_block[] 3653 If the descriptor binding identified by pname:srcSet and 3654 pname:srcBinding has a descriptor type of 3655 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT then 3656 pname:descriptorCount specifies the number of bytes to copy and the 3657 remaining array elements in the source or destination binding refer to 3658 the remaining number of bytes in those. 3659endif::VK_EXT_inline_uniform_block[] 3660 3661ifdef::VK_VALVE_mutable_descriptor_type[] 3662If the sname:VkDescriptorSetLayoutBinding for pname:dstBinding is 3663ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE and pname:srcBinding is not 3664ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new active descriptor type 3665becomes the descriptor type of pname:srcBinding. 3666If both sname:VkDescriptorSetLayoutBinding for pname:srcBinding and 3667pname:dstBinding are ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the active 3668descriptor type in each source descriptor is copied into the corresponding 3669destination descriptor. 3670The active descriptor type can: be different for each source descriptor. 3671 3672[NOTE] 3673.Note 3674==== 3675The intention is that copies to and from mutable descriptors is a simple 3676memcpy. 3677Copies between non-mutable and mutable descriptors are expected to require 3678one memcpy per descriptor to handle the difference in size, but this use 3679case with more than one pname:descriptorCount is considered rare. 3680==== 3681endif::VK_VALVE_mutable_descriptor_type[] 3682 3683.Valid Usage 3684**** 3685 * [[VUID-VkCopyDescriptorSet-srcBinding-00345]] 3686 pname:srcBinding must: be a valid binding within pname:srcSet 3687 * [[VUID-VkCopyDescriptorSet-srcArrayElement-00346]] 3688 The sum of pname:srcArrayElement and pname:descriptorCount must: be less 3689 than or equal to the number of array elements in the descriptor set 3690 binding specified by pname:srcBinding, and all applicable consecutive 3691 bindings, as described by <<descriptorsets-updates-consecutive>> 3692 * [[VUID-VkCopyDescriptorSet-dstBinding-00347]] 3693 pname:dstBinding must: be a valid binding within pname:dstSet 3694 * [[VUID-VkCopyDescriptorSet-dstArrayElement-00348]] 3695 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 3696 than or equal to the number of array elements in the descriptor set 3697 binding specified by pname:dstBinding, and all applicable consecutive 3698 bindings, as described by <<descriptorsets-updates-consecutive>> 3699 * [[VUID-VkCopyDescriptorSet-dstBinding-02632]] 3700 The type of pname:dstBinding within pname:dstSet must: be equal to the 3701 type of pname:srcBinding within pname:srcSet 3702 * [[VUID-VkCopyDescriptorSet-srcSet-00349]] 3703 If pname:srcSet is equal to pname:dstSet, then the source and 3704 destination ranges of descriptors must: not overlap, where the ranges 3705 may: include array elements from consecutive bindings as described by 3706 <<descriptorsets-updates-consecutive>> 3707ifdef::VK_EXT_inline_uniform_block[] 3708 * [[VUID-VkCopyDescriptorSet-srcBinding-02223]] 3709 If the descriptor type of the descriptor set binding specified by 3710 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, 3711 pname:srcArrayElement must: be an integer multiple of `4` 3712 * [[VUID-VkCopyDescriptorSet-dstBinding-02224]] 3713 If the descriptor type of the descriptor set binding specified by 3714 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, 3715 pname:dstArrayElement must: be an integer multiple of `4` 3716 * [[VUID-VkCopyDescriptorSet-srcBinding-02225]] 3717 If the descriptor type of the descriptor set binding specified by either 3718 pname:srcBinding or pname:dstBinding is 3719 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:descriptorCount 3720 must: be an integer multiple of `4` 3721endif::VK_EXT_inline_uniform_block[] 3722ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3723 * [[VUID-VkCopyDescriptorSet-srcSet-01918]] 3724 If pname:srcSet's layout was created with the 3725 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3726 set, then pname:dstSet's layout must: also have been created with the 3727 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3728 set 3729ifdef::VK_VALVE_mutable_descriptor_type[] 3730 * [[VUID-VkCopyDescriptorSet-srcSet-04885]] 3731 If pname:srcSet's layout was created with neither 3732 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT nor 3733 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE flags 3734 set, then pname:dstSet's layout must: 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[] 3738ifndef::VK_VALVE_mutable_descriptor_type[] 3739 * [[VUID-VkCopyDescriptorSet-srcSet-04886]] 3740 If pname:srcSet's layout was created without the 3741 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3742 set, then pname:dstSet's layout must: also have been created without the 3743 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 3744 set 3745endif::VK_VALVE_mutable_descriptor_type[] 3746 * [[VUID-VkCopyDescriptorSet-srcSet-01920]] 3747 If the descriptor pool from which pname:srcSet was allocated was created 3748 with the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set, 3749 then the descriptor pool from which pname:dstSet was allocated must: 3750 also have been created with the 3751 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3752ifdef::VK_VALVE_mutable_descriptor_type[] 3753 * [[VUID-VkCopyDescriptorSet-srcSet-04887]] 3754 If the descriptor pool from which pname:srcSet was allocated was created 3755 with neither ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT nor 3756 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE flags set, then the 3757 descriptor pool from which pname:dstSet was allocated must: have been 3758 created without the 3759 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3760endif::VK_VALVE_mutable_descriptor_type[] 3761ifndef::VK_VALVE_mutable_descriptor_type[] 3762 * [[VUID-VkCopyDescriptorSet-srcSet-04888]] 3763 If the descriptor pool from which pname:srcSet was allocated was created 3764 without the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag 3765 set, then the descriptor pool from which pname:dstSet was allocated 3766 must: also have been created without the 3767 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 3768endif::VK_VALVE_mutable_descriptor_type[] 3769endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3770 * [[VUID-VkCopyDescriptorSet-dstBinding-02753]] 3771 If the descriptor type of the descriptor set binding specified by 3772 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_SAMPLER, then pname:dstSet 3773 must: not have been allocated with a layout that included immutable 3774 samplers for pname:dstBinding 3775ifdef::VK_VALVE_mutable_descriptor_type[] 3776 * [[VUID-VkCopyDescriptorSet-dstSet-04612]] 3777 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3778 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the new 3779 active descriptor type must: exist in the corresponding 3780 pname:pMutableDescriptorTypeLists list for pname:dstBinding if the new 3781 active descriptor type is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 3782 * [[VUID-VkCopyDescriptorSet-srcSet-04613]] 3783 If sname:VkDescriptorSetLayoutBinding for pname:srcSet at 3784 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE and the 3785 sname:VkDescriptorSetLayoutBinding for pname:dstSet at pname:dstBinding 3786 is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the active descriptor 3787 type for the source descriptor must: match the descriptor type of 3788 pname:dstBinding 3789 * [[VUID-VkCopyDescriptorSet-dstSet-04614]] 3790 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3791 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, and the new 3792 active descriptor type is ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE, the 3793 pname:pMutableDescriptorTypeLists for pname:srcBinding and 3794 pname:dstBinding must: match exactly 3795endif::VK_VALVE_mutable_descriptor_type[] 3796**** 3797 3798include::{generated}/validity/structs/VkCopyDescriptorSet.txt[] 3799-- 3800 3801 3802ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 3803[[descriptorsets-updates-with-template]] 3804=== Descriptor Update Templates 3805 3806[open,refpage='VkDescriptorUpdateTemplate',desc='Opaque handle to a descriptor update template',type='handles'] 3807-- 3808A descriptor update template specifies a mapping from descriptor update 3809information in host memory to descriptors in a descriptor set. 3810It is designed to avoid passing redundant information to the driver when 3811frequently updating the same set of descriptors in descriptor sets. 3812 3813Descriptor update template objects are represented by 3814sname:VkDescriptorUpdateTemplate handles: 3815 3816include::{generated}/api/handles/VkDescriptorUpdateTemplate.txt[] 3817 3818ifdef::VK_KHR_descriptor_update_template[] 3819or the equivalent 3820 3821include::{generated}/api/handles/VkDescriptorUpdateTemplateKHR.txt[] 3822endif::VK_KHR_descriptor_update_template[] 3823-- 3824 3825 3826=== Descriptor Set Updates with Templates 3827 3828[open,refpage='vkCreateDescriptorUpdateTemplate',desc='Create a new descriptor update template',type='protos'] 3829-- 3830Updating a large sname:VkDescriptorSet array can: be an expensive operation 3831since an application must: specify one slink:VkWriteDescriptorSet structure 3832for each descriptor or descriptor array to update, each of which 3833re-specifies the same state when updating the same descriptor in multiple 3834descriptor sets. 3835For cases when an application wishes to update the same set of descriptors 3836in multiple descriptor sets allocated using the same 3837sname:VkDescriptorSetLayout, flink:vkUpdateDescriptorSetWithTemplate can: be 3838used as a replacement for flink:vkUpdateDescriptorSets. 3839 3840sname:VkDescriptorUpdateTemplate allows implementations to convert a set of 3841descriptor update operations on a single descriptor set to an internal 3842format that, in conjunction with flink:vkUpdateDescriptorSetWithTemplate 3843ifdef::VK_KHR_push_descriptor[] 3844or flink:vkCmdPushDescriptorSetWithTemplateKHR 3845endif::VK_KHR_push_descriptor[] 3846, can: be more efficient compared to calling flink:vkUpdateDescriptorSets 3847ifdef::VK_KHR_push_descriptor[] 3848or flink:vkCmdPushDescriptorSetKHR 3849endif::VK_KHR_push_descriptor[] 3850. 3851The descriptors themselves are not specified in the 3852sname:VkDescriptorUpdateTemplate, rather, offsets into an application 3853provided pointer to host memory are specified, which are combined with a 3854pointer passed to flink:vkUpdateDescriptorSetWithTemplate 3855ifdef::VK_KHR_push_descriptor[] 3856or flink:vkCmdPushDescriptorSetWithTemplateKHR 3857endif::VK_KHR_push_descriptor[] 3858. 3859This allows large batches of updates to be executed without having to 3860convert application data structures into a strictly-defined Vulkan data 3861structure. 3862 3863To create a descriptor update template, call: 3864 3865ifdef::VK_VERSION_1_1[] 3866include::{generated}/api/protos/vkCreateDescriptorUpdateTemplate.txt[] 3867endif::VK_VERSION_1_1[] 3868 3869ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 3870 3871ifdef::VK_KHR_descriptor_update_template[] 3872include::{generated}/api/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] 3873endif::VK_KHR_descriptor_update_template[] 3874 3875 * pname:device is the logical device that creates the descriptor update 3876 template. 3877 * pname:pCreateInfo is a pointer to a 3878 slink:VkDescriptorUpdateTemplateCreateInfo structure specifying the set 3879 of descriptors to update with a single call to 3880ifdef::VK_KHR_push_descriptor[] 3881 flink:vkCmdPushDescriptorSetWithTemplateKHR or 3882endif::VK_KHR_push_descriptor[] 3883 flink:vkUpdateDescriptorSetWithTemplate. 3884 * pname:pAllocator controls host memory allocation as described in the 3885 <<memory-allocation, Memory Allocation>> chapter. 3886 * pname:pDescriptorUpdateTemplate is a pointer to a 3887 sname:VkDescriptorUpdateTemplate handle in which the resulting 3888 descriptor update template object is returned. 3889 3890include::{generated}/validity/protos/vkCreateDescriptorUpdateTemplate.txt[] 3891-- 3892 3893[open,refpage='VkDescriptorUpdateTemplateCreateInfo',desc='Structure specifying parameters of a newly created descriptor update template',type='structs'] 3894-- 3895The slink:VkDescriptorUpdateTemplateCreateInfo structure is defined as: 3896include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 3897 3898ifdef::VK_KHR_descriptor_update_template[] 3899or the equivalent 3900 3901include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfoKHR.txt[] 3902endif::VK_KHR_descriptor_update_template[] 3903 3904 * pname:sType is the type of this structure. 3905 * pname:pNext is `NULL` or a pointer to a structure extending this 3906 structure. 3907 * pname:flags is reserved for future use. 3908 * pname:descriptorUpdateEntryCount is the number of elements in the 3909 pname:pDescriptorUpdateEntries array. 3910 * pname:pDescriptorUpdateEntries is a pointer to an array of 3911 slink:VkDescriptorUpdateTemplateEntry structures describing the 3912 descriptors to be updated by the descriptor update template. 3913 * pname:templateType Specifies the type of the descriptor update template. 3914 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET it 3915 can: only be used to update descriptor sets with a fixed 3916 pname:descriptorSetLayout. 3917ifdef::VK_KHR_push_descriptor[] 3918 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3919 it can: only be used to push descriptor sets using the provided 3920 pname:pipelineBindPoint, pname:pipelineLayout, and pname:set number. 3921endif::VK_KHR_push_descriptor[] 3922 * pname:descriptorSetLayout is the descriptor set layout used to build the 3923 descriptor update template. 3924 All descriptor sets which are going to be updated through the newly 3925 created descriptor update template must: be created with a layout that 3926 matches (is the same as, or defined identically to) this layout. 3927 This parameter is ignored if pname:templateType is not 3928 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET. 3929ifdef::VK_KHR_push_descriptor[] 3930 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 3931 type of the pipeline that will use the descriptors. 3932 This parameter is ignored if pname:templateType is not 3933 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3934 * pname:pipelineLayout is a slink:VkPipelineLayout object used to program 3935 the bindings. 3936 This parameter is ignored if pname:templateType is not 3937 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3938 * pname:set is the set number of the descriptor set in the pipeline layout 3939 that will be updated. 3940 This parameter is ignored if pname:templateType is not 3941 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 3942endif::VK_KHR_push_descriptor[] 3943ifndef::VK_KHR_push_descriptor[] 3944 * pname:pipelineBindPoint is reserved for future use and is ignored 3945 * pname:pipelineLayout is reserved for future use and is ignored 3946 * pname:set is reserved for future use and is ignored 3947endif::VK_KHR_push_descriptor[] 3948 3949.Valid Usage 3950**** 3951 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00350]] 3952 If pname:templateType is 3953 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 3954 pname:descriptorSetLayout must: be a valid sname:VkDescriptorSetLayout 3955 handle 3956ifdef::VK_KHR_push_descriptor[] 3957 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00351]] 3958 If pname:templateType is 3959 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 3960 pname:pipelineBindPoint must: be a valid elink:VkPipelineBindPoint value 3961 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00352]] 3962 If pname:templateType is 3963 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 3964 pname:pipelineLayout must: be a valid sname:VkPipelineLayout handle 3965 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00353]] 3966 If pname:templateType is 3967 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, pname:set 3968 must: be the unique set number in the pipeline layout that uses a 3969 descriptor set layout that was created with 3970 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 3971endif::VK_KHR_push_descriptor[] 3972ifdef::VK_VALVE_mutable_descriptor_type[] 3973 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-04615]] 3974 If pname:templateType is 3975 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 3976 pname:descriptorSetLayout must: not contain a binding with type 3977 ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 3978endif::VK_VALVE_mutable_descriptor_type[] 3979**** 3980 3981 3982include::{generated}/validity/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 3983-- 3984 3985[open,refpage='VkDescriptorUpdateTemplateCreateFlags',desc='Reserved for future use',type='flags'] 3986-- 3987include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlags.txt[] 3988 3989ifdef::VK_KHR_descriptor_update_template[] 3990or the equivalent 3991 3992include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlagsKHR.txt[] 3993endif::VK_KHR_descriptor_update_template[] 3994 3995tname:VkDescriptorUpdateTemplateCreateFlags is a bitmask type for setting a 3996mask, but is currently reserved for future use. 3997-- 3998 3999[open,refpage='VkDescriptorUpdateTemplateType',desc='Indicates the valid usage of the descriptor update template',type='enums'] 4000-- 4001The descriptor update template type is determined by the 4002slink:VkDescriptorUpdateTemplateCreateInfo::pname:templateType property, 4003which takes the following values: 4004 4005include::{generated}/api/enums/VkDescriptorUpdateTemplateType.txt[] 4006 4007ifdef::VK_KHR_descriptor_update_template[] 4008or the equivalent 4009 4010include::{generated}/api/enums/VkDescriptorUpdateTemplateTypeKHR.txt[] 4011endif::VK_KHR_descriptor_update_template[] 4012 4013 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET specifies that 4014 the descriptor update template will be used for descriptor set updates 4015 only. 4016ifdef::VK_KHR_push_descriptor[] 4017 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR specifies 4018 that the descriptor update template will be used for push descriptor 4019 updates only. 4020endif::VK_KHR_push_descriptor[] 4021-- 4022 4023 4024[open,refpage='VkDescriptorUpdateTemplateEntry',desc='Describes a single descriptor update of the descriptor update template',type='structs'] 4025-- 4026The sname:VkDescriptorUpdateTemplateEntry structure is defined as: 4027include::{generated}/api/structs/VkDescriptorUpdateTemplateEntry.txt[] 4028 4029ifdef::VK_KHR_descriptor_update_template[] 4030or the equivalent 4031 4032include::{generated}/api/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] 4033endif::VK_KHR_descriptor_update_template[] 4034 4035 * pname:dstBinding is the descriptor binding to update when using this 4036 descriptor update template. 4037 * pname:dstArrayElement is the starting element in the array belonging to 4038 pname:dstBinding. 4039ifdef::VK_EXT_inline_uniform_block[] 4040 If the descriptor binding identified by pname:dstBinding has a 4041 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4042 then pname:dstArrayElement specifies the starting byte offset to update. 4043endif::VK_EXT_inline_uniform_block[] 4044 * pname:descriptorCount is the number of descriptors to update. 4045 If pname:descriptorCount is greater than the number of remaining array 4046 elements in the destination binding, those affect consecutive bindings 4047 in a manner similar to slink:VkWriteDescriptorSet above. 4048ifdef::VK_EXT_inline_uniform_block[] 4049 If the descriptor binding identified by pname:dstBinding has a 4050 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4051 then pname:descriptorCount specifies the number of bytes to update and 4052 the remaining array elements in the destination binding refer to the 4053 remaining number of bytes in it. 4054endif::VK_EXT_inline_uniform_block[] 4055 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 4056 the descriptor. 4057 * pname:offset is the offset in bytes of the first binding in the raw data 4058 structure. 4059 * pname:stride is the stride in bytes between two consecutive array 4060 elements of the descriptor update informations in the raw data 4061 structure. 4062 The actual pointer ptr for each array element j of update entry i is 4063 computed using the following formula: 4064+ 4065[source,c++] 4066~~~~ 4067 const char *ptr = (const char *)pData + pDescriptorUpdateEntries[i].offset + j * pDescriptorUpdateEntries[i].stride 4068~~~~ 4069+ 4070The stride is useful in case the bindings are stored in structs along with 4071other data. 4072ifdef::VK_EXT_inline_uniform_block[] 4073If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT 4074then the value of pname:stride is ignored and the stride is assumed to be 4075`1`, i.e. the descriptor update information for them is always specified as 4076a contiguous range. 4077endif::VK_EXT_inline_uniform_block[] 4078 4079.Valid Usage 4080**** 4081 * [[VUID-VkDescriptorUpdateTemplateEntry-dstBinding-00354]] 4082 pname:dstBinding must: be a valid binding in the descriptor set layout 4083 implicitly specified when using a descriptor update template to update 4084 descriptors 4085 * [[VUID-VkDescriptorUpdateTemplateEntry-dstArrayElement-00355]] 4086 pname:dstArrayElement and pname:descriptorCount must: be less than or 4087 equal to the number of array elements in the descriptor set binding 4088 implicitly specified when using a descriptor update template to update 4089 descriptors, and all applicable consecutive bindings, as described by 4090 <<descriptorsets-updates-consecutive>> 4091ifdef::VK_EXT_inline_uniform_block[] 4092 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02226]] 4093 If pname:descriptor type is 4094 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:dstArrayElement 4095 must: be an integer multiple of `4` 4096 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02227]] 4097 If pname:descriptor type is 4098 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT, pname:descriptorCount 4099 must: be an integer multiple of `4` 4100endif::VK_EXT_inline_uniform_block[] 4101**** 4102 4103include::{generated}/validity/structs/VkDescriptorUpdateTemplateEntry.txt[] 4104-- 4105 4106[open,refpage='vkDestroyDescriptorUpdateTemplate',desc='Destroy a descriptor update template object',type='protos'] 4107-- 4108To destroy a descriptor update template, call: 4109 4110ifdef::VK_VERSION_1_1[] 4111include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplate.txt[] 4112endif::VK_VERSION_1_1[] 4113 4114ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4115 4116ifdef::VK_KHR_descriptor_update_template[] 4117include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplateKHR.txt[] 4118endif::VK_KHR_descriptor_update_template[] 4119 4120 * pname:device is the logical device that has been used to create the 4121 descriptor update template 4122 * pname:descriptorUpdateTemplate is the descriptor update template to 4123 destroy. 4124 * pname:pAllocator controls host memory allocation as described in the 4125 <<memory-allocation, Memory Allocation>> chapter. 4126 4127.Valid Usage 4128**** 4129 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00356]] 4130 If sname:VkAllocationCallbacks were provided when 4131 pname:descriptorUpdateTemplate was created, a compatible set of 4132 callbacks must: be provided here 4133 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00357]] 4134 If no sname:VkAllocationCallbacks were provided when 4135 pname:descriptorUpdateTemplate was created, pname:pAllocator must: be 4136 `NULL` 4137**** 4138 4139include::{generated}/validity/protos/vkDestroyDescriptorUpdateTemplate.txt[] 4140-- 4141 4142[open,refpage='vkUpdateDescriptorSetWithTemplate',desc='Update the contents of a descriptor set object using an update template',type='protos'] 4143-- 4144Once a sname:VkDescriptorUpdateTemplate has been created, descriptor sets 4145can: be updated by calling: 4146 4147ifdef::VK_VERSION_1_1[] 4148include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplate.txt[] 4149endif::VK_VERSION_1_1[] 4150 4151ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4152 4153ifdef::VK_KHR_descriptor_update_template[] 4154include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplateKHR.txt[] 4155endif::VK_KHR_descriptor_update_template[] 4156 4157 * pname:device is the logical device that updates the descriptor set. 4158 * pname:descriptorSet is the descriptor set to update 4159 * pname:descriptorUpdateTemplate is a slink:VkDescriptorUpdateTemplate 4160 object specifying the update mapping between pname:pData and the 4161 descriptor set to update. 4162 * pname:pData is a pointer to memory containing one or more 4163 slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or 4164 slink:VkBufferView structures 4165ifdef::VK_KHR_acceleration_structure[or slink:VkAccelerationStructureKHR] 4166ifdef::VK_NV_ray_tracing[or slink:VkAccelerationStructureNV] 4167ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[handles] 4168 used to write the descriptors. 4169 4170.Valid Usage 4171**** 4172 * [[VUID-vkUpdateDescriptorSetWithTemplate-pData-01685]] 4173 pname:pData must: be a valid pointer to a memory containing one or more 4174 valid instances of slink:VkDescriptorImageInfo, 4175 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 4176 by pname:descriptorUpdateTemplate when it was created with 4177 flink:vkCreateDescriptorUpdateTemplate 4178**** 4179 4180include::{generated}/validity/protos/vkUpdateDescriptorSetWithTemplate.txt[] 4181 4182.API example 4183[source,c++] 4184~~~~ 4185struct AppBufferView { 4186 VkBufferView bufferView; 4187 uint32_t applicationRelatedInformation; 4188}; 4189 4190struct AppDataStructure 4191{ 4192 VkDescriptorImageInfo imageInfo; // a single image info 4193 VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array 4194 AppBufferView bufferView[2]; // An application defined structure containing a bufferView 4195 // ... some more application related data 4196}; 4197 4198const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 4199{ 4200 // binding to a single image descriptor 4201 { 4202 0, // binding 4203 0, // dstArrayElement 4204 1, // descriptorCount 4205 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 4206 offsetof(AppDataStructure, imageInfo), // offset 4207 0 // stride is not required if descriptorCount is 1 4208 }, 4209 4210 // binding to an array of buffer descriptors 4211 { 4212 1, // binding 4213 0, // dstArrayElement 4214 3, // descriptorCount 4215 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType 4216 offsetof(AppDataStructure, bufferInfoArray), // offset 4217 sizeof(VkDescriptorBufferInfo) // stride, descriptor buffer infos are compact 4218 }, 4219 4220 // binding to an array of buffer views 4221 { 4222 2, // binding 4223 0, // dstArrayElement 4224 2, // descriptorCount 4225 VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, // descriptorType 4226 offsetof(AppDataStructure, bufferView) + 4227 offsetof(AppBufferView, bufferView), // offset 4228 sizeof(AppBufferView) // stride, bufferViews do not have to be compact 4229 }, 4230}; 4231 4232// create a descriptor update template for descriptor set updates 4233const VkDescriptorUpdateTemplateCreateInfo createInfo = 4234{ 4235 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 4236 NULL, // pNext 4237 0, // flags 4238 3, // descriptorUpdateEntryCount 4239 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 4240 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, // templateType 4241 myLayout, // descriptorSetLayout 4242 0, // pipelineBindPoint, ignored by given templateType 4243 0, // pipelineLayout, ignored by given templateType 4244 0, // set, ignored by given templateType 4245}; 4246 4247VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 4248myResult = vkCreateDescriptorUpdateTemplate( 4249 myDevice, 4250 &createInfo, 4251 NULL, 4252 &myDescriptorUpdateTemplate); 4253 4254AppDataStructure appData; 4255 4256// fill appData here or cache it in your engine 4257vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData); 4258~~~~ 4259-- 4260endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4261 4262 4263[[descriptorsets-binding]] 4264=== Descriptor Set Binding 4265 4266[open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] 4267-- 4268To bind one or more descriptor sets to a command buffer, call: 4269 4270include::{generated}/api/protos/vkCmdBindDescriptorSets.txt[] 4271 4272 * pname:commandBuffer is the command buffer that the descriptor sets will 4273 be bound to. 4274 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4275 type of the pipeline that will use the descriptors. 4276 There is a separate set of bind points for each pipeline type, so 4277 binding one does not disturb the others. 4278 * pname:layout is a slink:VkPipelineLayout object used to program the 4279 bindings. 4280 * pname:firstSet is the set number of the first descriptor set to be 4281 bound. 4282 * pname:descriptorSetCount is the number of elements in the 4283 pname:pDescriptorSets array. 4284 * pname:pDescriptorSets is a pointer to an array of handles to 4285 slink:VkDescriptorSet objects describing the descriptor sets to bind to. 4286 * pname:dynamicOffsetCount is the number of dynamic offsets in the 4287 pname:pDynamicOffsets array. 4288 * pname:pDynamicOffsets is a pointer to an array of code:uint32_t values 4289 specifying dynamic offsets. 4290 4291fname:vkCmdBindDescriptorSets causes the sets numbered [pname:firstSet.. 4292pname:firstSet+pname:descriptorSetCount-1] to use the bindings stored in 4293pname:pDescriptorSets[0..descriptorSetCount-1] for subsequent 4294<<pipeline-bindpoint-commands, bound pipeline commands>> set by 4295pname:pipelineBindPoint. 4296Any bindings that were previously applied via these sets are no longer 4297valid. 4298 4299Once bound, a descriptor set affects rendering of subsequent commands that 4300interact with the given pipeline type in the command buffer until either a 4301different set is bound to the same set number, or the set is disturbed as 4302described in <<descriptorsets-compatibility, Pipeline Layout 4303Compatibility>>. 4304 4305A compatible descriptor set must: be bound for all set numbers that any 4306shaders in a pipeline access, at the time that a drawing or dispatching 4307command is recorded to execute using that pipeline. 4308However, if none of the shaders in a pipeline statically use any bindings 4309with a particular set number, then no descriptor set need be bound for that 4310set number, even if the pipeline layout includes a non-trivial descriptor 4311set layout for that set number. 4312 4313[[descriptorsets-binding-dynamicoffsets]] 4314If any of the sets being bound include dynamic uniform or storage buffers, 4315then pname:pDynamicOffsets includes one element for each array element in 4316each dynamic descriptor type binding in each set. 4317Values are taken from pname:pDynamicOffsets in an order such that all 4318entries for set N come before set N+1; within a set, entries are ordered by 4319the binding numbers in the descriptor set layouts; and within a binding 4320array, elements are in order. 4321pname:dynamicOffsetCount must: equal the total number of dynamic descriptors 4322in the sets being bound. 4323 4324The effective offset used for dynamic uniform and storage buffer bindings is 4325the sum of the relative offset taken from pname:pDynamicOffsets, and the 4326base address of the buffer plus base offset in the descriptor set. 4327The range of the dynamic uniform and storage buffer bindings is the buffer 4328range as specified in the descriptor set. 4329 4330Each of the pname:pDescriptorSets must: be compatible with the pipeline 4331layout specified by pname:layout. 4332The layout used to program the bindings must: also be compatible with the 4333pipeline used in subsequent <<pipeline-bindpoint-commands, bound pipeline 4334commands>> with that pipeline type, as defined in the 4335<<descriptorsets-compatibility, Pipeline Layout Compatibility>> section. 4336 4337The descriptor set contents bound by a call to fname:vkCmdBindDescriptorSets 4338may: be consumed at the following times: 4339 4340ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4341 * For descriptor bindings created with the 4342 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set, the contents 4343 may: be consumed when the command buffer is submitted to a queue, or 4344 during shader execution of the resulting draws and dispatches, or any 4345 time in between. 4346 Otherwise, 4347endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4348 * during host execution of the command, or during shader execution of the 4349 resulting draws and dispatches, or any time in between. 4350 4351Thus, the contents of a descriptor set binding must: not be altered 4352(overwritten by an update command, or freed) between the first point in time 4353that it may: be consumed, and when the command completes executing on the 4354queue. 4355 4356The contents of pname:pDynamicOffsets are consumed immediately during 4357execution of fname:vkCmdBindDescriptorSets. 4358Once all pending uses have completed, it is legal to update and reuse a 4359descriptor set. 4360 4361.Valid Usage 4362**** 4363 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-00358]] 4364 Each element of pname:pDescriptorSets must: have been allocated with a 4365 sname:VkDescriptorSetLayout that matches (is the same as, or identically 4366 defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, 4367 where _n_ is the sum of pname:firstSet and the index into 4368 pname:pDescriptorSets 4369 * [[VUID-vkCmdBindDescriptorSets-dynamicOffsetCount-00359]] 4370 pname:dynamicOffsetCount must: be equal to the total number of dynamic 4371 descriptors in pname:pDescriptorSets 4372 * [[VUID-vkCmdBindDescriptorSets-firstSet-00360]] 4373 The sum of pname:firstSet and pname:descriptorSetCount must: be less 4374 than or equal to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount 4375 provided when pname:layout was created 4376 * [[VUID-vkCmdBindDescriptorSets-pipelineBindPoint-00361]] 4377 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 4378 parent sname:VkCommandPool's queue family 4379 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01971]] 4380 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4381 binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: 4382 be a multiple of 4383 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 4384 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01972]] 4385 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4386 binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: 4387 be a multiple of 4388 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 4389 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-01979]] 4390 For each dynamic uniform or storage buffer binding in 4391 pname:pDescriptorSets, the sum of the effective offset, as defined 4392 above, and the range of the binding must: be less than or equal to the 4393 size of the buffer 4394ifdef::VK_VALVE_mutable_descriptor_type[] 4395 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-04616]] 4396 Each element of pname:pDescriptorSets must: not have been allocated from 4397 a sname:VkDescriptorPool with the 4398 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE flag set 4399endif::VK_VALVE_mutable_descriptor_type[] 4400**** 4401 4402include::{generated}/validity/protos/vkCmdBindDescriptorSets.txt[] 4403-- 4404 4405 4406ifdef::VK_KHR_push_descriptor[] 4407[[descriptorsets-push-descriptors]] 4408=== Push Descriptor Updates 4409 4410[open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] 4411-- 4412In addition to allocating descriptor sets and binding them to a command 4413buffer, an application can: record descriptor updates into the command 4414buffer. 4415 4416To push descriptor updates into a command buffer, call: 4417 4418include::{generated}/api/protos/vkCmdPushDescriptorSetKHR.txt[] 4419 4420 * pname:commandBuffer is the command buffer that the descriptors will be 4421 recorded in. 4422 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4423 type of the pipeline that will use the descriptors. 4424 There is a separate set of push descriptor bindings for each pipeline 4425 type, so binding one does not disturb the others. 4426 * pname:layout is a slink:VkPipelineLayout object used to program the 4427 bindings. 4428 * pname:set is the set number of the descriptor set in the pipeline layout 4429 that will be updated. 4430 * pname:descriptorWriteCount is the number of elements in the 4431 pname:pDescriptorWrites array. 4432 * pname:pDescriptorWrites is a pointer to an array of 4433 slink:VkWriteDescriptorSet structures describing the descriptors to be 4434 updated. 4435 4436_Push descriptors_ are a small bank of descriptors whose storage is 4437internally managed by the command buffer rather than being written into a 4438descriptor set and later bound to a command buffer. 4439Push descriptors allow for incremental updates of descriptors without 4440managing the lifetime of descriptor sets. 4441 4442When a command buffer begins recording, all push descriptors are undefined:. 4443Push descriptors can: be updated incrementally and cause shaders to use the 4444updated descriptors for subsequent <<pipeline-bindpoint-commands, bound 4445pipeline commands>> with the pipeline type set by pname:pipelineBindPoint 4446until the descriptor is overwritten, or else until the set is disturbed as 4447described in <<descriptorsets-compatibility, Pipeline Layout 4448Compatibility>>. 4449When the set is disturbed or push descriptors with a different descriptor 4450set layout are set, all push descriptors are undefined:. 4451 4452Push descriptors that are <<shaders-staticuse,statically used>> by a 4453pipeline must: not be undefined: at the time that a drawing or dispatching 4454command is recorded to execute using that pipeline. 4455This includes immutable sampler descriptors, which must: be pushed before 4456they are accessed by a pipeline (the immutable samplers are pushed, rather 4457than the samplers in pname:pDescriptorWrites). 4458Push descriptors that are not statically used can: remain undefined:. 4459 4460Push descriptors do not use dynamic offsets. 4461Instead, the corresponding non-dynamic descriptor types can: be used and the 4462pname:offset member of slink:VkDescriptorBufferInfo can: be changed each 4463time the descriptor is written. 4464 4465Each element of pname:pDescriptorWrites is interpreted as in 4466slink:VkWriteDescriptorSet, except the pname:dstSet member is ignored. 4467 4468To push an immutable sampler, use a slink:VkWriteDescriptorSet with 4469pname:dstBinding and pname:dstArrayElement selecting the immutable sampler's 4470binding. 4471If the descriptor type is ename:VK_DESCRIPTOR_TYPE_SAMPLER, the 4472pname:pImageInfo parameter is ignored and the immutable sampler is taken 4473from the push descriptor set layout in the pipeline layout. 4474If the descriptor type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 4475the pname:sampler member of the pname:pImageInfo parameter is ignored and 4476the immutable sampler is taken from the push descriptor set layout in the 4477pipeline layout. 4478 4479.Valid Usage 4480**** 4481 * [[VUID-vkCmdPushDescriptorSetKHR-pipelineBindPoint-00363]] 4482 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 4483 parent sname:VkCommandPool's queue family 4484 * [[VUID-vkCmdPushDescriptorSetKHR-set-00364]] 4485 pname:set must: be less than 4486 slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 4487 pname:layout was created 4488 * [[VUID-vkCmdPushDescriptorSetKHR-set-00365]] 4489 pname:set must: be the unique set number in the pipeline layout that 4490 uses a descriptor set layout that was created with 4491 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 4492**** 4493 4494include::{generated}/validity/protos/vkCmdPushDescriptorSetKHR.txt[] 4495 4496-- 4497 4498 4499ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4500=== Push Descriptor Updates with Descriptor Update Templates 4501 4502[open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] 4503-- 4504It is also possible to use a descriptor update template to specify the push 4505descriptors to update. 4506To do so, call: 4507 4508include::{generated}/api/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 4509 4510 * pname:commandBuffer is the command buffer that the descriptors will be 4511 recorded in. 4512 * pname:descriptorUpdateTemplate is a descriptor update template defining 4513 how to interpret the descriptor information in pname:pData. 4514 * pname:layout is a slink:VkPipelineLayout object used to program the 4515 bindings. 4516 It must: be compatible with the layout used to create the 4517 pname:descriptorUpdateTemplate handle. 4518 * pname:set is the set number of the descriptor set in the pipeline layout 4519 that will be updated. 4520 This must: be the same number used to create the 4521 pname:descriptorUpdateTemplate handle. 4522 * pname:pData is a pointer to memory containing descriptors for the 4523 templated update. 4524 4525.Valid Usage 4526**** 4527 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366]] 4528 The pname:pipelineBindPoint specified during the creation of the 4529 descriptor update template must: be supported by the 4530 pname:commandBuffer's parent sname:VkCommandPool's queue family 4531 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] 4532 pname:pData must: be a valid pointer to a memory containing one or more 4533 valid instances of slink:VkDescriptorImageInfo, 4534 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 4535 by pname:descriptorUpdateTemplate when it was created with 4536 flink:vkCreateDescriptorUpdateTemplate 4537**** 4538 4539include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 4540 4541.API example 4542[source,c++] 4543~~~~ 4544 4545struct AppDataStructure 4546{ 4547 VkDescriptorImageInfo imageInfo; // a single image info 4548 // ... some more application related data 4549}; 4550 4551const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 4552{ 4553 // binding to a single image descriptor 4554 { 4555 0, // binding 4556 0, // dstArrayElement 4557 1, // descriptorCount 4558 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 4559 offsetof(AppDataStructure, imageInfo), // offset 4560 0 // stride is not required if descriptorCount is 1 4561 } 4562}; 4563 4564// create a descriptor update template for push descriptor set updates 4565const VkDescriptorUpdateTemplateCreateInfo createInfo = 4566{ 4567 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 4568 NULL, // pNext 4569 0, // flags 4570 1, // descriptorUpdateEntryCount 4571 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 4572 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, // templateType 4573 0, // descriptorSetLayout, ignored by given templateType 4574 VK_PIPELINE_BIND_POINT_GRAPHICS, // pipelineBindPoint 4575 myPipelineLayout, // pipelineLayout 4576 0, // set 4577}; 4578 4579VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 4580myResult = vkCreateDescriptorUpdateTemplate( 4581 myDevice, 4582 &createInfo, 4583 NULL, 4584 &myDescriptorUpdateTemplate); 4585 4586AppDataStructure appData; 4587// fill appData here or cache it in your engine 4588vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); 4589~~~~ 4590-- 4591endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4592endif::VK_KHR_push_descriptor[] 4593 4594 4595[[descriptorsets-push-constants]] 4596=== Push Constant Updates 4597 4598As described above in section <<descriptorsets-pipelinelayout, Pipeline 4599Layouts>>, the pipeline layout defines shader push constants which are 4600updated via Vulkan commands rather than via writes to memory or copy 4601commands. 4602 4603[NOTE] 4604.Note 4605==== 4606Push constants represent a high speed path to modify constant data in 4607pipelines that is expected to outperform memory-backed resource updates. 4608==== 4609 4610[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] 4611-- 4612To update push constants, call: 4613 4614include::{generated}/api/protos/vkCmdPushConstants.txt[] 4615 4616 * pname:commandBuffer is the command buffer in which the push constant 4617 update will be recorded. 4618 * pname:layout is the pipeline layout used to program the push constant 4619 updates. 4620 * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying 4621 the shader stages that will use the push constants in the updated range. 4622 * pname:offset is the start offset of the push constant range to update, 4623 in units of bytes. 4624 * pname:size is the size of the push constant range to update, in units of 4625 bytes. 4626 * pname:pValues is a pointer to an array of pname:size bytes containing 4627 the new push constant values. 4628 4629When a command buffer begins recording, all push constant values are 4630undefined:. 4631ifdef::VK_KHR_maintenance4[] 4632Reads of undefined: push constant values by the executing shader return 4633undefined: values. 4634endif::VK_KHR_maintenance4[] 4635 4636Push constant values can: be updated incrementally, causing shader stages in 4637pname:stageFlags to read the new data from pname:pValues for push constants 4638modified by this command, while still reading the previous data for push 4639constants not modified by this command. 4640When a <<pipeline-bindpoint-commands, bound pipeline command>> is issued, 4641the bound pipeline's layout must: be compatible with the layouts used to set 4642the values of all push constants in the pipeline layout's push constant 4643ranges, as described in <<descriptorsets-compatibility,Pipeline Layout 4644Compatibility>>. 4645Binding a pipeline with a layout that is not compatible with the push 4646constant layout does not disturb the push constant values. 4647 4648[NOTE] 4649.Note 4650==== 4651As pname:stageFlags needs to include all flags the relevant push constant 4652ranges were created with, any flags that are not supported by the queue 4653family that the slink:VkCommandPool used to allocate pname:commandBuffer was 4654created on are ignored. 4655==== 4656 4657.Valid Usage 4658**** 4659 * [[VUID-vkCmdPushConstants-offset-01795]] 4660 For each byte in the range specified by pname:offset and pname:size and 4661 for each shader stage in pname:stageFlags, there must: be a push 4662 constant range in pname:layout that includes that byte and that stage 4663 * [[VUID-vkCmdPushConstants-offset-01796]] 4664 For each byte in the range specified by pname:offset and pname:size and 4665 for each push constant range that overlaps that byte, pname:stageFlags 4666 must: include all stages in that push constant range's 4667 slink:VkPushConstantRange::pname:stageFlags 4668 * [[VUID-vkCmdPushConstants-offset-00368]] 4669 pname:offset must: be a multiple of `4` 4670 * [[VUID-vkCmdPushConstants-size-00369]] 4671 pname:size must: be a multiple of `4` 4672 * [[VUID-vkCmdPushConstants-offset-00370]] 4673 pname:offset must: be less than 4674 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 4675 * [[VUID-vkCmdPushConstants-size-00371]] 4676 pname:size must: be less than or equal to 4677 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 4678 pname:offset 4679**** 4680 4681include::{generated}/validity/protos/vkCmdPushConstants.txt[] 4682-- 4683 4684 4685ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 4686[[descriptorsets-physical-storage-buffer]] 4687== Physical Storage Buffer Access 4688 4689[open,refpage='vkGetBufferDeviceAddress',desc='Query an address of a buffer',type='protos',alias='vkGetBufferDeviceAddressKHR'] 4690-- 4691To query a 64-bit buffer device address value through which buffer memory 4692can: be accessed in a shader, call: 4693 4694ifdef::VK_VERSION_1_2[] 4695include::{generated}/api/protos/vkGetBufferDeviceAddress.txt[] 4696endif::VK_VERSION_1_2[] 4697 4698ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 4699 4700ifdef::VK_KHR_buffer_device_address[] 4701include::{generated}/api/protos/vkGetBufferDeviceAddressKHR.txt[] 4702endif::VK_KHR_buffer_device_address[] 4703 4704// @Jon: 3-way conditional logic here is wrong 4705 4706ifdef::VK_EXT_buffer_device_address[] 4707or the equivalent command 4708 4709include::{generated}/api/protos/vkGetBufferDeviceAddressEXT.txt[] 4710endif::VK_EXT_buffer_device_address[] 4711 4712 * pname:device is the logical device that the buffer was created on. 4713 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 4714 specifying the buffer to retrieve an address for. 4715 4716The 64-bit return value is an address of the start of pname:pInfo->buffer. 4717The address range starting at this value and whose size is the size of the 4718buffer can: be used in a shader to access the memory bound to that buffer, 4719using the 4720ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4721`SPV_KHR_physical_storage_buffer` extension 4722ifdef::VK_EXT_buffer_device_address[or the equivalent] 4723endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4724ifdef::VK_EXT_buffer_device_address[] 4725`SPV_EXT_physical_storage_buffer` extension 4726endif::VK_EXT_buffer_device_address[] 4727and the code:PhysicalStorageBuffer storage class. 4728For example, this value can: be stored in a uniform buffer, and the shader 4729can: read the value from the uniform buffer and use it to do a dependent 4730read/write to this buffer. 4731A value of zero is reserved as a "`null`" pointer and must: not be returned 4732as a valid buffer device address. 4733All loads, stores, and atomics in a shader through 4734code:PhysicalStorageBuffer pointers must: access addresses in the address 4735range of some buffer. 4736 4737If the buffer was created with a non-zero value of 4738ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4739slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress 4740ifdef::VK_EXT_buffer_device_address[or] 4741endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4742ifdef::VK_EXT_buffer_device_address[] 4743slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress 4744endif::VK_EXT_buffer_device_address[] 4745the return value will be the same address that was returned at capture time. 4746 4747.Valid Usage 4748**** 4749 * [[VUID-vkGetBufferDeviceAddress-bufferDeviceAddress-03324]] 4750 The <<features-bufferDeviceAddress,bufferDeviceAddress>> or 4751 <<features-bufferDeviceAddressEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddress>> 4752 feature must: be enabled 4753 * [[VUID-vkGetBufferDeviceAddress-device-03325]] 4754 If pname:device was created with multiple physical devices, then the 4755 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 4756 or 4757 <<features-bufferDeviceAddressMultiDeviceEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddressMultiDevice>> 4758 feature must: be enabled 4759**** 4760 4761include::{generated}/validity/protos/vkGetBufferDeviceAddress.txt[] 4762-- 4763 4764[open,refpage='VkBufferDeviceAddressInfo',desc='Structure specifying the buffer to query an address for',type='structs',alias='VkBufferDeviceAddressInfoKHR,VkBufferDeviceAddressInfoEXT'] 4765-- 4766The sname:VkBufferDeviceAddressInfo structure is defined as: 4767 4768include::{generated}/api/structs/VkBufferDeviceAddressInfo.txt[] 4769 4770ifdef::VK_KHR_buffer_device_address[] 4771or the equivalent 4772 4773include::{generated}/api/structs/VkBufferDeviceAddressInfoKHR.txt[] 4774endif::VK_KHR_buffer_device_address[] 4775 4776// @Jon: three-way conditional logic is broken 4777ifdef::VK_EXT_buffer_device_address[] 4778or the equivalent 4779 4780include::{generated}/api/structs/VkBufferDeviceAddressInfoEXT.txt[] 4781endif::VK_EXT_buffer_device_address[] 4782 4783 * pname:sType is the type of this structure. 4784 * pname:pNext is `NULL` or a pointer to a structure extending this 4785 structure. 4786 * pname:buffer specifies the buffer whose address is being queried. 4787 4788.Valid Usage 4789**** 4790 * [[VUID-VkBufferDeviceAddressInfo-buffer-02600]] 4791 If pname:buffer is non-sparse and was not created with the 4792 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag, then it 4793 must: be bound completely and contiguously to a single 4794 sname:VkDeviceMemory object 4795 * [[VUID-VkBufferDeviceAddressInfo-buffer-02601]] 4796 pname:buffer must: have been created with 4797 ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT 4798**** 4799 4800include::{generated}/validity/structs/VkBufferDeviceAddressInfo.txt[] 4801-- 4802endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 4803 4804ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4805[open,refpage='vkGetBufferOpaqueCaptureAddress',desc='Query an opaque capture address of a buffer',type='protos',alias='vkGetBufferOpaqueCaptureAddressKHR'] 4806-- 4807To query a 64-bit buffer opaque capture address, call: 4808 4809ifdef::VK_VERSION_1_2[] 4810include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddress.txt[] 4811endif::VK_VERSION_1_2[] 4812 4813ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 4814 4815ifdef::VK_KHR_buffer_device_address[] 4816include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddressKHR.txt[] 4817endif::VK_KHR_buffer_device_address[] 4818 4819 * pname:device is the logical device that the buffer was created on. 4820 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 4821 specifying the buffer to retrieve an address for. 4822 4823The 64-bit return value is an opaque capture address of the start of 4824pname:pInfo->buffer. 4825 4826If the buffer was created with a non-zero value of 4827slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress the 4828return value must: be the same address. 4829 4830.Valid Usage 4831**** 4832 * [[VUID-vkGetBufferOpaqueCaptureAddress-None-03326]] 4833 The <<features-bufferDeviceAddress,bufferDeviceAddress>> feature must: 4834 be enabled 4835 * [[VUID-vkGetBufferOpaqueCaptureAddress-device-03327]] 4836 If pname:device was created with multiple physical devices, then the 4837 <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> 4838 feature must: be enabled 4839**** 4840 4841include::{generated}/validity/protos/vkGetBufferOpaqueCaptureAddress.txt[] 4842-- 4843endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 4844