1// Copyright 2015-2023 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 organized 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 21ifdef::VK_EXT_descriptor_buffer[] 22If the <<features-descriptorBuffer, pname:descriptorBuffer>> feature is 23enabled, the implementation supports placing descriptors into 24<<descriptorbuffers,descriptor buffers>> which are bound during command 25recording in a similar way to descriptor sets. 26endif::VK_EXT_descriptor_buffer[] 27 28Shaders access resources via variables decorated with a descriptor set and 29binding number that link them to a descriptor in a descriptor set. 30The shader interface mapping to bound descriptor sets is described in the 31<<interfaces-resources, Shader Resource Interface>> section. 32 33ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 34Shaders can: also access buffers without going through descriptors by using 35<<descriptorsets-physical-storage-buffer,Physical Storage Buffer Access>> to 36access them through 64-bit addresses. 37endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 38 39 40[[descriptorsets-types]] 41== Descriptor Types 42 43There are a number of different types of descriptor supported by Vulkan, 44corresponding to different resources or usage. 45The following sections describe the API definitions of each descriptor type. 46The mapping of each type to SPIR-V is listed in the 47<<interfaces-resources-correspondence, Shader Resource and Descriptor Type 48Correspondence>> and <<interfaces-resources-storage-class-correspondence, 49Shader Resource and Storage Class Correspondence>> tables in the 50<<interfaces, Shader Interfaces>> chapter. 51 52 53[[descriptorsets-storageimage]] 54=== Storage Image 55 56A _storage image_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE) is a descriptor 57type associated with an <<resources-images, image resource>> via an 58<<resources-image-views, image view>> that load, store, and atomic 59operations can: be performed on. 60 61Storage image loads are supported in all shader stages for image views whose 62<<resources-image-view-format-features,format features>> contain 63<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 64 65Stores to storage images are supported in 66ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] 67compute shaders for image views whose 68<<resources-image-view-format-features,format features>> contain 69<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 70 71Atomic operations on storage images are supported in 72ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] 73compute shaders for image views whose 74<<resources-image-view-format-features,format features>> contain 75<<formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT>>. 76 77When the <<features-fragmentStoresAndAtomics, 78pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 79operations are also supported for storage images in fragment shaders with 80the same set of image formats as supported in compute shaders. 81When the <<features-vertexPipelineStoresAndAtomics, 82pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 83operations are also supported in vertex, tessellation, and geometry shaders 84with the same set of image formats as supported in compute shaders. 85 86The image subresources for a storage image must: be in the 87ifdef::VK_KHR_shared_presentable_image[] 88ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 89endif::VK_KHR_shared_presentable_image[] 90ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 91shader. 92 93 94[[descriptorsets-sampler]] 95=== Sampler 96 97A _sampler descriptor_ (ename:VK_DESCRIPTOR_TYPE_SAMPLER) is a descriptor 98type associated with a <<samplers,sampler>> object, used to control the 99behavior of <<textures,sampling operations>> performed on a 100<<descriptorsets-sampledimage, sampled image>>. 101 102 103[[descriptorsets-sampledimage]] 104=== Sampled Image 105 106A _sampled image_ (ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE) is a descriptor 107type associated with an <<resources-images, image resource>> via an 108<<resources-image-views, image view>> that <<textures,sampling operations>> 109can: be performed on. 110 111Shaders combine a sampled image variable and a sampler variable to perform 112sampling operations. 113 114Sampled images are supported in all shader stages for image views whose 115<<resources-image-view-format-features,format features>> contain 116<<formats-properties,ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT>>. 117 118An image subresources for a sampled image must: be in one of the following 119layouts: 120 121 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 122 * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 123 * ename:VK_IMAGE_LAYOUT_GENERAL 124ifdef::VK_KHR_shared_presentable_image[] 125 * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 126endif::VK_KHR_shared_presentable_image[] 127ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 128 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 129 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 130endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 131ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 132 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 133 * ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 134endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 135ifdef::VK_KHR_synchronization2[] 136 * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR 137endif::VK_KHR_synchronization2[] 138ifdef::VK_EXT_attachment_feedback_loop_layout[] 139 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT 140endif::VK_EXT_attachment_feedback_loop_layout[] 141 142 143[[descriptorsets-combinedimagesampler]] 144=== Combined Image Sampler 145 146A _combined image sampler_ (ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER) 147is a single descriptor type associated with both a <<samplers,sampler>> and 148an <<resources-images,image resource>>, combining both a 149<<descriptorsets-sampler,sampler>> and <<descriptorsets-sampledimage, 150sampled image>> descriptor into a single descriptor. 151 152ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 153If the descriptor refers to a sampler that performs 154ifndef::VK_EXT_fragment_density_map[] 155<<samplers-YCbCr-conversion,{YCbCr} conversion>>, 156endif::VK_EXT_fragment_density_map[] 157ifdef::VK_EXT_fragment_density_map[] 158<<samplers-YCbCr-conversion,{YCbCr} conversion>> or samples a 159<<samplers-subsamplesampler,subsampled image>>, 160endif::VK_EXT_fragment_density_map[] 161the sampler must: only be used to sample the image in the same descriptor. 162Otherwise, the 163endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 164ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 165ifndef::VK_EXT_fragment_density_map[] 166The 167endif::VK_EXT_fragment_density_map[] 168ifdef::VK_EXT_fragment_density_map[] 169If the descriptor refers to a sampler that samples a 170<<samplers-subsamplesampler,subsampled image>>, the sampler must: only be 171used to sample the image in the same descriptor. 172Otherwise, the 173endif::VK_EXT_fragment_density_map[] 174endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 175sampler and image in this type of descriptor can: be used freely with any 176other samplers and images. 177 178An image subresources for a combined image sampler must: be in one of the 179following layouts: 180 181 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 182 * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 183 * ename:VK_IMAGE_LAYOUT_GENERAL 184ifdef::VK_KHR_shared_presentable_image[] 185 * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 186endif::VK_KHR_shared_presentable_image[] 187ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 188 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 189 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 190endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 191ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 192 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL 193 * ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL 194endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] 195ifdef::VK_KHR_synchronization2[] 196 * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR 197endif::VK_KHR_synchronization2[] 198ifdef::VK_EXT_attachment_feedback_loop_layout[] 199 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT 200endif::VK_EXT_attachment_feedback_loop_layout[] 201 202 203[NOTE] 204.Note 205==== 206On some implementations, it may: be more efficient to sample from an image 207using a combination of sampler and sampled image that are stored together in 208the descriptor set in a combined descriptor. 209==== 210 211 212[[descriptorsets-uniformtexelbuffer]] 213=== Uniform Texel Buffer 214 215A _uniform texel buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER) is 216a descriptor type associated with a <<resources-buffers,buffer resource>> 217via a <<resources-buffer-views, buffer view>> that <<textures,image sampling 218operations>> can: be performed on. 219 220Uniform texel buffers define a tightly-packed 1-dimensional linear array of 221texels, with texels going through format conversion when read in a shader in 222the same way as they are for an image. 223 224Load operations from uniform texel buffers are supported in all shader 225stages for buffer view formats which report 226<<resources-buffer-view-format-features,format features>> support for 227ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT 228 229 230[[descriptorsets-storagetexelbuffer]] 231=== Storage Texel Buffer 232 233A _storage texel buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER) is 234a descriptor type associated with a <<resources-buffers,buffer resource>> 235via a <<resources-buffer-views, buffer view>> that <<textures,image load, 236store, and atomic operations>> can: be performed on. 237 238Storage texel buffers define a tightly-packed 1-dimensional linear array of 239texels, with texels going through format conversion when read in a shader in 240the same way as they are for an image. 241Unlike <<descriptorsets-uniformtexelbuffer,uniform texel buffers>>, these 242buffers can also be written to in the same way as for 243<<descriptorsets-storageimage, storage images>>. 244 245Storage texel buffer loads are supported in all shader stages for texel 246buffer view formats which report 247<<resources-buffer-view-format-features,format features>> support for 248ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT 249 250Stores to storage texel buffers are supported in 251ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] 252compute shaders for texel buffer formats which report 253<<resources-buffer-view-format-features,format features>> support for 254ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT 255 256Atomic operations on storage texel buffers are supported in 257ifdef::VK_NV_mesh_shader,VK_EXT_mesh_shader[task, mesh and] 258compute shaders for texel buffer formats which report 259<<resources-buffer-view-format-features,format features>> support for 260ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT 261 262When the <<features-fragmentStoresAndAtomics, 263pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 264operations are also supported for storage texel buffers in fragment shaders 265with the same set of texel buffer formats as supported in compute shaders. 266When the <<features-vertexPipelineStoresAndAtomics, 267pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 268operations are also supported in vertex, tessellation, and geometry shaders 269with the same set of texel buffer formats as supported in compute shaders. 270 271 272[[descriptorsets-storagebuffer]] 273=== Storage Buffer 274 275A _storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER) is a descriptor 276type associated with a <<resources-buffers,buffer resource>> directly, 277described in a shader as a structure with various members that load, store, 278and atomic operations can: be performed on. 279 280[NOTE] 281.Note 282==== 283Atomic operations can: only be performed on members of certain types as 284defined in the <<spirvenv, SPIR-V environment appendix>>. 285==== 286 287 288[[descriptorsets-uniformbuffer]] 289=== Uniform Buffer 290 291A _uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER) is a descriptor 292type associated with a <<resources-buffers,buffer resource>> directly, 293described in a shader as a structure with various members that load 294operations can: be performed on. 295 296 297[[descriptorsets-uniformbufferdynamic]] 298=== Dynamic Uniform Buffer 299 300A _dynamic uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC) 301is almost identical to a <<descriptorsets-uniformbuffer, uniform buffer>>, 302and differs only in how the offset into the buffer is specified. 303The base offset calculated by the slink:VkDescriptorBufferInfo when 304initially <<descriptorsets-updates, updating the descriptor set>> is added 305to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 306the descriptor set. 307 308 309[[descriptorsets-storagebufferdynamic]] 310=== Dynamic Storage Buffer 311 312A _dynamic storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC) 313is almost identical to a <<descriptorsets-storagebuffer, storage buffer>>, 314and differs only in how the offset into the buffer is specified. 315The base offset calculated by the slink:VkDescriptorBufferInfo when 316initially <<descriptorsets-updates, updating the descriptor set>> is added 317to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 318the descriptor set. 319 320 321ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 322[[descriptorsets-inlineuniformblock]] 323=== Inline Uniform Block 324 325An _inline uniform block_ (ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK) is 326almost identical to a <<descriptorsets-uniformbuffer, uniform buffer>>, and 327differs only in taking its storage directly from the encompassing descriptor 328set instead of being backed by buffer memory. 329It is typically used to access a small set of constant data that does not 330require the additional flexibility provided by the indirection enabled when 331using a uniform buffer where the descriptor and the referenced buffer memory 332are decoupled. 333Compared to push constants, they allow reusing the same set of constant data 334across multiple disjoint sets of drawing and dispatching commands. 335 336Inline uniform block descriptors cannot: be aggregated into arrays. 337Instead, the array size specified for an inline uniform block descriptor 338binding specifies the binding's capacity in bytes. 339 340endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 341 342 343ifdef::VK_QCOM_image_processing[] 344[[descriptorsets-weightimage]] 345=== Sample Weight Image 346 347A _sample weight image_ (ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM) 348is a descriptor type associated with an <<resources-images, image resource>> 349via an <<resources-image-views, image view>> that can: be used in 350<<textures-weightimage, weight image sampling>>. 351The image view must have been created with 352slink:VkImageViewSampleWeightCreateInfoQCOM. 353 354Shaders can: combine a weight image variable, a sampled image variable, and 355a sampler variable to perform <<textures-weightimage, weight image 356sampling>>. 357 358Weight image sampling is supported in all shader stages if the weight image 359view specifies a format that supports 360<<resources-image-view-format-features,format feature>> 361<<formats-properties,ename:VK_FORMAT_FEATURE_2_WEIGHT_IMAGE_BIT_QCOM>> and 362the sampled image view specifies a format that supports 363<<resources-image-view-format-features,format feature>> 364<<formats-properties,ename:VK_FORMAT_FEATURE_2_WEIGHT_SAMPLED_IMAGE_BIT_QCOM>> 365 366The image subresources for the weight image must: be in the 367ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 368ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 369shader. 370 371 372[[descriptorsets-blockmatch]] 373=== Block Matching Image 374 375A _block matching image_ (ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM) 376is a descriptor type associated with an <<resources-images, image resource>> 377via an <<resources-image-views, image view>> that can: be used in 378<<textures-blockmatch, block matching>>. 379 380Shaders can: combine a target image variable, a reference image variable, 381and a sampler variable to perform <<textures-blockmatch, block matching>>. 382 383Block matching is supported in all shader stages for if both the target view 384and reference view specifies a format that supports 385<<resources-image-view-format-features,format feature>> 386<<formats-properties,ename:VK_FORMAT_FEATURE_2_BLOCK_MATCHING_BIT_QCOM>> 387 388 389The image subresources for block matching must: be in the 390ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 391ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 392shader. 393endif::VK_QCOM_image_processing[] 394 395 396[[descriptorsets-inputattachment]] 397=== Input Attachment 398 399An _input attachment_ (ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT) is a 400descriptor type associated with an <<resources-images, image resource>> via 401an <<resources-image-views, image view>> that can: be used for 402<<synchronization-framebuffer-regions,framebuffer local>> load operations in 403fragment shaders. 404 405All image formats that are supported for color attachments 406(ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT 407ifdef::VK_NV_linear_color_attachment[] 408or ename:VK_FORMAT_FEATURE_2_LINEAR_COLOR_ATTACHMENT_BIT_NV 409endif::VK_NV_linear_color_attachment[] 410) or depth/stencil attachments 411(ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT) for a given image 412tiling mode are also supported for input attachments. 413 414An image view used as an input attachment must: be in one of the following 415layouts: 416 417 * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL 418 * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL 419 * ename:VK_IMAGE_LAYOUT_GENERAL 420ifdef::VK_KHR_shared_presentable_image[] 421 * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 422endif::VK_KHR_shared_presentable_image[] 423ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 424 * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL 425 * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL 426endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 427ifdef::VK_KHR_synchronization2[] 428 * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR 429endif::VK_KHR_synchronization2[] 430ifdef::VK_EXT_attachment_feedback_loop_layout[] 431 * ename:VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT 432endif::VK_EXT_attachment_feedback_loop_layout[] 433 434 435ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 436[[descriptorsets-accelerationstructure]] 437=== Acceleration Structure 438 439An _acceleration structure_ ( 440ifdef::VK_KHR_acceleration_structure[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR] 441ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] 442ifdef::VK_NV_ray_tracing[ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV] 443) is a descriptor type that is used to retrieve scene geometry from within 444shaders that are used for ray traversal. 445Shaders have read-only access to the memory. 446endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 447 448 449ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 450[[descriptorsets-mutable]] 451=== Mutable 452 453A descriptor of _mutable_ (ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT) type 454indicates that this descriptor can: mutate to any of the descriptor types 455given in the 456slink:VkMutableDescriptorTypeCreateInfoEXT::pname:pDescriptorTypes list of 457descriptor types in the pname:pNext chain of 458slink:VkDescriptorSetLayoutCreateInfo for this binding. 459At any point, each individual descriptor of mutable type has an active 460descriptor type. 461The active descriptor type can: be any one of the declared types in 462pname:pDescriptorTypes. 463Additionally, a mutable descriptor's active descriptor type can: be of the 464ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT type, which is the initial active 465descriptor type. 466The active descriptor type can: change when the descriptor is updated. 467When a descriptor is consumed by binding a descriptor set, the active 468descriptor type is considered, not ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT. 469 470An active descriptor type of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT is 471considered an undefined: descriptor. 472If a descriptor is consumed where the active descriptor type does not match 473what the shader expects, the descriptor is considered an undefined: 474descriptor. 475 476[NOTE] 477.Note 478==== 479To find which descriptor types are supported as 480ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the application can: use 481flink:vkGetDescriptorSetLayoutSupport with an 482ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT binding, with the list of descriptor 483types to query in the 484slink:VkMutableDescriptorTypeCreateInfoEXT::pname:pDescriptorTypes array for 485that binding. 486==== 487 488[NOTE] 489.Note 490==== 491The intention of a mutable descriptor type is that implementations allocate 492N bytes per descriptor, where N is determined by the maximum descriptor size 493for a given descriptor binding. 494Implementations are not expected to keep track of the active descriptor 495type, and it should be considered a C-like union type. 496 497A mutable descriptor type is not considered as efficient in terms of runtime 498performance as using a non-mutable descriptor type, and applications are not 499encouraged to use them outside API layering efforts. 500Mutable descriptor types can be more efficient if the alternative is using 501many different descriptors to emulate mutable descriptor types. 502==== 503endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 504 505 506[[descriptorsets-sets]] 507== Descriptor Sets 508 509Descriptors are grouped together into descriptor set objects. 510A descriptor set object is an opaque object containing storage for a set of 511descriptors, where the types and number of descriptors is defined by a 512descriptor set layout. 513The layout object may: be used to define the association of each descriptor 514binding with memory or other implementation resources. 515The layout is used both for determining the resources that need to be 516associated with the descriptor set, and determining the interface between 517shader stages and shader resources. 518 519 520[[descriptorsets-setlayout]] 521=== Descriptor Set Layout 522 523[open,refpage='VkDescriptorSetLayout',desc='Opaque handle to a descriptor set layout object',type='handles'] 524-- 525A descriptor set layout object is defined by an array of zero or more 526descriptor bindings. 527Each individual descriptor binding is specified by a descriptor type, a 528count (array size) of the number of descriptors in the binding, a set of 529shader stages that can: access the binding, and (if using immutable 530samplers) an array of sampler descriptors. 531 532Descriptor set layout objects are represented by sname:VkDescriptorSetLayout 533handles: 534 535include::{generated}/api/handles/VkDescriptorSetLayout.adoc[] 536-- 537 538[open,refpage='vkCreateDescriptorSetLayout',desc='Create a new descriptor set layout',type='protos'] 539-- 540:refpage: vkCreateDescriptorSetLayout 541:objectnameplural: descriptor set layouts 542:objectnamecamelcase: descriptorSetLayout 543:objectcount: 1 544 545To create descriptor set layout objects, call: 546 547include::{generated}/api/protos/vkCreateDescriptorSetLayout.adoc[] 548 549 * pname:device is the logical device that creates the descriptor set 550 layout. 551 * pname:pCreateInfo is a pointer to a 552 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 553 the descriptor set layout object. 554 * pname:pAllocator controls host memory allocation as described in the 555 <<memory-allocation, Memory Allocation>> chapter. 556 * pname:pSetLayout is a pointer to a slink:VkDescriptorSetLayout handle in 557 which the resulting descriptor set layout object is returned. 558 559include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 560 561ifdef::VKSC_VERSION_1_0[] 562.Valid Usage 563**** 564include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 565 566:uniqifier: layoutbindings 567:combinedobjectnameplural: descriptor set layout bindings 568:combinedparentobject: VkDescriptorSetLayout 569:combinedobjectcount: pname:pCreateInfo->bindingCount 570:combinedobjectnamecamelcase: descriptorSetLayoutBinding 571include::{chapters}/commonvalidity/memory_reservation_request_count_combined_common.adoc[] 572**** 573endif::VKSC_VERSION_1_0[] 574 575include::{generated}/validity/protos/vkCreateDescriptorSetLayout.adoc[] 576-- 577 578[open,refpage='VkDescriptorSetLayoutCreateInfo',desc='Structure specifying parameters of a newly created descriptor set layout',type='structs'] 579-- 580Information about the descriptor set layout is passed in a 581sname:VkDescriptorSetLayoutCreateInfo structure: 582 583include::{generated}/api/structs/VkDescriptorSetLayoutCreateInfo.adoc[] 584 585 * pname:sType is a elink:VkStructureType value identifying this structure. 586 * pname:pNext is `NULL` or a pointer to a structure extending this 587 structure. 588 * pname:flags is a bitmask 589ifdef::VK_KHR_push_descriptor[] 590 of elink:VkDescriptorSetLayoutCreateFlagBits 591endif::VK_KHR_push_descriptor[] 592 specifying options for descriptor set layout creation. 593 * pname:bindingCount is the number of elements in pname:pBindings. 594 * pname:pBindings is a pointer to an array of 595 slink:VkDescriptorSetLayoutBinding structures. 596 597.Valid Usage 598**** 599 * [[VUID-VkDescriptorSetLayoutCreateInfo-binding-00279]] 600 The slink:VkDescriptorSetLayoutBinding::pname:binding members of the 601 elements of the pname:pBindings array must: each have different values 602ifdef::VK_KHR_push_descriptor[] 603 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00280]] 604 If pname:flags contains 605 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 606 elements of pname:pBindings must: not have a pname:descriptorType of 607 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 608 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 609ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 610 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-02208]] 611 If pname:flags contains 612 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 613 elements of pname:pBindings must: not have a pname:descriptorType of 614 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 615endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 616 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00281]] 617 If pname:flags contains 618 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then the 619 total number of elements of all bindings must: be less than or equal to 620 slink:VkPhysicalDevicePushDescriptorPropertiesKHR::pname:maxPushDescriptors 621ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 622 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04590]] 623 If pname:flags contains 624 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, 625 pname:flags must: not contain 626 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT 627 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04591]] 628 If pname:flags contains 629 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, 630 pname:pBindings must: not have a pname:descriptorType of 631 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 632endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 633endif::VK_KHR_push_descriptor[] 634ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 635 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-03000]] 636 If any binding has the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 637 bit set, pname:flags must: include 638 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 639 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-03001]] 640 If any binding has the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 641 bit set, then all bindings must: not have pname:descriptorType of 642 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 643 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 644ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 645 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04592]] 646 If pname:flags contains 647 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT, 648 pname:flags must: not contain 649 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT 650endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 651endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 652ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 653 * [[VUID-VkDescriptorSetLayoutCreateInfo-pBindings-07303]] 654 If any element pname:pBindings[i] has a pname:descriptorType of 655 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, then a 656 slink:VkMutableDescriptorTypeCreateInfoEXT must: be present in the 657 pname:pNext chain, and pname:mutableDescriptorTypeListCount must: be 658 greater than i 659 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-04594]] 660 If a binding has a pname:descriptorType value of 661 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, then sname:pImmutableSamplers 662 must: be `NULL` 663 * [[VUID-VkDescriptorSetLayoutCreateInfo-mutableDescriptorType-04595]] 664 If 665 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT::pname:mutableDescriptorType 666 is not enabled, pname:pBindings must: not contain a pname:descriptorType 667 of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 668 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-04596]] 669 If pname:flags contains 670 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT, 671 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT::pname:mutableDescriptorType 672 must: be enabled 673endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 674ifdef::VKSC_VERSION_1_0[] 675 * [[VUID-VkDescriptorSetLayoutCreateInfo-bindingCount-05011]] 676 pname:bindingCount must: be less than or equal to 677 <<limits-maxDescriptorSetLayoutBindings,maxDescriptorSetLayoutBindings>> 678 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorCount-05071]] 679 The sum of pname:descriptorCount over all bindings in pname:pBindings 680 that have pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER or 681 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER and 682 sname:pImmutableSamplers not equal to `NULL` must: be less than or equal 683 to 684 slink:VkDeviceObjectReservationCreateInfo::pname:maxImmutableSamplersPerDescriptorSetLayout 685endif::VKSC_VERSION_1_0[] 686ifdef::VK_EXT_descriptor_buffer[] 687 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-08000]] 688 If pname:flags contains 689 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, then 690 all elements of pname:pBindings must: not have a pname:descriptorType of 691 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 692 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 693 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-08001]] 694 If pname:flags contains 695 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, 696 pname:flags must: also contain 697 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT 698ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 699 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-08002]] 700 If pname:flags contains 701 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, then 702 pname:flags must: not contain 703 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 704endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 705ifdef::VK_VALVE_mutable_descriptor_type[] 706 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-08003]] 707 If pname:flags contains 708 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT, then 709 pname:flags must: not contain 710 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE 711endif::VK_VALVE_mutable_descriptor_type[] 712endif::VK_EXT_descriptor_buffer[] 713**** 714 715include::{generated}/validity/structs/VkDescriptorSetLayoutCreateInfo.adoc[] 716-- 717 718ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 719[open,refpage='VkMutableDescriptorTypeCreateInfoEXT',desc='Structure describing the list of possible active descriptor types for mutable type descriptors',type='structs',alias='VkMutableDescriptorTypeCreateInfoVALVE'] 720-- 721If the pname:pNext chain of a slink:VkDescriptorSetLayoutCreateInfo or 722slink:VkDescriptorPoolCreateInfo structure includes a 723slink:VkMutableDescriptorTypeCreateInfoEXT structure, then that structure 724specifies Information about the possible descriptor types for mutable 725descriptor types. 726 727The sname:VkMutableDescriptorTypeCreateInfoEXT structure is defined as: 728 729include::{generated}/api/structs/VkMutableDescriptorTypeCreateInfoEXT.adoc[] 730 731ifdef::VK_VALVE_mutable_descriptor_type[] 732or the equivalent 733 734include::{generated}/api/structs/VkMutableDescriptorTypeCreateInfoVALVE.adoc[] 735endif::VK_VALVE_mutable_descriptor_type[] 736 737 * pname:sType is a elink:VkStructureType value identifying this structure. 738 * pname:pNext is `NULL` or a pointer to a structure extending this 739 structure. 740 * pname:mutableDescriptorTypeListCount is the number of elements in 741 pname:pMutableDescriptorTypeLists. 742 * pname:pMutableDescriptorTypeLists is a pointer to an array of 743 sname:VkMutableDescriptorTypeListEXT structures. 744 745If pname:mutableDescriptorTypeListCount is zero or if this structure is not 746included in the pname:pNext chain, the slink:VkMutableDescriptorTypeListEXT 747for each element is considered to be zero or `NULL` for each member. 748Otherwise, the descriptor set layout binding at 749slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings[i] uses the 750descriptor type lists in 751slink:VkMutableDescriptorTypeCreateInfoEXT::pname:pMutableDescriptorTypeLists[i]. 752 753include::{generated}/validity/structs/VkMutableDescriptorTypeCreateInfoEXT.adoc[] 754-- 755 756[open,refpage='VkMutableDescriptorTypeListEXT',desc='Structure describing descriptor types that a given descriptor may mutate to',type='structs',alias='VkMutableDescriptorTypeListVALVE'] 757-- 758The list of potential descriptor types a given mutable descriptor can: 759mutate to is passed in a sname:VkMutableDescriptorTypeListEXT structure. 760 761The sname:VkMutableDescriptorTypeListEXT structure is defined as: 762 763include::{generated}/api/structs/VkMutableDescriptorTypeListEXT.adoc[] 764 765ifdef::VK_VALVE_mutable_descriptor_type[] 766or the equivalent 767 768include::{generated}/api/structs/VkMutableDescriptorTypeListVALVE.adoc[] 769endif::VK_VALVE_mutable_descriptor_type[] 770 771 * pname:descriptorTypeCount is the number of elements in 772 pname:pDescriptorTypes. 773 * pname:pDescriptorTypes is `NULL` or a pointer to an array of 774 pname:descriptorTypeCount elink:VkDescriptorType values defining which 775 descriptor types a given binding may mutate to. 776 777.Valid Usage 778**** 779 * [[VUID-VkMutableDescriptorTypeListEXT-descriptorTypeCount-04597]] 780 pname:descriptorTypeCount must: not be `0` if the corresponding binding 781 is of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 782 * [[VUID-VkMutableDescriptorTypeListEXT-pDescriptorTypes-04598]] 783 pname:pDescriptorTypes must: be a valid pointer to an array of 784 pname:descriptorTypeCount valid, unique elink:VkDescriptorType values if 785 the given binding is of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT type 786 * [[VUID-VkMutableDescriptorTypeListEXT-descriptorTypeCount-04599]] 787 pname:descriptorTypeCount must: be `0` if the corresponding binding is 788 not of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 789 * [[VUID-VkMutableDescriptorTypeListEXT-pDescriptorTypes-04600]] 790 pname:pDescriptorTypes must: not contain 791 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 792 * [[VUID-VkMutableDescriptorTypeListEXT-pDescriptorTypes-04601]] 793 pname:pDescriptorTypes must: not contain 794 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 795 * [[VUID-VkMutableDescriptorTypeListEXT-pDescriptorTypes-04602]] 796 pname:pDescriptorTypes must: not contain 797 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC 798ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 799 * [[VUID-VkMutableDescriptorTypeListEXT-pDescriptorTypes-04603]] 800 pname:pDescriptorTypes must: not contain 801 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 802endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 803**** 804 805include::{generated}/validity/structs/VkMutableDescriptorTypeListEXT.adoc[] 806-- 807endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 808 809[open,refpage='VkDescriptorSetLayoutCreateFlagBits',desc='Bitmask specifying descriptor set layout properties',type='enums'] 810-- 811Bits which can: be set in 812slink:VkDescriptorSetLayoutCreateInfo::pname:flags, specifying options for 813descriptor set layout, are: 814 815include::{generated}/api/enums/VkDescriptorSetLayoutCreateFlagBits.adoc[] 816 817ifdef::VK_KHR_push_descriptor[] 818 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies 819 that descriptor sets must: not be allocated using this layout, and 820 descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. 821endif::VK_KHR_push_descriptor[] 822ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 823// Jon: "UpdateAfterBind" is a vague reference, should be more precise / 824// link to the right specification area 825 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 826 specifies that descriptor sets using this layout must: be allocated from 827 a descriptor pool created with the 828 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT bit set. 829 Descriptor set layouts created with this bit set have alternate limits 830 for the maximum number of descriptors per-stage and per-pipeline layout. 831 The non-UpdateAfterBind limits only count descriptors in sets created 832 without this flag. 833 The UpdateAfterBind limits count all descriptors, but the limits may: be 834 higher than the non-UpdateAfterBind limits. 835endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 836ifdef::VK_NV_device_generated_commands_compute[] 837 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_INDIRECT_BINDABLE_BIT_NV specifies 838 that descriptor sets using this layout allows them to be bound with 839 compute pipelines that are created with 840 ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV flag set to be used in 841 <<device-generated-commands,Device-Generated Commands>>. 842endif::VK_NV_device_generated_commands_compute[] 843ifdef::VK_EXT_descriptor_buffer[] 844 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT 845 specifies that this layout must: only be used with descriptor buffers. 846 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT 847 specifies that this is a layout only containing immutable samplers that 848 can: be bound by flink:vkCmdBindDescriptorBufferEmbeddedSamplersEXT. 849 Unlike normal immutable samplers, embedded immutable samplers do not 850 require the application to provide them in a descriptor buffer. 851endif::VK_EXT_descriptor_buffer[] 852ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 853 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT specifies 854 that descriptor sets using this layout must: be allocated from a 855 descriptor pool created with the 856 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT bit set. 857 Descriptor set layouts created with this bit have no expressible limit 858 for maximum number of descriptors per-stage. 859 Host descriptor sets are limited only by available host memory, but may: 860 be limited for implementation specific reasons. 861ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 862 Implementations may: limit the number of supported descriptors to 863 UpdateAfterBind limits or non-UpdateAfterBind limits, whichever is 864 larger. 865endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 866ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 867 Implementations may: limit the number of supported descriptors to 868 non-UpdateAfterBind limits. 869endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 870endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 871 872ifndef::VK_KHR_push_descriptor[] 873[NOTE] 874.Note 875==== 876All bits for this type are defined by extensions, and none of those 877extensions are enabled in this build of the specification. 878==== 879endif::VK_KHR_push_descriptor[] 880-- 881 882[open,refpage='VkDescriptorSetLayoutCreateFlags',desc='Bitmask of VkDescriptorSetLayoutCreateFlagBits',type='flags'] 883-- 884include::{generated}/api/flags/VkDescriptorSetLayoutCreateFlags.adoc[] 885 886tname:VkDescriptorSetLayoutCreateFlags is a bitmask type for setting a mask 887of zero or more elink:VkDescriptorSetLayoutCreateFlagBits. 888-- 889 890[open,refpage='VkDescriptorSetLayoutBinding',desc='Structure specifying a descriptor set layout binding',type='structs'] 891-- 892The sname:VkDescriptorSetLayoutBinding structure is defined as: 893 894include::{generated}/api/structs/VkDescriptorSetLayoutBinding.adoc[] 895 896 * pname:binding is the binding number of this entry and corresponds to a 897 resource of the same binding number in the shader stages. 898 * pname:descriptorType is a elink:VkDescriptorType specifying which type 899 of resource descriptors are used for this binding. 900 * pname:descriptorCount is the number of descriptors contained in the 901 binding, accessed in a shader as an 902ifndef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[array.] 903ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 904 array, except if pname:descriptorType is 905 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK in which case 906 pname:descriptorCount is the size in bytes of the inline uniform block. 907endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 908 If pname:descriptorCount is zero this binding entry is reserved and the 909 resource must: not be accessed from any stage via this binding within 910 any pipeline using the set layout. 911 * pname:stageFlags member is a bitmask of elink:VkShaderStageFlagBits 912 specifying which pipeline shader stages can: access a resource for this 913 binding. 914 ename:VK_SHADER_STAGE_ALL is a shorthand specifying that all defined 915 shader stages, including any additional stages defined by extensions, 916 can: access the resource. 917+ 918If a shader stage is not included in pname:stageFlags, then a resource must: 919not be accessed from that stage via this binding within any pipeline using 920the set layout. 921Other than input attachments which are limited to the fragment shader, there 922are no limitations on what combinations of stages can: use a descriptor 923binding, and in particular a binding can: be used by both graphics stages 924and the compute stage. 925 * pname:pImmutableSamplers affects initialization of samplers. 926 If pname:descriptorType specifies a ename:VK_DESCRIPTOR_TYPE_SAMPLER or 927 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then 928 pname:pImmutableSamplers can: be used to initialize a set of _immutable 929 samplers_. 930 Immutable samplers are permanently bound into the set layout and must: 931 not be changed; updating a ename:VK_DESCRIPTOR_TYPE_SAMPLER descriptor 932 with immutable samplers is not allowed and updates to a 933 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptor with 934 immutable samplers does not modify the samplers (the image views are 935 updated, but the sampler updates are ignored). 936 If pname:pImmutableSamplers is not `NULL`, then it is a pointer to an 937 array of sampler handles that will be copied into the set layout and 938 used for the corresponding binding. 939 Only the sampler handles are copied; the sampler objects must: not be 940 destroyed before the final use of the set layout and any descriptor 941 pools and sets created using it. 942 If pname:pImmutableSamplers is `NULL`, then the sampler slots are 943 dynamic and sampler handles must: be bound into descriptor sets using 944 this layout. 945 If pname:descriptorType is not one of these descriptor types, then 946 pname:pImmutableSamplers is ignored. 947 948The above layout definition allows the descriptor bindings to be specified 949sparsely such that not all binding numbers between 0 and the maximum binding 950number need to be specified in the pname:pBindings array. 951Bindings that are not specified have a pname:descriptorCount and 952pname:stageFlags of zero, and the value of pname:descriptorType is 953undefined:. 954However, all binding numbers between 0 and the maximum binding number in the 955slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings array may: consume 956memory in the descriptor set layout even if not all descriptor bindings are 957used, though it should: not consume additional memory from the descriptor 958pool. 959 960[NOTE] 961.Note 962==== 963The maximum binding number specified should: be as compact as possible to 964avoid wasted memory. 965==== 966 967.Valid Usage 968**** 969 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-00282]] 970 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 971 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 972 pname:descriptorCount is not `0` and pname:pImmutableSamplers is not 973 `NULL`, pname:pImmutableSamplers must: be a valid pointer to an array of 974 pname:descriptorCount valid sname:VkSampler handles 975ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 976 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-04604]] 977 If the <<features-inlineUniformBlock, pname:inlineUniformBlock>> feature 978 is not enabled, pname:descriptorType must: not be 979 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 980 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-02209]] 981 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 982 then pname:descriptorCount must: be a multiple of `4` 983 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-08004]] 984 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 985ifdef::VK_EXT_descriptor_buffer[] 986 and slink:VkDescriptorSetLayoutCreateInfo::pname:flags does not contain 987 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT 988endif::VK_EXT_descriptor_buffer[] 989 then pname:descriptorCount must: be less than or equal to 990 sname:VkPhysicalDeviceInlineUniformBlockProperties::pname:maxInlineUniformBlockSize 991ifdef::VK_EXT_descriptor_buffer[] 992 * [[VUID-VkDescriptorSetLayoutBinding-flags-08005]] 993 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags contains 994 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, 995 pname:descriptorType must: be ename:VK_DESCRIPTOR_TYPE_SAMPLER 996 * [[VUID-VkDescriptorSetLayoutBinding-flags-08006]] 997 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags contains 998 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, 999 pname:descriptorCount must: less than or equal to `1` 1000 * [[VUID-VkDescriptorSetLayoutBinding-flags-08007]] 1001 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags contains 1002 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, 1003 and pname:descriptorCount is equal to `1`, pname:pImmutableSamplers 1004 must: not be `NULL` 1005endif::VK_EXT_descriptor_buffer[] 1006endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1007 * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-00283]] 1008 If pname:descriptorCount is not `0`, pname:stageFlags must: be a valid 1009 combination of elink:VkShaderStageFlagBits values 1010 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-01510]] 1011 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and 1012 pname:descriptorCount is not `0`, then pname:stageFlags must: be `0` or 1013 ename:VK_SHADER_STAGE_FRAGMENT_BIT 1014ifdef::VK_EXT_custom_border_color[] 1015 * [[VUID-VkDescriptorSetLayoutBinding-pImmutableSamplers-04009]] 1016 The sampler objects indicated by pname:pImmutableSamplers must: not have 1017 a pname:borderColor with one of the values 1018 ename:VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or 1019 ename:VK_BORDER_COLOR_INT_CUSTOM_EXT 1020endif::VK_EXT_custom_border_color[] 1021ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 1022 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-04605]] 1023 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, then 1024 sname:pImmutableSamplers must: be `NULL` 1025endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 1026ifdef::VKSC_VERSION_1_0[] 1027 * [[VUID-VkDescriptorSetLayoutBinding-binding-05012]] 1028 pname:binding must: be less than the value of 1029 slink:VkDeviceObjectReservationCreateInfo::pname:descriptorSetLayoutBindingLimit 1030 provided when the device was created 1031endif::VKSC_VERSION_1_0[] 1032**** 1033 1034include::{generated}/validity/structs/VkDescriptorSetLayoutBinding.adoc[] 1035-- 1036 1037ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1038[open,refpage='VkDescriptorSetLayoutBindingFlagsCreateInfo',desc='Structure specifying creation flags for descriptor set layout bindings',type='structs',alias='VkDescriptorSetLayoutBindingFlagsCreateInfoEXT'] 1039-- 1040If the pname:pNext chain of a slink:VkDescriptorSetLayoutCreateInfo 1041structure includes a slink:VkDescriptorSetLayoutBindingFlagsCreateInfo 1042structure, then that structure includes an array of flags, one for each 1043descriptor set layout binding. 1044 1045The slink:VkDescriptorSetLayoutBindingFlagsCreateInfo structure is defined 1046as: 1047 1048include::{generated}/api/structs/VkDescriptorSetLayoutBindingFlagsCreateInfo.adoc[] 1049 1050ifdef::VK_EXT_descriptor_indexing[] 1051or the equivalent 1052 1053include::{generated}/api/structs/VkDescriptorSetLayoutBindingFlagsCreateInfoEXT.adoc[] 1054endif::VK_EXT_descriptor_indexing[] 1055 1056 * pname:sType is a elink:VkStructureType value identifying this structure. 1057 * pname:pNext is `NULL` or a pointer to a structure extending this 1058 structure. 1059 * pname:bindingCount is zero or the number of elements in 1060 pname:pBindingFlags. 1061 * pname:pBindingFlags is a pointer to an array of 1062 tlink:VkDescriptorBindingFlags bitfields, one for each descriptor set 1063 layout binding. 1064 1065If pname:bindingCount is zero or if this structure is not included in the 1066pname:pNext chain, the tlink:VkDescriptorBindingFlags for each descriptor 1067set layout binding is considered to be zero. 1068Otherwise, the descriptor set layout binding at 1069slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings[i] uses the flags in 1070pname:pBindingFlags[i]. 1071 1072.Valid Usage 1073**** 1074 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-bindingCount-03002]] 1075 If pname:bindingCount is not zero, pname:bindingCount must: equal 1076 slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount 1077ifdef::VK_KHR_push_descriptor[] 1078 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-flags-03003]] 1079 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags includes 1080 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 1081 elements of pname:pBindingFlags must: not include 1082 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT, 1083 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT, or 1084 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT 1085endif::VK_KHR_push_descriptor[] 1086 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-pBindingFlags-03004]] 1087 If an element of pname:pBindingFlags includes 1088 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, then all 1089 other elements of slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings 1090 must: have a smaller value of pname:binding 1091 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-pBindingFlags-09379]] 1092 If an element of pname:pBindingFlags includes 1093 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, then it must: 1094 be the element with the the highest pname:binding number 1095 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUniformBufferUpdateAfterBind-03005]] 1096 If 1097 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUniformBufferUpdateAfterBind 1098 is not enabled, all bindings with descriptor type 1099 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER must: not use 1100 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1101 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingSampledImageUpdateAfterBind-03006]] 1102 If 1103 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingSampledImageUpdateAfterBind 1104 is not enabled, all bindings with descriptor type 1105 ename:VK_DESCRIPTOR_TYPE_SAMPLER, 1106 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, or 1107 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE must: not use 1108 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1109 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageImageUpdateAfterBind-03007]] 1110 If 1111 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageImageUpdateAfterBind 1112 is not enabled, all bindings with descriptor type 1113 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE must: not use 1114 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1115 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageBufferUpdateAfterBind-03008]] 1116 If 1117 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageBufferUpdateAfterBind 1118 is not enabled, all bindings with descriptor type 1119 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER must: not use 1120 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1121 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUniformTexelBufferUpdateAfterBind-03009]] 1122 If 1123 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUniformTexelBufferUpdateAfterBind 1124 is not enabled, all bindings with descriptor type 1125 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER must: not use 1126 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1127 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingStorageTexelBufferUpdateAfterBind-03010]] 1128 If 1129 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingStorageTexelBufferUpdateAfterBind 1130 is not enabled, all bindings with descriptor type 1131 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER must: not use 1132 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1133ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1134 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingInlineUniformBlockUpdateAfterBind-02211]] 1135 If 1136 slink:VkPhysicalDeviceInlineUniformBlockFeatures::pname:descriptorBindingInlineUniformBlockUpdateAfterBind 1137 is not enabled, all bindings with descriptor type 1138 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK must: not use 1139 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1140endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1141ifdef::VK_KHR_acceleration_structure[] 1142 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingAccelerationStructureUpdateAfterBind-03570]] 1143 If 1144 slink:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:descriptorBindingAccelerationStructureUpdateAfterBind 1145 is not enabled, all bindings with descriptor type 1146 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR or 1147 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV must: not use 1148 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1149endif::VK_KHR_acceleration_structure[] 1150 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-None-03011]] 1151 All bindings with descriptor type 1152 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 1153 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 1154 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: not use 1155 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT 1156 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingUpdateUnusedWhilePending-03012]] 1157 If 1158 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingUpdateUnusedWhilePending 1159 is not enabled, all elements of pname:pBindingFlags must: not include 1160 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT 1161 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingPartiallyBound-03013]] 1162 If 1163 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingPartiallyBound 1164 is not enabled, all elements of pname:pBindingFlags must: not include 1165 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT 1166 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-descriptorBindingVariableDescriptorCount-03014]] 1167 If 1168 slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingVariableDescriptorCount 1169 is not enabled, all elements of pname:pBindingFlags must: not include 1170 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT 1171 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfo-pBindingFlags-03015]] 1172 If an element of pname:pBindingFlags includes 1173 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, that 1174 element's pname:descriptorType must: not be 1175 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 1176 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 1177**** 1178 1179include::{generated}/validity/structs/VkDescriptorSetLayoutBindingFlagsCreateInfo.adoc[] 1180-- 1181 1182[open,refpage='VkDescriptorBindingFlagBits',desc='Bitmask specifying descriptor set layout binding properties',type='enums',alias='VkDescriptorBindingFlagBitsEXT'] 1183-- 1184Bits which can: be set in each element of 1185slink:VkDescriptorSetLayoutBindingFlagsCreateInfo::pname:pBindingFlags, 1186specifying options for the corresponding descriptor set layout binding, are: 1187 1188include::{generated}/api/enums/VkDescriptorBindingFlagBits.adoc[] 1189 1190ifdef::VK_EXT_descriptor_indexing[] 1191or the equivalent 1192 1193include::{generated}/api/enums/VkDescriptorBindingFlagBitsEXT.adoc[] 1194endif::VK_EXT_descriptor_indexing[] 1195 1196// Used below for VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 1197:maxBlockSize: <<limits-maxInlineUniformBlockSize, pname:maxInlineUniformBlockSize>> 1198:maxTotalSize: <<limits-maxInlineUniformTotalSize, pname:maxInlineUniformTotalSize>> 1199 1200 * ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT indicates that if 1201 descriptors in this binding are updated between when the descriptor set 1202 is bound in a command buffer and when that command buffer is submitted 1203 to a queue, then the submission will use the most recently set 1204 descriptors for this binding and the updates do not invalidate the 1205 command buffer. 1206 Descriptor bindings created with this flag are also partially exempt 1207 from the external synchronization requirement in 1208ifdef::VK_KHR_descriptor_update_template[] 1209 flink:vkUpdateDescriptorSetWithTemplateKHR and 1210endif::VK_KHR_descriptor_update_template[] 1211 flink:vkUpdateDescriptorSets. 1212 Multiple descriptors with this flag set can: be updated concurrently in 1213 different threads, though the same descriptor must: not be updated 1214 concurrently by two threads. 1215 Descriptors with this flag set can: be updated concurrently with the set 1216 being bound to a command buffer in another thread, but not concurrently 1217 with the set being reset or freed. 1218 * ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT indicates that 1219 descriptors in this binding that are not _dynamically used_ need not 1220 contain valid descriptors at the time the descriptors are consumed. 1221 A descriptor is dynamically used if any shader invocation executes an 1222 instruction that performs any memory access using the descriptor. 1223 If a descriptor is not dynamically used, any resource referenced by the 1224 descriptor is not considered to be referenced during command execution. 1225 * ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT indicates 1226 that descriptors in this binding can: be updated after a command buffer 1227 has bound this descriptor set, or while a command buffer that uses this 1228 descriptor set is pending execution, as long as the descriptors that are 1229 updated are not used by those command buffers. 1230 Descriptor bindings created with this flag are also partially exempt 1231 from the external synchronization requirement in 1232 flink:vkUpdateDescriptorSetWithTemplateKHR and 1233 flink:vkUpdateDescriptorSets in the same way as for 1234 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT. 1235 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT is also set, then 1236 descriptors can: be updated as long as they are not dynamically used by 1237 any shader invocations. 1238 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT is not set, then 1239 descriptors can: be updated as long as they are not statically used by 1240 any shader invocations. 1241 * ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT indicates that 1242 this is a _variable-sized descriptor binding_ whose size will be 1243 specified when a descriptor set is allocated using this layout. 1244 The value of pname:descriptorCount is treated as an upper bound on the 1245 size of the binding. 1246 This must: only be used for the last binding in the descriptor set 1247 layout (i.e. the binding with the largest value of pname:binding). 1248 For the purposes of counting against limits such as 1249 pname:maxDescriptorSet* and pname:maxPerStageDescriptor*, the full value 1250 of pname:descriptorCount is 1251ifndef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[counted.] 1252ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1253 counted, except for descriptor bindings with a descriptor type of 1254ifndef::VK_EXT_descriptor_buffer[] 1255 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK. 1256endif::VK_EXT_descriptor_buffer[] 1257ifdef::VK_EXT_descriptor_buffer[] 1258 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, when 1259 slink:VkDescriptorSetLayoutCreateInfo::pname:flags does not contain 1260 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT. 1261endif::VK_EXT_descriptor_buffer[] 1262 In this case, pname:descriptorCount specifies the upper bound on the 1263 byte size of the binding; thus it counts against the 1264ifdef::VK_VERSION_1_3+VK_EXT_inline_uniform_block[{maxBlockSize} and {maxTotalSize} limits] 1265ifndef::VK_VERSION_1_3[{maxBlockSize} limit] 1266ifndef::VK_EXT_inline_uniform_block[{maxTotalSize} limit] 1267instead. 1268endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1269 1270[NOTE] 1271.Note 1272==== 1273Note that while ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT and 1274ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT both involve 1275updates to descriptor sets after they are bound, 1276ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT is a weaker 1277requirement since it is only about descriptors that are not used, whereas 1278ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT requires the 1279implementation to observe updates to descriptors that are used. 1280==== 1281-- 1282 1283[open,refpage='VkDescriptorBindingFlags',desc='Bitmask of VkDescriptorBindingFlagBits',type='flags',alias='VkDescriptorBindingFlagsEXT'] 1284-- 1285include::{generated}/api/flags/VkDescriptorBindingFlags.adoc[] 1286 1287ifdef::VK_EXT_descriptor_indexing[] 1288or the equivalent 1289 1290include::{generated}/api/flags/VkDescriptorBindingFlagsEXT.adoc[] 1291endif::VK_EXT_descriptor_indexing[] 1292 1293tname:VkDescriptorBindingFlags is a bitmask type for setting a mask of zero 1294or more elink:VkDescriptorBindingFlagBits. 1295-- 1296endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1297 1298ifdef::VK_VERSION_1_1,VK_KHR_maintenance3[] 1299[open,refpage='vkGetDescriptorSetLayoutSupport',desc='Query whether a descriptor set layout can be created',type='protos'] 1300-- 1301To query information about whether a descriptor set layout can: be created, 1302call: 1303 1304ifdef::VK_VERSION_1_1[] 1305include::{generated}/api/protos/vkGetDescriptorSetLayoutSupport.adoc[] 1306endif::VK_VERSION_1_1[] 1307 1308ifdef::VK_VERSION_1_1+VK_KHR_maintenance3[or the equivalent command] 1309 1310ifdef::VK_KHR_maintenance3[] 1311include::{generated}/api/protos/vkGetDescriptorSetLayoutSupportKHR.adoc[] 1312endif::VK_KHR_maintenance3[] 1313 1314 * pname:device is the logical device that would create the descriptor set 1315 layout. 1316 * pname:pCreateInfo is a pointer to a 1317 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 1318 the descriptor set layout object. 1319 * pname:pSupport is a pointer to a slink:VkDescriptorSetLayoutSupport 1320 structure, in which information about support for the descriptor set 1321 layout object is returned. 1322 1323Some implementations have limitations on what fits in a descriptor set which 1324are not easily expressible in terms of existing limits like 1325pname:maxDescriptorSet*, for example if all descriptor types share a limited 1326space in memory but each descriptor is a different size or alignment. 1327This command returns information about whether a descriptor set satisfies 1328this limit. 1329If the descriptor set layout satisfies the 1330slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 1331limit, this command is guaranteed to return ename:VK_TRUE in 1332slink:VkDescriptorSetLayoutSupport::pname:supported. 1333If the descriptor set layout exceeds the 1334slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 1335limit, whether the descriptor set layout is supported is 1336implementation-dependent and may: depend on whether the descriptor sizes and 1337alignments cause the layout to exceed an internal limit. 1338 1339This command does not consider other limits such as 1340pname:maxPerStageDescriptor*, and so a descriptor set layout that is 1341supported according to this command must: still satisfy the pipeline layout 1342limits such as pname:maxPerStageDescriptor* in order to be used in a 1343pipeline layout. 1344 1345[NOTE] 1346.Note 1347==== 1348This is a sname:VkDevice query rather than sname:VkPhysicalDevice because 1349the answer may: depend on enabled features. 1350==== 1351 1352include::{generated}/validity/protos/vkGetDescriptorSetLayoutSupport.adoc[] 1353-- 1354 1355[open,refpage='VkDescriptorSetLayoutSupport',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs'] 1356-- 1357Information about support for the descriptor set layout is returned in a 1358sname:VkDescriptorSetLayoutSupport structure: 1359 1360include::{generated}/api/structs/VkDescriptorSetLayoutSupport.adoc[] 1361 1362ifdef::VK_KHR_maintenance3[] 1363or the equivalent 1364 1365include::{generated}/api/structs/VkDescriptorSetLayoutSupportKHR.adoc[] 1366endif::VK_KHR_maintenance3[] 1367 1368 * pname:sType is a elink:VkStructureType value identifying this structure. 1369 * pname:pNext is `NULL` or a pointer to a structure extending this 1370 structure. 1371 * pname:supported specifies whether the descriptor set layout can: be 1372 created. 1373 1374pname:supported is set to ename:VK_TRUE if the descriptor set can: be 1375created, or else is set to ename:VK_FALSE. 1376 1377include::{generated}/validity/structs/VkDescriptorSetLayoutSupport.adoc[] 1378-- 1379endif::VK_VERSION_1_1,VK_KHR_maintenance3[] 1380 1381ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1382[open,refpage='VkDescriptorSetVariableDescriptorCountLayoutSupport',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs',alias='VkDescriptorSetVariableDescriptorCountLayoutSupportEXT'] 1383-- 1384If the pname:pNext chain of a slink:VkDescriptorSetLayoutSupport structure 1385includes a sname:VkDescriptorSetVariableDescriptorCountLayoutSupport 1386structure, then that structure returns additional information about whether 1387the descriptor set layout is supported. 1388 1389include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountLayoutSupport.adoc[] 1390 1391ifdef::VK_EXT_descriptor_indexing[] 1392or the equivalent 1393 1394include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.adoc[] 1395endif::VK_EXT_descriptor_indexing[] 1396 1397 * pname:sType is a elink:VkStructureType value identifying this structure. 1398 * pname:pNext is `NULL` or a pointer to a structure extending this 1399 structure. 1400 * pname:maxVariableDescriptorCount indicates the maximum number of 1401 descriptors supported in the highest numbered binding of the layout, if 1402 that binding is variable-sized. 1403ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1404 If the highest numbered binding of the layout has a descriptor type of 1405 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 1406 pname:maxVariableDescriptorCount indicates the maximum byte size 1407 supported for the binding, if that binding is variable-sized. 1408endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1409 1410If the slink:VkDescriptorSetLayoutCreateInfo structure specified in 1411flink:vkGetDescriptorSetLayoutSupport::pname:pCreateInfo includes a 1412variable-sized descriptor, then pname:supported is determined assuming the 1413requested size of the variable-sized descriptor, and 1414pname:maxVariableDescriptorCount is set to the maximum size of that 1415descriptor that can: be successfully created (which is greater than or equal 1416to the requested size passed in). 1417If the slink:VkDescriptorSetLayoutCreateInfo structure does not include a 1418variable-sized descriptor, or if the 1419slink:VkPhysicalDeviceDescriptorIndexingFeatures::pname:descriptorBindingVariableDescriptorCount 1420feature is not enabled, then pname:maxVariableDescriptorCount is set to 1421zero. 1422For the purposes of this command, a variable-sized descriptor binding with a 1423pname:descriptorCount of zero is treated as having a pname:descriptorCount 1424of 1425ifndef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[one,] 1426ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1427four if pname:descriptorType is 1428ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, or one otherwise, 1429endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1430and thus the binding is not ignored and the maximum descriptor count will be 1431returned. 1432If the layout is not supported, then the value written to 1433pname:maxVariableDescriptorCount is undefined:. 1434 1435include::{generated}/validity/structs/VkDescriptorSetVariableDescriptorCountLayoutSupport.adoc[] 1436-- 1437endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1438 1439The following examples show a shader snippet using two descriptor sets, and 1440application code that creates corresponding descriptor set layouts. 1441 1442.GLSL example 1443[source,glsl] 1444---- 1445// 1446// binding to a single sampled image descriptor in set 0 1447// 1448layout (set=0, binding=0) uniform texture2D mySampledImage; 1449 1450// 1451// binding to an array of sampled image descriptors in set 0 1452// 1453layout (set=0, binding=1) uniform texture2D myArrayOfSampledImages[12]; 1454 1455// 1456// binding to a single uniform buffer descriptor in set 1 1457// 1458layout (set=1, binding=0) uniform myUniformBuffer 1459{ 1460 vec4 myElement[32]; 1461}; 1462---- 1463 1464.SPIR-V example 1465[source,spirv] 1466---- 1467 ... 1468 %1 = OpExtInstImport "GLSL.std.450" 1469 ... 1470 OpName %9 "mySampledImage" 1471 OpName %14 "myArrayOfSampledImages" 1472 OpName %18 "myUniformBuffer" 1473 OpMemberName %18 0 "myElement" 1474 OpName %20 "" 1475 OpDecorate %9 DescriptorSet 0 1476 OpDecorate %9 Binding 0 1477 OpDecorate %14 DescriptorSet 0 1478 OpDecorate %14 Binding 1 1479 OpDecorate %17 ArrayStride 16 1480 OpMemberDecorate %18 0 Offset 0 1481 OpDecorate %18 Block 1482 OpDecorate %20 DescriptorSet 1 1483 OpDecorate %20 Binding 0 1484 %2 = OpTypeVoid 1485 %3 = OpTypeFunction %2 1486 %6 = OpTypeFloat 32 1487 %7 = OpTypeImage %6 2D 0 0 0 1 Unknown 1488 %8 = OpTypePointer UniformConstant %7 1489 %9 = OpVariable %8 UniformConstant 1490 %10 = OpTypeInt 32 0 1491 %11 = OpConstant %10 12 1492 %12 = OpTypeArray %7 %11 1493 %13 = OpTypePointer UniformConstant %12 1494 %14 = OpVariable %13 UniformConstant 1495 %15 = OpTypeVector %6 4 1496 %16 = OpConstant %10 32 1497 %17 = OpTypeArray %15 %16 1498 %18 = OpTypeStruct %17 1499 %19 = OpTypePointer Uniform %18 1500 %20 = OpVariable %19 Uniform 1501 ... 1502---- 1503 1504.API example 1505[source,c++] 1506---- 1507VkResult myResult; 1508 1509const VkDescriptorSetLayoutBinding myDescriptorSetLayoutBinding[] = 1510{ 1511 // binding to a single image descriptor 1512 { 1513 .binding = 0, 1514 .descriptorType = VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 1515 .descriptorCount = 1, 1516 .stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT, 1517 .pImmutableSamplers = NULL 1518 }, 1519 1520 // binding to an array of image descriptors 1521 { 1522 .binding = 1, 1523 .descriptorType = VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 1524 .descriptorCount = 12, 1525 .stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT, 1526 .pImmutableSamplers = NULL 1527 }, 1528 1529 // binding to a single uniform buffer descriptor 1530 { 1531 .binding = 0, 1532 .descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 1533 .descriptorCount = 1, 1534 .stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT, 1535 .pImmutableSamplers = NULL 1536 } 1537}; 1538 1539const VkDescriptorSetLayoutCreateInfo myDescriptorSetLayoutCreateInfo[] = 1540{ 1541 // Information for first descriptor set with two descriptor bindings 1542 { 1543 .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, 1544 .pNext = NULL, 1545 .flags = 0, 1546 .bindingCount = 2, 1547 .pBindings = &myDescriptorSetLayoutBinding[0] 1548 }, 1549 1550 // Information for second descriptor set with one descriptor binding 1551 { 1552 .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, 1553 .pNext = NULL, 1554 .flags = 0, 1555 .bindingCount = 1, 1556 .pBindings = &myDescriptorSetLayoutBinding[2] 1557 } 1558}; 1559 1560VkDescriptorSetLayout myDescriptorSetLayout[2]; 1561 1562// 1563// Create first descriptor set layout 1564// 1565myResult = vkCreateDescriptorSetLayout( 1566 myDevice, 1567 &myDescriptorSetLayoutCreateInfo[0], 1568 NULL, 1569 &myDescriptorSetLayout[0]); 1570 1571// 1572// Create second descriptor set layout 1573// 1574myResult = vkCreateDescriptorSetLayout( 1575 myDevice, 1576 &myDescriptorSetLayoutCreateInfo[1], 1577 NULL, 1578 &myDescriptorSetLayout[1]); 1579---- 1580 1581[open,refpage='vkDestroyDescriptorSetLayout',desc='Destroy a descriptor set layout object',type='protos'] 1582-- 1583To destroy a descriptor set layout, call: 1584 1585include::{generated}/api/protos/vkDestroyDescriptorSetLayout.adoc[] 1586 1587 * pname:device is the logical device that destroys the descriptor set 1588 layout. 1589 * pname:descriptorSetLayout is the descriptor set layout to destroy. 1590 * pname:pAllocator controls host memory allocation as described in the 1591 <<memory-allocation, Memory Allocation>> chapter. 1592 1593ifndef::VKSC_VERSION_1_0[] 1594.Valid Usage 1595**** 1596 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00284]] 1597 If sname:VkAllocationCallbacks were provided when 1598 pname:descriptorSetLayout was created, a compatible set of callbacks 1599 must: be provided here 1600 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00285]] 1601 If no sname:VkAllocationCallbacks were provided when 1602 pname:descriptorSetLayout was created, pname:pAllocator must: be `NULL` 1603**** 1604endif::VKSC_VERSION_1_0[] 1605 1606include::{generated}/validity/protos/vkDestroyDescriptorSetLayout.adoc[] 1607-- 1608 1609 1610[[descriptorsets-pipelinelayout]] 1611=== Pipeline Layouts 1612 1613[open,refpage='VkPipelineLayout',desc='Opaque handle to a pipeline layout object',type='handles'] 1614-- 1615Access to descriptor sets from a pipeline is accomplished through a 1616_pipeline layout_. 1617Zero or more descriptor set layouts and zero or more push constant ranges 1618are combined to form a pipeline layout object describing the complete set of 1619resources that can: be accessed by a pipeline. 1620The pipeline layout represents a sequence of descriptor sets with each 1621having a specific layout. 1622This sequence of layouts is used to determine the interface between shader 1623stages and shader resources. 1624Each pipeline is created using a pipeline layout. 1625 1626Pipeline layout objects are represented by sname:VkPipelineLayout handles: 1627 1628include::{generated}/api/handles/VkPipelineLayout.adoc[] 1629-- 1630 1631[open,refpage='vkCreatePipelineLayout',desc='Creates a new pipeline layout object',type='protos'] 1632-- 1633:refpage: vkCreatePipelineLayout 1634:objectnameplural: pipeline layouts 1635:objectnamecamelcase: pipelineLayout 1636:objectcount: 1 1637 1638To create a pipeline layout, call: 1639 1640include::{generated}/api/protos/vkCreatePipelineLayout.adoc[] 1641 1642 * pname:device is the logical device that creates the pipeline layout. 1643 * pname:pCreateInfo is a pointer to a slink:VkPipelineLayoutCreateInfo 1644 structure specifying the state of the pipeline layout object. 1645 * pname:pAllocator controls host memory allocation as described in the 1646 <<memory-allocation, Memory Allocation>> chapter. 1647 * pname:pPipelineLayout is a pointer to a slink:VkPipelineLayout handle in 1648 which the resulting pipeline layout object is returned. 1649 1650include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1651 1652ifdef::VKSC_VERSION_1_0[] 1653.Valid Usage 1654**** 1655include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 1656**** 1657endif::VKSC_VERSION_1_0[] 1658 1659include::{generated}/validity/protos/vkCreatePipelineLayout.adoc[] 1660-- 1661 1662[open,refpage='VkPipelineLayoutCreateInfo',desc='Structure specifying the parameters of a newly created pipeline layout object',type='structs'] 1663-- 1664The slink:VkPipelineLayoutCreateInfo structure is defined as: 1665 1666include::{generated}/api/structs/VkPipelineLayoutCreateInfo.adoc[] 1667 1668 * pname:sType is a elink:VkStructureType value identifying this structure. 1669 * pname:pNext is `NULL` or a pointer to a structure extending this 1670 structure. 1671 * pname:flags is a bitmask of elink:VkPipelineLayoutCreateFlagBits 1672 specifying options for pipeline layout creation. 1673 * pname:setLayoutCount is the number of descriptor sets included in the 1674 pipeline layout. 1675 * pname:pSetLayouts is a pointer to an array of 1676 sname:VkDescriptorSetLayout objects. 1677 * pname:pushConstantRangeCount is the number of push constant ranges 1678 included in the pipeline layout. 1679 * pname:pPushConstantRanges is a pointer to an array of 1680 sname:VkPushConstantRange structures defining a set of push constant 1681 ranges for use in a single pipeline layout. 1682 In addition to descriptor set layouts, a pipeline layout also describes 1683 how many push constants can: be accessed by each stage of the pipeline. 1684+ 1685[NOTE] 1686.Note 1687==== 1688Push constants represent a high speed path to modify constant data in 1689pipelines that is expected to outperform memory-backed resource updates. 1690==== 1691 1692ifdef::VKSC_VERSION_1_0[] 1693In Vulkan SC, the pipeline compilation process occurs 1694<<pipelines-offline-compilation,offline>>, but the application must: still 1695provide values to sname:VkPipelineLayoutCreateInfo that match the values 1696used for offline compilation of pipelines using this slink:VkPipelineLayout. 1697endif::VKSC_VERSION_1_0[] 1698 1699.Valid Usage 1700**** 1701 * [[VUID-VkPipelineLayoutCreateInfo-setLayoutCount-00286]] 1702 pname:setLayoutCount must: be less than or equal to 1703 sname:VkPhysicalDeviceLimits::pname:maxBoundDescriptorSets 1704 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03016]] 1705 The total number of descriptors in descriptor set layouts 1706ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1707 created without the 1708 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1709endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1710 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1711 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1712 shader stage across all elements of pname:pSetLayouts must: be less than 1713 or equal to 1714 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSamplers 1715 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03017]] 1716 The total number of descriptors in descriptor set layouts 1717ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1718 created without the 1719 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1720endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1721 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER 1722 and ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any 1723 given shader stage across all elements of pname:pSetLayouts must: be 1724 less than or equal to 1725 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorUniformBuffers 1726 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03018]] 1727 The total number of descriptors in descriptor set layouts 1728ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1729 created without the 1730 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1731endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1732 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER 1733 and ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any 1734 given shader stage across all elements of pname:pSetLayouts must: be 1735 less than or equal to 1736 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageBuffers 1737 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-06939]] 1738 The total number of descriptors in descriptor set layouts 1739ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1740 created without the 1741 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1742endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1743 with a pname:descriptorType of 1744 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1745 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 1746ifdef::VK_QCOM_image_processing[] 1747 ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM, 1748 ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM, 1749endif::VK_QCOM_image_processing[] 1750 and ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, accessible to any 1751 given shader stage across all elements of pname:pSetLayouts must: be 1752 less than or equal to 1753 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSampledImages 1754 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03020]] 1755 The total number of descriptors in descriptor set layouts 1756ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1757 created without the 1758 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1759endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1760 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 1761 and ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any 1762 given shader stage across all elements of pname:pSetLayouts must: be 1763 less than or equal to 1764 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageImages 1765 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03021]] 1766 The total number of descriptors in descriptor set layouts 1767ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1768 created without the 1769 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1770endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1771 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 1772 accessible to any given shader stage across all elements of 1773 pname:pSetLayouts must: be less than or equal to 1774 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorInputAttachments 1775ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1776 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02214]] 1777 The total number of bindings in descriptor set layouts 1778ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1779 created without the 1780 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1781 and 1782endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1783 with a pname:descriptorType of 1784 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK accessible to any given 1785 shader stage across all elements of pname:pSetLayouts, must: be less 1786 than or equal to 1787 sname:VkPhysicalDeviceInlineUniformBlockProperties::pname:maxPerStageDescriptorInlineUniformBlocks 1788endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1789ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1790 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03022]] 1791 The total number of descriptors with a pname:descriptorType of 1792 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1793 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1794 shader stage across all elements of pname:pSetLayouts must: be less than 1795 or equal to 1796 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindSamplers 1797 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03023]] 1798 The total number of descriptors with a pname:descriptorType of 1799 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1800 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any given 1801 shader stage across all elements of pname:pSetLayouts must: be less than 1802 or equal to 1803 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers 1804 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03024]] 1805 The total number of descriptors with a pname:descriptorType of 1806 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1807 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any given 1808 shader stage across all elements of pname:pSetLayouts must: be less than 1809 or equal to 1810 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers 1811 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03025]] 1812 The total number of descriptors with a pname:descriptorType of 1813 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1814 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1815 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any given 1816 shader stage across all elements of pname:pSetLayouts must: be less than 1817 or equal to 1818 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindSampledImages 1819 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03026]] 1820 The total number of descriptors with a pname:descriptorType of 1821 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1822 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any given 1823 shader stage across all elements of pname:pSetLayouts must: be less than 1824 or equal to 1825 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindStorageImages 1826 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03027]] 1827 The total number of descriptors with a pname:descriptorType of 1828 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1829 stage across all elements of pname:pSetLayouts must: be less than or 1830 equal to 1831 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxPerStageDescriptorUpdateAfterBindInputAttachments 1832ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1833 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02215]] 1834 The total number of bindings with a pname:descriptorType of 1835 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK accessible to any given 1836 shader stage across all elements of pname:pSetLayouts must: be less than 1837 or equal to 1838 sname:VkPhysicalDeviceInlineUniformBlockProperties::pname:maxPerStageDescriptorUpdateAfterBindInlineUniformBlocks 1839endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1840endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1841 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03028]] 1842 The total number of descriptors in descriptor set layouts 1843ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1844 created without the 1845 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1846endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1847 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1848 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1849 shader stages and across all elements of pname:pSetLayouts must: be less 1850 than or equal to 1851 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSamplers 1852 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03029]] 1853 The total number of descriptors in descriptor set layouts 1854ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1855 created without the 1856 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1857endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1858 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER 1859 accessible across all shader stages and across all elements of 1860 pname:pSetLayouts must: be less than or equal to 1861 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffers 1862 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03030]] 1863 The total number of descriptors in descriptor set layouts 1864ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1865 created without the 1866 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1867endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1868 with a pname:descriptorType of 1869 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1870 shader stages and across all elements of pname:pSetLayouts must: be less 1871 than or equal to 1872 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffersDynamic 1873 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03031]] 1874 The total number of descriptors in descriptor set layouts 1875ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1876 created without the 1877 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1878endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1879 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER 1880 accessible across all shader stages and across all elements of 1881 pname:pSetLayouts must: be less than or equal to 1882 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffers 1883 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03032]] 1884 The total number of descriptors in descriptor set layouts 1885ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1886 created without the 1887 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1888endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1889 with a pname:descriptorType of 1890 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1891 shader stages and across all elements of pname:pSetLayouts must: be less 1892 than or equal to 1893 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffersDynamic 1894 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03033]] 1895 The total number of descriptors in descriptor set layouts 1896ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1897 created without the 1898 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1899endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1900 with a pname:descriptorType of 1901 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1902 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1903 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1904 shader stages and across all elements of pname:pSetLayouts must: be less 1905 than or equal to 1906 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSampledImages 1907 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03034]] 1908 The total number of descriptors in descriptor set layouts 1909ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1910 created without the 1911 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1912endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1913 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 1914 and ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1915 shader stages and across all elements of pname:pSetLayouts must: be less 1916 than or equal to 1917 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageImages 1918 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03035]] 1919 The total number of descriptors in descriptor set layouts 1920ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1921 created without the 1922 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1923endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1924 with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT 1925 accessible across all shader stages and across all elements of 1926 pname:pSetLayouts must: be less than or equal to 1927 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetInputAttachments 1928ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1929 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02216]] 1930 The total number of bindings in descriptor set layouts 1931ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1932 created without the 1933 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit set 1934endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1935 with a pname:descriptorType of 1936 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK accessible across all 1937 shader stages and across all elements of pname:pSetLayouts must: be less 1938 than or equal to 1939 sname:VkPhysicalDeviceInlineUniformBlockProperties::pname:maxDescriptorSetInlineUniformBlocks 1940endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1941ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 1942 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03036]] 1943 The total number of descriptors of the type 1944 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1945 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1946 shader stages and across all elements of pname:pSetLayouts must: be less 1947 than or equal to 1948 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindSamplers 1949 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03037]] 1950 The total number of descriptors of the type 1951 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1952 stages and across all elements of pname:pSetLayouts must: be less than 1953 or equal to 1954 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindUniformBuffers 1955 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03038]] 1956 The total number of descriptors of the type 1957 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1958 shader stages and across all elements of pname:pSetLayouts must: be less 1959 than or equal to 1960 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 1961 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03039]] 1962 The total number of descriptors of the type 1963 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1964 stages and across all elements of pname:pSetLayouts must: be less than 1965 or equal to 1966 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageBuffers 1967 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03040]] 1968 The total number of descriptors of the type 1969 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1970 shader stages and across all elements of pname:pSetLayouts must: be less 1971 than or equal to 1972 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 1973 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03041]] 1974 The total number of descriptors of the type 1975 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1976 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1977 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1978 shader stages and across all elements of pname:pSetLayouts must: be less 1979 than or equal to 1980 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindSampledImages 1981 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03042]] 1982 The total number of descriptors of the type 1983 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1984 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1985 shader stages and across all elements of pname:pSetLayouts must: be less 1986 than or equal to 1987 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindStorageImages 1988 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03043]] 1989 The total number of descriptors of the type 1990 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1991 stages and across all elements of pname:pSetLayouts must: be less than 1992 or equal to 1993 sname:VkPhysicalDeviceDescriptorIndexingProperties::pname:maxDescriptorSetUpdateAfterBindInputAttachments 1994ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 1995 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02217]] 1996 The total number of bindings with a pname:descriptorType of 1997 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK accessible across all 1998 shader stages and across all elements of pname:pSetLayouts must: be less 1999 than or equal to 2000 sname:VkPhysicalDeviceInlineUniformBlockProperties::pname:maxDescriptorSetUpdateAfterBindInlineUniformBlocks 2001endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2002endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2003ifdef::VK_VERSION_1_3[] 2004 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-06531]] 2005 The total number of descriptors with a pname:descriptorType of 2006 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK accessible across all 2007 shader stages and across all elements of pname:pSetLayouts must: be less 2008 than or equal to 2009 sname:VkPhysicalDeviceVulkan13Properties::pname:maxInlineUniformTotalSize 2010endif::VK_VERSION_1_3[] 2011 * [[VUID-VkPipelineLayoutCreateInfo-pPushConstantRanges-00292]] 2012 Any two elements of pname:pPushConstantRanges must: not include the same 2013 stage in pname:stageFlags 2014ifdef::VK_KHR_push_descriptor[] 2015 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00293]] 2016 pname:pSetLayouts must: not contain more than one descriptor set layout 2017 that was created with 2018 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 2019endif::VK_KHR_push_descriptor[] 2020ifdef::VK_KHR_acceleration_structure[] 2021 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03571]] 2022 The total number of bindings in descriptor set layouts created without 2023 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 2024 set with a pname:descriptorType of 2025 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible to any 2026 given shader stage across all elements of pname:pSetLayouts must: be 2027 less than or equal to 2028 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPerStageDescriptorAccelerationStructures 2029 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03572]] 2030 The total number of bindings with a pname:descriptorType of 2031 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible to any 2032 given shader stage across all elements of pname:pSetLayouts must: be 2033 less than or equal to 2034 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxPerStageDescriptorUpdateAfterBindAccelerationStructures 2035 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03573]] 2036 The total number of bindings in descriptor set layouts created without 2037 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 2038 set with a pname:descriptorType of 2039 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible across 2040 all shader stages and across all elements of pname:pSetLayouts must: be 2041 less than or equal to 2042 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxDescriptorSetAccelerationStructures 2043 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03574]] 2044 The total number of bindings with a pname:descriptorType of 2045 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR accessible across 2046 all shader stages and across all elements of pname:pSetLayouts must: be 2047 less than or equal to 2048 slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxDescriptorSetUpdateAfterBindAccelerationStructures 2049endif::VK_KHR_acceleration_structure[] 2050ifdef::VK_NV_ray_tracing[] 2051 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-02381]] 2052 The total number of bindings with a pname:descriptorType of 2053 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV accessible across all 2054 shader stages and across all elements of pname:pSetLayouts must: be less 2055 than or equal to 2056 slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxDescriptorSetAccelerationStructures 2057endif::VK_NV_ray_tracing[] 2058ifdef::VK_EXT_fragment_density_map2[] 2059 * [[VUID-VkPipelineLayoutCreateInfo-pImmutableSamplers-03566]] 2060 The total number of pname:pImmutableSamplers created with pname:flags 2061 containing ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or 2062 ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT across 2063 all shader stages and across all elements of pname:pSetLayouts must: be 2064 less than or equal to <<limits-maxDescriptorSetSubsampledSamplers, 2065 sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:maxDescriptorSetSubsampledSamplers>> 2066endif::VK_EXT_fragment_density_map2[] 2067ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2068 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-04606]] 2069 Any element of pname:pSetLayouts must: not have been created with the 2070 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT bit set 2071endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2072 * [[VUID-VkPipelineLayoutCreateInfo-graphicsPipelineLibrary-06753]] 2073ifdef::VK_EXT_graphics_pipeline_library[] 2074 If <<features-graphicsPipelineLibrary, pname:graphicsPipelineLibrary>> 2075 is not enabled, elements 2076endif::VK_EXT_graphics_pipeline_library[] 2077ifndef::VK_EXT_graphics_pipeline_library[Elements] 2078 of pname:pSetLayouts must: be valid slink:VkDescriptorSetLayout objects 2079ifdef::VK_EXT_descriptor_buffer[] 2080 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-08008]] 2081 If any element of pname:pSetLayouts was created with the 2082 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set, 2083 all elements of pname:pSetLayouts must: have been created with the 2084 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set 2085endif::VK_EXT_descriptor_buffer[] 2086**** 2087 2088include::{generated}/validity/structs/VkPipelineLayoutCreateInfo.adoc[] 2089-- 2090 2091[open,refpage='VkPipelineLayoutCreateFlagBits',desc='Pipeline layout creation flag bits',type='enums'] 2092-- 2093include::{generated}/api/enums/VkPipelineLayoutCreateFlagBits.adoc[] 2094 2095ifndef::VK_EXT_graphics_pipeline_library[] 2096All values for this enum are defined by extensions. 2097endif::VK_EXT_graphics_pipeline_library[] 2098ifdef::VK_EXT_graphics_pipeline_library[] 2099 * ename:VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT specifies that 2100 implementations must: ensure that the properties and/or absence of a 2101 particular descriptor set do not influence any other properties of the 2102 pipeline layout. 2103 This allows pipelines libraries linked without 2104 ename:VK_PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT to be created 2105 with a subset of the total descriptor sets. 2106endif::VK_EXT_graphics_pipeline_library[] 2107-- 2108 2109[open,refpage='VkPipelineLayoutCreateFlags',desc='Bitmask of pipeline layout creation flag bits',type='flags'] 2110-- 2111include::{generated}/api/flags/VkPipelineLayoutCreateFlags.adoc[] 2112 2113tname:VkPipelineLayoutCreateFlags is a bitmask type for setting a mask of 2114elink:VkPipelineLayoutCreateFlagBits. 2115-- 2116 2117[open,refpage='VkPushConstantRange',desc='Structure specifying a push constant range',type='structs'] 2118-- 2119The sname:VkPushConstantRange structure is defined as: 2120 2121include::{generated}/api/structs/VkPushConstantRange.adoc[] 2122 2123 * pname:stageFlags is a set of stage flags describing the shader stages 2124 that will access a range of push constants. 2125 If a particular stage is not included in the range, then accessing 2126 members of that range of push constants from the corresponding shader 2127 stage will return undefined: values. 2128 * pname:offset and pname:size are the start offset and size, respectively, 2129 consumed by the range. 2130 Both pname:offset and pname:size are in units of bytes and must: be a 2131 multiple of 4. 2132 The layout of the push constant variables is specified in the shader. 2133 2134.Valid Usage 2135**** 2136 * [[VUID-VkPushConstantRange-offset-00294]] 2137 pname:offset must: be less than 2138 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 2139 * [[VUID-VkPushConstantRange-offset-00295]] 2140 pname:offset must: be a multiple of `4` 2141 * [[VUID-VkPushConstantRange-size-00296]] 2142 pname:size must: be greater than `0` 2143 * [[VUID-VkPushConstantRange-size-00297]] 2144 pname:size must: be a multiple of `4` 2145 * [[VUID-VkPushConstantRange-size-00298]] 2146 pname:size must: be less than or equal to 2147 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 2148 pname:offset 2149**** 2150 2151include::{generated}/validity/structs/VkPushConstantRange.adoc[] 2152-- 2153 2154Once created, pipeline layouts are used as part of pipeline creation (see 2155<<pipelines, Pipelines>>), as part of binding descriptor sets (see 2156<<descriptorsets-binding, Descriptor Set Binding>>), and as part of setting 2157push constants (see <<descriptorsets-push-constants, Push Constant 2158Updates>>). 2159Pipeline creation accepts a pipeline layout as input, and the layout may: be 2160used to map (set, binding, arrayElement) tuples to implementation resources 2161or memory locations within a descriptor set. 2162The assignment of implementation resources depends only on the bindings 2163defined in the descriptor sets that comprise the pipeline layout, and not on 2164any shader source. 2165 2166[[descriptorsets-pipelinelayout-consistency]] 2167All resource variables <<shaders-staticuse,statically used>> in all shaders 2168in a pipeline must: be declared with a (set, binding, arrayElement) that 2169exists in the corresponding descriptor set layout and is of an appropriate 2170descriptor type and includes the set of shader stages it is used by in 2171pname:stageFlags. 2172The pipeline layout can: include entries that are not used by a particular 2173pipeline. 2174The pipeline layout allows the application to provide a consistent set of 2175bindings across multiple pipeline compiles, which enables those pipelines to 2176be compiled in a way that the implementation may: cheaply switch pipelines 2177without reprogramming the bindings. 2178 2179Similarly, the push constant block declared in each shader (if present) 2180must: only place variables at offsets that are each included in a push 2181constant range with pname:stageFlags including the bit corresponding to the 2182shader stage that uses it. 2183The pipeline layout can: include ranges or portions of ranges that are not 2184used by a particular pipeline. 2185 2186There is a limit on the total number of resources of each type that can: be 2187included in bindings in all descriptor set layouts in a pipeline layout as 2188shown in <<descriptorsets-pipelinelayout-limits,Pipeline Layout Resource 2189Limits>>. 2190The "`Total Resources Available`" column gives the limit on the number of 2191each type of resource that can: be included in bindings in all descriptor 2192sets in the pipeline layout. 2193Some resource types count against multiple limits. 2194Additionally, there are limits on the total number of each type of resource 2195that can: be used in any pipeline stage as described in 2196<<interfaces-resources-limits,Shader Resource Limits>>. 2197 2198[[descriptorsets-pipelinelayout-limits]] 2199.Pipeline Layout Resource Limits 2200[width="80%",cols="<37,<22",options="header"] 2201|==== 2202| Total Resources Available | Resource Types 2203.2+<.^| pname:maxDescriptorSetSamplers 2204ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2205or pname:maxDescriptorSetUpdateAfterBindSamplers 2206endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2207 | sampler | combined image sampler 2208.3+<.^| pname:maxDescriptorSetSampledImages 2209ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2210or pname:maxDescriptorSetUpdateAfterBindSampledImages 2211endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2212 | sampled image | combined image sampler | uniform texel buffer 2213.2+<.^| pname:maxDescriptorSetStorageImages 2214ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2215or pname:maxDescriptorSetUpdateAfterBindStorageImages 2216endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2217 | storage image | storage texel buffer 2218.2+<.^| pname:maxDescriptorSetUniformBuffers 2219ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2220or pname:maxDescriptorSetUpdateAfterBindUniformBuffers 2221endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2222 | uniform buffer | uniform buffer dynamic 2223| pname:maxDescriptorSetUniformBuffersDynamic 2224ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2225or pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 2226endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2227 | uniform buffer dynamic 2228.2+<.^| pname:maxDescriptorSetStorageBuffers 2229ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2230or pname:maxDescriptorSetUpdateAfterBindStorageBuffers 2231endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2232 | storage buffer | storage buffer dynamic 2233| pname:maxDescriptorSetStorageBuffersDynamic 2234ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2235or pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 2236endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2237 | storage buffer dynamic 2238| pname:maxDescriptorSetInputAttachments 2239ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2240or pname:maxDescriptorSetUpdateAfterBindInputAttachments 2241endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2242 | input attachment 2243ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2244| pname:maxDescriptorSetInlineUniformBlocks 2245ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2246or pname:maxDescriptorSetUpdateAfterBindInlineUniformBlocks 2247endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2248 | inline uniform block 2249endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2250ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2251| pname:maxDescriptorSetAccelerationStructures 2252ifdef::VK_KHR_acceleration_structure[] 2253or pname:maxDescriptorSetUpdateAfterBindAccelerationStructures 2254endif::VK_KHR_acceleration_structure[] 2255 | acceleration structure 2256endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 2257|==== 2258 2259 2260[open,refpage='vkDestroyPipelineLayout',desc='Destroy a pipeline layout object',type='protos'] 2261-- 2262To destroy a pipeline layout, call: 2263 2264include::{generated}/api/protos/vkDestroyPipelineLayout.adoc[] 2265 2266 * pname:device is the logical device that destroys the pipeline layout. 2267 * pname:pipelineLayout is the pipeline layout to destroy. 2268 * pname:pAllocator controls host memory allocation as described in the 2269 <<memory-allocation, Memory Allocation>> chapter. 2270 2271.Valid Usage 2272**** 2273ifndef::VKSC_VERSION_1_0[] 2274 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00299]] 2275 If sname:VkAllocationCallbacks were provided when pname:pipelineLayout 2276 was created, a compatible set of callbacks must: be provided here 2277 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00300]] 2278 If no sname:VkAllocationCallbacks were provided when 2279 pname:pipelineLayout was created, pname:pAllocator must: be `NULL` 2280endif::VKSC_VERSION_1_0[] 2281 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-02004]] 2282 pname:pipelineLayout must: not have been passed to any ftext:vkCmd* 2283 command for any command buffers that are still in the 2284 <<commandbuffers-lifecycle, recording state>> when 2285 fname:vkDestroyPipelineLayout is called 2286**** 2287 2288include::{generated}/validity/protos/vkDestroyPipelineLayout.adoc[] 2289-- 2290 2291 2292[[descriptorsets-compatibility]] 2293==== Pipeline Layout Compatibility 2294 2295Two pipeline layouts are defined to be "`compatible for 2296<<descriptorsets-push-constants, push constants>>`" if they were created 2297with identical push constant ranges. 2298Two pipeline layouts are defined to be "`compatible for set N`" if they were 2299created with _identically defined_ descriptor set layouts for sets zero 2300through N, 2301ifdef::VK_EXT_graphics_pipeline_library[] 2302if both of them either were or were not created with 2303ename:VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT, 2304endif::VK_EXT_graphics_pipeline_library[] 2305and if they were created with identical push constant ranges. 2306 2307When binding a descriptor set (see <<descriptorsets-binding, Descriptor Set 2308Binding>>) to set number N, a previously bound descriptor set bound with 2309lower index M than N is disturbed if the pipeline layouts for set M and N 2310are not compatible for set M. Otherwise, the bound descriptor set in M is 2311not disturbed. 2312 2313If, additionally, the previously bound descriptor set for set N was bound 2314using a pipeline layout not compatible for set N, then all bindings in sets 2315numbered greater than N are disturbed. 2316 2317When binding a pipeline, the pipeline can: correctly access any previously 2318bound descriptor set N if it was bound with compatible pipeline layout for 2319set N, and it was not disturbed. 2320 2321Layout compatibility means that descriptor sets can: be bound to a command 2322buffer for use by any pipeline created with a compatible pipeline layout, 2323and without having bound a particular pipeline first. 2324It also means that descriptor sets can: remain valid across a pipeline 2325change, and the same resources will be accessible to the newly bound 2326pipeline. 2327 2328When a descriptor set is disturbed by binding descriptor sets, the disturbed 2329set is considered to contain undefined: descriptors bound with the same 2330pipeline layout as the disturbing descriptor set. 2331 2332ifdef::implementation-guide[] 2333.Implementor's Note 2334**** 2335A consequence of layout compatibility is that when the implementation 2336compiles a pipeline layout and maps pipeline resources to implementation 2337resources, the mechanism for set N should: only be a function of sets 2338[0..N]. 2339**** 2340endif::implementation-guide[] 2341 2342 2343[NOTE] 2344.Note 2345==== 2346Place the least frequently changing descriptor sets near the start of the 2347pipeline layout, and place the descriptor sets representing the most 2348frequently changing resources near the end. 2349When pipelines are switched, only the descriptor set bindings that have been 2350invalidated will need to be updated and the remainder of the descriptor set 2351bindings will remain in place. 2352==== 2353 2354The maximum number of descriptor sets that can: be bound to a pipeline 2355layout is queried from physical device properties (see 2356pname:maxBoundDescriptorSets in <<limits, Limits>>). 2357 2358.API example 2359[source,c++] 2360---- 2361const VkDescriptorSetLayout layouts[] = { layout1, layout2 }; 2362 2363const VkPushConstantRange ranges[] = 2364{ 2365 { 2366 .stageFlags = VK_SHADER_STAGE_VERTEX_BIT, 2367 .offset = 0, 2368 .size = 4 2369 }, 2370 { 2371 .stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT, 2372 .offset = 4, 2373 .size = 4 2374 }, 2375}; 2376 2377const VkPipelineLayoutCreateInfo createInfo = 2378{ 2379 .sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO, 2380 .pNext = NULL, 2381 .flags = 0, 2382 .setLayoutCount = 2, 2383 .pSetLayouts = layouts, 2384 .pushConstantRangeCount = 2, 2385 .pPushConstantRanges = ranges 2386}; 2387 2388VkPipelineLayout myPipelineLayout; 2389myResult = vkCreatePipelineLayout( 2390 myDevice, 2391 &createInfo, 2392 NULL, 2393 &myPipelineLayout); 2394---- 2395 2396 2397[[descriptorsets-allocation]] 2398=== Allocation of Descriptor Sets 2399 2400[open,refpage='VkDescriptorPool',desc='Opaque handle to a descriptor pool object',type='handles'] 2401-- 2402A _descriptor pool_ maintains a pool of descriptors, from which descriptor 2403sets are allocated. 2404Descriptor pools are externally synchronized, meaning that the application 2405must: not allocate and/or free descriptor sets from the same pool in 2406multiple threads simultaneously. 2407 2408Descriptor pools are represented by sname:VkDescriptorPool handles: 2409 2410include::{generated}/api/handles/VkDescriptorPool.adoc[] 2411-- 2412 2413[open,refpage='vkCreateDescriptorPool',desc='Creates a descriptor pool object',type='protos'] 2414-- 2415:refpage: vkCreateDescriptorPool 2416:objectnameplural: descriptor pools 2417:objectnamecamelcase: descriptorPool 2418:objectcount: 1 2419 2420To create a descriptor pool object, call: 2421 2422include::{generated}/api/protos/vkCreateDescriptorPool.adoc[] 2423 2424 * pname:device is the logical device that creates the descriptor pool. 2425 * pname:pCreateInfo is a pointer to a slink:VkDescriptorPoolCreateInfo 2426 structure specifying the state of the descriptor pool object. 2427 * pname:pAllocator controls host memory allocation as described in the 2428 <<memory-allocation, Memory Allocation>> chapter. 2429 * pname:pDescriptorPool is a pointer to a slink:VkDescriptorPool handle in 2430 which the resulting descriptor pool object is returned. 2431 2432The created descriptor pool is returned in pname:pDescriptorPool. 2433 2434include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 2435 2436ifdef::VKSC_VERSION_1_0[] 2437.Valid Usage 2438**** 2439include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 2440**** 2441endif::VKSC_VERSION_1_0[] 2442 2443include::{generated}/validity/protos/vkCreateDescriptorPool.adoc[] 2444-- 2445 2446[open,refpage='VkDescriptorPoolCreateInfo',desc='Structure specifying parameters of a newly created descriptor pool',type='structs'] 2447-- 2448Additional information about the pool is passed in a 2449sname:VkDescriptorPoolCreateInfo structure: 2450 2451include::{generated}/api/structs/VkDescriptorPoolCreateInfo.adoc[] 2452 2453 * pname:sType is a elink:VkStructureType value identifying this structure. 2454 * pname:pNext is `NULL` or a pointer to a structure extending this 2455 structure. 2456 * pname:flags is a bitmask of elink:VkDescriptorPoolCreateFlagBits 2457 specifying certain supported operations on the pool. 2458 * pname:maxSets is the maximum number of descriptor sets that can: be 2459 allocated from the pool. 2460 * pname:poolSizeCount is the number of elements in pname:pPoolSizes. 2461 * pname:pPoolSizes is a pointer to an array of slink:VkDescriptorPoolSize 2462 structures, each containing a descriptor type and number of descriptors 2463 of that type to be allocated in the pool. 2464 2465If multiple sname:VkDescriptorPoolSize structures containing the same 2466descriptor type appear in the pname:pPoolSizes array then the pool will be 2467created with enough storage for the total number of descriptors of each 2468type. 2469 2470Fragmentation of a descriptor pool is possible and may: lead to descriptor 2471set allocation failures. 2472A failure due to fragmentation is defined as failing a descriptor set 2473allocation despite the sum of all outstanding descriptor set allocations 2474from the pool plus the requested allocation requiring no more than the total 2475number of descriptors requested at pool creation. 2476Implementations provide certain guarantees of when fragmentation must: not 2477cause allocation failure, as described below. 2478 2479If a descriptor pool has not had any descriptor sets freed since it was 2480created or most recently reset then fragmentation must: not cause an 2481allocation failure (note that this is always the case for a pool created 2482without the ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT bit 2483set). 2484Additionally, if all sets allocated from the pool since it was created or 2485most recently reset use the same number of descriptors (of each type) and 2486the requested allocation also uses that same number of descriptors (of each 2487type), then fragmentation must: not cause an allocation failure. 2488 2489If an allocation failure occurs due to fragmentation, an application can: 2490create an additional descriptor pool to perform further descriptor set 2491allocations. 2492 2493ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2494If pname:flags has the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT 2495bit set, descriptor pool creation may: fail with the error 2496ename:VK_ERROR_FRAGMENTATION if the total number of descriptors across all 2497pools (including this one) created with this bit set exceeds 2498pname:maxUpdateAfterBindDescriptorsInAllPools, or if fragmentation of the 2499underlying hardware resources occurs. 2500endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2501 2502ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2503If a pname:pPoolSizes[i]::pname:type is 2504ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, a 2505slink:VkMutableDescriptorTypeCreateInfoEXT struct in the pname:pNext chain 2506can: be used to specify which mutable descriptor types can: be allocated 2507from the pool. 2508If included in the pname:pNext chain, 2509slink:VkMutableDescriptorTypeCreateInfoEXT::pname:pMutableDescriptorTypeLists[i] 2510specifies which kind of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT descriptors 2511can: be allocated from this pool entry. 2512If slink:VkMutableDescriptorTypeCreateInfoEXT does not exist in the 2513pname:pNext chain, or 2514slink:VkMutableDescriptorTypeCreateInfoEXT::pname:pMutableDescriptorTypeLists[i] 2515is out of range, the descriptor pool allocates enough memory to be able to 2516allocate a ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT descriptor with any 2517supported elink:VkDescriptorType as a mutable descriptor. 2518A mutable descriptor can: be allocated from a pool entry if the type list in 2519slink:VkDescriptorSetLayoutCreateInfo is a subset of the type list declared 2520in the descriptor pool, or if the pool entry is created without a descriptor 2521type list. 2522Multiple pname:pPoolSizes entries with ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 2523can: be declared. 2524When multiple such pool entries are present in pname:pPoolSizes, they 2525specify sets of supported descriptor types which either fully overlap, 2526partially overlap, or are disjoint. 2527Two sets fully overlap if the sets of supported descriptor types are equal. 2528If the sets are not disjoint they partially overlap. 2529A pool entry without a sname:VkMutableDescriptorTypeListEXT assigned to it 2530is considered to partially overlap any other pool entry which has a 2531sname:VkMutableDescriptorTypeListEXT assigned to it. 2532The application must: ensure that partial overlap does not exist in 2533pname:pPoolSizes. 2534 2535[NOTE] 2536.Note 2537==== 2538The requirement of no partial overlap is intended to resolve ambiguity for 2539validation as there is no confusion which pname:pPoolSizes entries will be 2540allocated from. 2541An implementation is not expected to depend on this requirement. 2542==== 2543endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2544 2545.Valid Usage 2546**** 2547 * [[VUID-VkDescriptorPoolCreateInfo-descriptorPoolOverallocation-09227]] 2548ifdef::VK_NV_descriptor_pool_overallocation[] 2549 If the <<features-descriptorPoolOverallocation, 2550 pname:descriptorPoolOverallocation>> feature is not enabled, or 2551 pname:flags does not have 2552 ename:VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV set, 2553endif::VK_NV_descriptor_pool_overallocation[] 2554 pname:maxSets must: be greater than `0` 2555ifdef::VK_NV_descriptor_pool_overallocation[] 2556 * [[VUID-VkDescriptorPoolCreateInfo-flags-09228]] 2557 If pname:flags has the 2558 ename:VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV or 2559 ename:VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NV bits 2560 set, then <<features-descriptorPoolOverallocation, 2561 pname:descriptorPoolOverallocation>> must: be enabled 2562endif::VK_NV_descriptor_pool_overallocation[] 2563ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2564ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2565 * [[VUID-VkDescriptorPoolCreateInfo-flags-04607]] 2566 If pname:flags has the ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT 2567 bit set, then the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT 2568 bit must: not be set 2569endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2570endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2571ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2572 * [[VUID-VkDescriptorPoolCreateInfo-mutableDescriptorType-04608]] 2573 If 2574 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT::pname:mutableDescriptorType 2575 is not enabled, pname:pPoolSizes must: not contain a 2576 pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 2577 * [[VUID-VkDescriptorPoolCreateInfo-flags-04609]] 2578 If pname:flags has the ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT 2579 bit set, 2580 slink:VkPhysicalDeviceMutableDescriptorTypeFeaturesEXT::pname:mutableDescriptorType 2581 must: be enabled 2582 * [[VUID-VkDescriptorPoolCreateInfo-pPoolSizes-04787]] 2583 If pname:pPoolSizes contains a pname:descriptorType of 2584 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, any other 2585 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT element in pname:pPoolSizes must: 2586 not have sets of supported descriptor types which partially overlap 2587endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2588**** 2589 2590include::{generated}/validity/structs/VkDescriptorPoolCreateInfo.adoc[] 2591-- 2592 2593ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2594[open,refpage='VkDescriptorPoolInlineUniformBlockCreateInfo',desc='Structure specifying the maximum number of inline uniform block bindings of a newly created descriptor pool',type='structs',alias='VkDescriptorPoolInlineUniformBlockCreateInfoEXT'] 2595-- 2596In order to be able to allocate descriptor sets having 2597<<descriptorsets-inlineuniformblock, inline uniform block>> bindings the 2598descriptor pool must: be created with specifying the inline uniform block 2599binding capacity of the descriptor pool, in addition to the total inline 2600uniform data capacity in bytes which is specified through a 2601slink:VkDescriptorPoolSize structure with a pname:descriptorType value of 2602ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK. 2603This can: be done by adding a 2604sname:VkDescriptorPoolInlineUniformBlockCreateInfo structure to the 2605pname:pNext chain of slink:VkDescriptorPoolCreateInfo. 2606 2607The sname:VkDescriptorPoolInlineUniformBlockCreateInfo structure is defined 2608as: 2609 2610include::{generated}/api/structs/VkDescriptorPoolInlineUniformBlockCreateInfo.adoc[] 2611 2612ifdef::VK_EXT_inline_uniform_block[] 2613or the equivalent 2614 2615include::{generated}/api/structs/VkDescriptorPoolInlineUniformBlockCreateInfoEXT.adoc[] 2616endif::VK_EXT_inline_uniform_block[] 2617 2618 * pname:sType is a elink:VkStructureType value identifying this structure. 2619 * pname:pNext is `NULL` or a pointer to a structure extending this 2620 structure. 2621 * pname:maxInlineUniformBlockBindings is the number of inline uniform 2622 block bindings to allocate. 2623 2624include::{generated}/validity/structs/VkDescriptorPoolInlineUniformBlockCreateInfo.adoc[] 2625-- 2626endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2627 2628[open,refpage='VkDescriptorPoolCreateFlagBits',desc='Bitmask specifying certain supported operations on a descriptor pool',type='enums'] 2629-- 2630Bits which can: be set in slink:VkDescriptorPoolCreateInfo::pname:flags, 2631enabling operations on a descriptor pool, are: 2632 2633include::{generated}/api/enums/VkDescriptorPoolCreateFlagBits.adoc[] 2634 2635 * ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT specifies that 2636 descriptor sets can: return their individual allocations to the pool, 2637 i.e. all of flink:vkAllocateDescriptorSets, flink:vkFreeDescriptorSets, 2638 and flink:vkResetDescriptorPool are allowed. 2639 Otherwise, descriptor sets allocated from the pool must: not be 2640 individually freed back to the pool, i.e. only 2641 flink:vkAllocateDescriptorSets and flink:vkResetDescriptorPool are 2642 allowed. 2643ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2644 * ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT specifies that 2645 descriptor sets allocated from this pool can: include bindings with the 2646 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set. 2647 It is valid to allocate descriptor sets that have bindings that do not 2648 set the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit from a 2649 pool that has ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT set. 2650endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2651ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2652 * ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT specifies that this 2653 descriptor pool and the descriptor sets allocated from it reside 2654 entirely in host memory and cannot be bound. 2655 Similar to descriptor sets allocated without this flag, applications 2656 can: copy-from and copy-to descriptors sets allocated from this 2657 descriptor pool. 2658 Descriptor sets allocated from this pool are partially exempt from the 2659 external synchronization requirement in 2660ifdef::VK_KHR_descriptor_update_template[] 2661 flink:vkUpdateDescriptorSetWithTemplateKHR and 2662endif::VK_KHR_descriptor_update_template[] 2663 flink:vkUpdateDescriptorSets. 2664 Descriptor sets and their descriptors can be updated concurrently in 2665 different threads, though the same descriptor must: not be updated 2666 concurrently by two threads. 2667endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2668ifdef::VK_NV_descriptor_pool_overallocation[] 2669 * ename:VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_SETS_BIT_NV 2670 specifies that the implementation should allow the application to 2671 allocate more than slink:VkDescriptorPoolCreateInfo::pname:maxSets 2672 descriptor set objects from the descriptor pool as available resources 2673 allow. 2674 The implementation may: use the pname:maxSets value to allocate the 2675 initial available sets, but using zero is permitted. 2676 * ename:VK_DESCRIPTOR_POOL_CREATE_ALLOW_OVERALLOCATION_POOLS_BIT_NV 2677 specifies that the implementation should allow the application to 2678 allocate more descriptors from the pool than was specified by the 2679 slink:VkDescriptorPoolSize::pname:descriptorCount for any descriptor 2680 type as specified by 2681 slink:VkDescriptorPoolCreateInfo::pname:poolSizeCount and 2682 slink:VkDescriptorPoolCreateInfo::pname:pPoolSizes, as available 2683 resources allow. 2684 The implementation may: use the pname:descriptorCount for each 2685 descriptor type to allocate the initial pool, but the application is 2686 allowed to set the pname:poolSizeCount to zero, or any of the 2687 pname:descriptorCount values in the pname:pPoolSizes array to zero. 2688endif::VK_NV_descriptor_pool_overallocation[] 2689-- 2690 2691[open,refpage='VkDescriptorPoolCreateFlags',desc='Bitmask of VkDescriptorPoolCreateFlagBits',type='flags'] 2692-- 2693include::{generated}/api/flags/VkDescriptorPoolCreateFlags.adoc[] 2694 2695tname:VkDescriptorPoolCreateFlags is a bitmask type for setting a mask of 2696zero or more elink:VkDescriptorPoolCreateFlagBits. 2697-- 2698 2699[open,refpage='VkDescriptorPoolSize',desc='Structure specifying descriptor pool size',type='structs'] 2700-- 2701The sname:VkDescriptorPoolSize structure is defined as: 2702 2703include::{generated}/api/structs/VkDescriptorPoolSize.adoc[] 2704 2705 * pname:type is the type of descriptor. 2706 * pname:descriptorCount is the number of descriptors of that type to 2707 allocate. 2708ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2709 If pname:type is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 2710 pname:descriptorCount is the number of bytes to allocate for descriptors 2711 of this type. 2712endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2713 2714ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2715[NOTE] 2716.Note 2717==== 2718When creating a descriptor pool that will contain descriptors for combined 2719image samplers of multi-planar formats, an application needs to account for 2720non-trivial descriptor consumption when choosing the pname:descriptorCount 2721value, as indicated by 2722slink:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount. 2723==== 2724endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2725 2726.Valid Usage 2727**** 2728 * [[VUID-VkDescriptorPoolSize-descriptorCount-00302]] 2729 pname:descriptorCount must: be greater than `0` 2730ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2731 * [[VUID-VkDescriptorPoolSize-type-02218]] 2732 If pname:type is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 2733 pname:descriptorCount must: be a multiple of `4` 2734endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2735**** 2736 2737include::{generated}/validity/structs/VkDescriptorPoolSize.adoc[] 2738-- 2739 2740ifdef::VKSC_VERSION_1_0[] 2741ifdef::hidden[] 2742// tag::scremoved[] 2743 * fname:vkDestroyDescriptorPool <<SCID-4>> 2744// end::scremoved[] 2745endif::hidden[] 2746 2747Descriptor pools cannot: be destroyed <<SCID-4>>. 2748If 2749slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> 2750is ename:VK_TRUE, the memory is returned to the system when the device is 2751destroyed. 2752 2753endif::VKSC_VERSION_1_0[] 2754ifndef::VKSC_VERSION_1_0[] 2755 2756[open,refpage='vkDestroyDescriptorPool',desc='Destroy a descriptor pool object',type='protos'] 2757-- 2758To destroy a descriptor pool, call: 2759 2760include::{generated}/api/protos/vkDestroyDescriptorPool.adoc[] 2761 2762 * pname:device is the logical device that destroys the descriptor pool. 2763 * pname:descriptorPool is the descriptor pool to destroy. 2764 * pname:pAllocator controls host memory allocation as described in the 2765 <<memory-allocation, Memory Allocation>> chapter. 2766 2767When a pool is destroyed, all descriptor sets allocated from the pool are 2768implicitly freed and become invalid. 2769Descriptor sets allocated from a given pool do not need to be freed before 2770destroying that descriptor pool. 2771 2772.Valid Usage 2773**** 2774 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00303]] 2775 All submitted commands that refer to pname:descriptorPool (via any 2776 allocated descriptor sets) must: have completed execution 2777 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00304]] 2778 If sname:VkAllocationCallbacks were provided when pname:descriptorPool 2779 was created, a compatible set of callbacks must: be provided here 2780 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00305]] 2781 If no sname:VkAllocationCallbacks were provided when 2782 pname:descriptorPool was created, pname:pAllocator must: be `NULL` 2783**** 2784 2785include::{generated}/validity/protos/vkDestroyDescriptorPool.adoc[] 2786-- 2787 2788endif::VKSC_VERSION_1_0[] 2789 2790[open,refpage='VkDescriptorSet',desc='Opaque handle to a descriptor set object',type='handles'] 2791-- 2792Descriptor sets are allocated from descriptor pool objects, and are 2793represented by sname:VkDescriptorSet handles: 2794 2795include::{generated}/api/handles/VkDescriptorSet.adoc[] 2796-- 2797 2798[open,refpage='vkAllocateDescriptorSets',desc='Allocate one or more descriptor sets',type='protos'] 2799-- 2800:refpage: vkAllocateDescriptorSets 2801:objectnameplural: descriptor sets 2802:objectnamecamelcase: descriptorSet 2803:objectcount: slink:VkDescriptorSetAllocateInfo::pname:descriptorSetCount 2804 2805To allocate descriptor sets from a descriptor pool, call: 2806 2807include::{generated}/api/protos/vkAllocateDescriptorSets.adoc[] 2808 2809 * pname:device is the logical device that owns the descriptor pool. 2810 * pname:pAllocateInfo is a pointer to a slink:VkDescriptorSetAllocateInfo 2811 structure describing parameters of the allocation. 2812 * pname:pDescriptorSets is a pointer to an array of slink:VkDescriptorSet 2813 handles in which the resulting descriptor set objects are returned. 2814 2815The allocated descriptor sets are returned in pname:pDescriptorSets. 2816 2817[[descriptor-set-initial-state]] 2818When a descriptor set is allocated, the initial state is largely 2819uninitialized and all descriptors are undefined:, with the exception that 2820samplers with a non-null pname:pImmutableSamplers are initialized on 2821allocation. 2822Descriptors also become undefined: if the underlying resource or view object 2823is destroyed. 2824Descriptor sets containing undefined: descriptors can: still be bound and 2825used, subject to the following conditions: 2826 2827ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2828 * For descriptor set bindings created with the 2829 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT bit set, all descriptors 2830 in that binding that are dynamically used must: have been populated 2831 before the descriptor set is <<descriptorsets-binding,consumed>>. 2832 * For descriptor set bindings created without the 2833 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT bit set, all descriptors 2834 in that binding that are statically used must: have been populated 2835 before the descriptor set is <<descriptorsets-binding,consumed>>. 2836endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2837ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2838 * Descriptors that are <<shaders-staticuse,statically used>> must: have 2839 been populated before the descriptor set is 2840 <<descriptorsets-binding,consumed>>. 2841endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2842ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2843 * Descriptor bindings with descriptor type of 2844 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK can: be undefined: when 2845 the descriptor set is <<descriptorsets-binding,consumed>>; though values 2846 in that block will be undefined:. 2847endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2848 * Entries that are not used by a pipeline can: have undefined: 2849 descriptors. 2850 2851ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2852If a call to fname:vkAllocateDescriptorSets would cause the total number of 2853descriptor sets allocated from the pool to exceed the value of 2854slink:VkDescriptorPoolCreateInfo::pname:maxSets used to create 2855pname:pAllocateInfo->descriptorPool, then the allocation may: fail due to 2856lack of space in the descriptor pool. 2857Similarly, the allocation may: fail due to lack of space if the call to 2858fname:vkAllocateDescriptorSets would cause the number of any given 2859descriptor type to exceed the sum of all the pname:descriptorCount members 2860of each element of slink:VkDescriptorPoolCreateInfo::pname:pPoolSizes with a 2861pname:type equal to that type. 2862 2863ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2864Additionally, the allocation may: also fail if a call to 2865fname:vkAllocateDescriptorSets would cause the total number of inline 2866uniform block bindings allocated from the pool to exceed the value of 2867slink:VkDescriptorPoolInlineUniformBlockCreateInfo::pname:maxInlineUniformBlockBindings 2868used to create the descriptor pool. 2869endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 2870 2871If the allocation fails due to no more space in the descriptor pool, and not 2872because of system or device memory exhaustion, then 2873ename:VK_ERROR_OUT_OF_POOL_MEMORY must: be returned. 2874endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2875 2876ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2877If an allocation fails due to fragmentation, an indeterminate error is 2878returned with an unspecified error code. 2879Any returned error other than 2880ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2881ename:VK_ERROR_OUT_OF_POOL_MEMORY or 2882endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2883ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: 2884applications should: assume that the allocation failed due to fragmentation, 2885and create a new descriptor pool. 2886endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2887 2888ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2889fname:vkAllocateDescriptorSets can: be used to create multiple descriptor 2890sets. 2891If the creation of any of those descriptor sets fails, then the 2892implementation must: destroy all successfully created descriptor set objects 2893from this command, set all entries of the pname:pDescriptorSets array to 2894dlink:VK_NULL_HANDLE and return the error. 2895endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2896 2897ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 2898[NOTE] 2899.Note 2900==== 2901Applications should: check for a negative return value when allocating new 2902descriptor sets, assume that any error 2903ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2904other than ename:VK_ERROR_OUT_OF_POOL_MEMORY 2905endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2906effectively means ename:VK_ERROR_FRAGMENTED_POOL, and try to create a new 2907descriptor pool. 2908If ename:VK_ERROR_FRAGMENTED_POOL is the actual return value, it adds 2909certainty to that decision. 2910 2911The reason for this is that ename:VK_ERROR_FRAGMENTED_POOL was only added in 2912a later version of the 1.0 specification, and so drivers may: return other 2913errors if they were written against earlier versions. 2914To ensure full compatibility with earlier patch versions, these other errors 2915are allowed. 2916==== 2917endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2918 2919include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 2920 2921ifdef::VKSC_VERSION_1_0[] 2922.Valid Usage 2923**** 2924include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 2925**** 2926endif::VKSC_VERSION_1_0[] 2927 2928include::{generated}/validity/protos/vkAllocateDescriptorSets.adoc[] 2929-- 2930 2931[open,refpage='VkDescriptorSetAllocateInfo',desc='Structure specifying the allocation parameters for descriptor sets',type='structs'] 2932-- 2933The sname:VkDescriptorSetAllocateInfo structure is defined as: 2934 2935include::{generated}/api/structs/VkDescriptorSetAllocateInfo.adoc[] 2936 2937 * pname:sType is a elink:VkStructureType value identifying this structure. 2938 * pname:pNext is `NULL` or a pointer to a structure extending this 2939 structure. 2940 * pname:descriptorPool is the pool which the sets will be allocated from. 2941 * pname:descriptorSetCount determines the number of descriptor sets to be 2942 allocated from the pool. 2943 * pname:pSetLayouts is a pointer to an array of descriptor set layouts, 2944 with each member specifying how the corresponding descriptor set is 2945 allocated. 2946 2947.Valid Usage 2948**** 2949ifndef::VKSC_VERSION_1_0[] 2950 * [[VUID-VkDescriptorSetAllocateInfo-apiVersion-07895]] 2951ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2952 If the apiext:VK_KHR_maintenance1 extension is not enabled and 2953 slink:VkPhysicalDeviceProperties::pname:apiVersion is less than Vulkan 2954 1.1, 2955endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2956 pname:descriptorSetCount must: not be greater than the number of sets 2957 that are currently available for allocation in pname:descriptorPool 2958 * [[VUID-VkDescriptorSetAllocateInfo-apiVersion-07896]] 2959ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2960 If the apiext:VK_KHR_maintenance1 extension is not enabled and 2961 slink:VkPhysicalDeviceProperties::pname:apiVersion is less than Vulkan 2962 1.1, 2963endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2964 pname:descriptorPool must: have enough free descriptor capacity 2965 remaining to allocate the descriptor sets of the specified layouts 2966endif::VKSC_VERSION_1_0[] 2967ifdef::VK_KHR_push_descriptor[] 2968 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-00308]] 2969 Each element of pname:pSetLayouts must: not have been created with 2970 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 2971endif::VK_KHR_push_descriptor[] 2972ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2973 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-03044]] 2974 If any element of pname:pSetLayouts was created with the 2975 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT bit 2976 set, pname:descriptorPool must: have been created with the 2977 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 2978 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-09380]] 2979 If pname:pSetLayouts[i] was created with an element of 2980 pname:pBindingFlags that includes 2981 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, and 2982 slink:VkDescriptorSetVariableDescriptorCountAllocateInfo is included in 2983 the pname:pNext chain, and 2984 sname:VkDescriptorSetVariableDescriptorCountAllocateInfo::pname:descriptorSetCount 2985 is not zero, then 2986 slink:VkDescriptorSetVariableDescriptorCountAllocateInfo::pDescriptorCounts[i] 2987 must: be less than or equal to 2988 slink:VkDescriptorSetLayoutBinding::descriptorCount for the 2989 corresponding binding used to create pname:pSetLayouts[i] 2990endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 2991ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2992 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-04610]] 2993 If any element of pname:pSetLayouts was created with the 2994 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT bit set, 2995 pname:descriptorPool must: have been created with the 2996 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT flag set 2997endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 2998ifdef::VK_EXT_descriptor_buffer[] 2999 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-08009]] 3000 Each element of pname:pSetLayouts must: not have been created with the 3001 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set 3002endif::VK_EXT_descriptor_buffer[] 3003**** 3004 3005include::{generated}/validity/structs/VkDescriptorSetAllocateInfo.adoc[] 3006-- 3007 3008ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3009[open,refpage='VkDescriptorSetVariableDescriptorCountAllocateInfo',desc='Structure specifying additional allocation parameters for descriptor sets',type='structs',alias='VkDescriptorSetVariableDescriptorCountAllocateInfoEXT'] 3010-- 3011If the pname:pNext chain of a slink:VkDescriptorSetAllocateInfo structure 3012includes a sname:VkDescriptorSetVariableDescriptorCountAllocateInfo 3013structure, then that structure includes an array of descriptor counts for 3014variable-sized descriptor bindings, one for each descriptor set being 3015allocated. 3016 3017The sname:VkDescriptorSetVariableDescriptorCountAllocateInfo structure is 3018defined as: 3019 3020include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountAllocateInfo.adoc[] 3021 3022ifdef::VK_EXT_descriptor_indexing[] 3023or the equivalent 3024 3025include::{generated}/api/structs/VkDescriptorSetVariableDescriptorCountAllocateInfoEXT.adoc[] 3026endif::VK_EXT_descriptor_indexing[] 3027 3028 * pname:sType is a elink:VkStructureType value identifying this structure. 3029 * pname:pNext is `NULL` or a pointer to a structure extending this 3030 structure. 3031 * pname:descriptorSetCount is zero or the number of elements in 3032 pname:pDescriptorCounts. 3033 * pname:pDescriptorCounts is a pointer to an array of descriptor counts, 3034 with each member specifying the number of descriptors in a 3035 variable-sized descriptor binding in the corresponding descriptor set 3036 being allocated. 3037 3038If pname:descriptorSetCount is zero or this structure is not included in the 3039pname:pNext chain, then the variable lengths are considered to be zero. 3040Otherwise, pname:pDescriptorCounts[i] is the number of descriptors in the 3041variable-sized descriptor binding in the corresponding descriptor set 3042layout. 3043ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3044If the variable-sized descriptor binding in the corresponding descriptor set 3045layout has a descriptor type of 3046ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 3047pname:pDescriptorCounts[i] specifies the binding's capacity in bytes. 3048endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3049If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] does not include 3050a variable-sized descriptor binding, then pname:pDescriptorCounts[i] is 3051ignored. 3052 3053.Valid Usage 3054**** 3055 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfo-descriptorSetCount-03045]] 3056 If pname:descriptorSetCount is not zero, pname:descriptorSetCount must: 3057 equal slink:VkDescriptorSetAllocateInfo::pname:descriptorSetCount 3058 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfo-pSetLayouts-03046]] 3059 If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] has a 3060 variable-sized descriptor binding, then pname:pDescriptorCounts[i] must: 3061 be less than or equal to the descriptor count specified for that binding 3062 when the descriptor set layout was created 3063**** 3064 3065include::{generated}/validity/structs/VkDescriptorSetVariableDescriptorCountAllocateInfo.adoc[] 3066-- 3067endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3068 3069[open,refpage='vkFreeDescriptorSets',desc='Free one or more descriptor sets',type='protos'] 3070-- 3071To free allocated descriptor sets, call: 3072 3073include::{generated}/api/protos/vkFreeDescriptorSets.adoc[] 3074 3075 * pname:device is the logical device that owns the descriptor pool. 3076 * pname:descriptorPool is the descriptor pool from which the descriptor 3077 sets were allocated. 3078 * pname:descriptorSetCount is the number of elements in the 3079 pname:pDescriptorSets array. 3080 * pname:pDescriptorSets is a pointer to an array of handles to 3081 slink:VkDescriptorSet objects. 3082 3083After calling fname:vkFreeDescriptorSets, all descriptor sets in 3084pname:pDescriptorSets are invalid. 3085 3086ifdef::VKSC_VERSION_1_0[] 3087If <<limits-recycleDescriptorSetMemory,recycleDescriptorSetMemory>> is 3088ename:VK_FALSE, then freeing a descriptor set does not make the pool memory 3089it used available to be reallocated until the descriptor pool is reset. 3090If <<limits-recycleDescriptorSetMemory,recycleDescriptorSetMemory>> is 3091ename:VK_TRUE, then the memory is available to be reallocated immediately 3092after freeing the descriptor set. 3093ifdef::hidden[] 3094// tag::scdeviation[] 3095 * If <<limits-recycleDescriptorSetMemory,recycleDescriptorSetMemory>> is 3096 ename:VK_FALSE, then freeing a descriptor set does not make the pool 3097 memory it used available to be reallocated until the descriptor pool is 3098 reset <<SCID-4>>. 3099// end::scdeviation[] 3100endif::hidden[] 3101endif::VKSC_VERSION_1_0[] 3102 3103.Valid Usage 3104**** 3105 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00309]] 3106 All submitted commands that refer to any element of 3107 pname:pDescriptorSets must: have completed execution 3108 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00310]] 3109 pname:pDescriptorSets must: be a valid pointer to an array of 3110 pname:descriptorSetCount sname:VkDescriptorSet handles, each element of 3111 which must: either be a valid handle or dlink:VK_NULL_HANDLE 3112 * [[VUID-vkFreeDescriptorSets-descriptorPool-00312]] 3113 pname:descriptorPool must: have been created with the 3114 ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT flag 3115**** 3116 3117include::{generated}/validity/protos/vkFreeDescriptorSets.adoc[] 3118-- 3119 3120[open,refpage='vkResetDescriptorPool',desc='Resets a descriptor pool object',type='protos'] 3121-- 3122To return all descriptor sets allocated from a given pool to the pool, 3123rather than freeing individual descriptor sets, call: 3124 3125include::{generated}/api/protos/vkResetDescriptorPool.adoc[] 3126 3127 * pname:device is the logical device that owns the descriptor pool. 3128 * pname:descriptorPool is the descriptor pool to be reset. 3129 * pname:flags is reserved for future use. 3130 3131Resetting a descriptor pool recycles all of the resources from all of the 3132descriptor sets allocated from the descriptor pool back to the descriptor 3133pool, and the descriptor sets are implicitly freed. 3134 3135.Valid Usage 3136**** 3137 * [[VUID-vkResetDescriptorPool-descriptorPool-00313]] 3138 All uses of pname:descriptorPool (via any allocated descriptor sets) 3139 must: have completed execution 3140**** 3141 3142include::{generated}/validity/protos/vkResetDescriptorPool.adoc[] 3143-- 3144 3145[open,refpage='VkDescriptorPoolResetFlags',desc='Reserved for future use',type='flags'] 3146-- 3147include::{generated}/api/flags/VkDescriptorPoolResetFlags.adoc[] 3148 3149tname:VkDescriptorPoolResetFlags is a bitmask type for setting a mask, but 3150is currently reserved for future use. 3151-- 3152 3153 3154[[descriptorsets-updates]] 3155=== Descriptor Set Updates 3156 3157[open,refpage='vkUpdateDescriptorSets',desc='Update the contents of a descriptor set object',type='protos'] 3158-- 3159Once allocated, descriptor sets can: be updated with a combination of write 3160and copy operations. 3161To update descriptor sets, call: 3162 3163include::{generated}/api/protos/vkUpdateDescriptorSets.adoc[] 3164 3165 * pname:device is the logical device that updates the descriptor sets. 3166 * pname:descriptorWriteCount is the number of elements in the 3167 pname:pDescriptorWrites array. 3168 * pname:pDescriptorWrites is a pointer to an array of 3169 slink:VkWriteDescriptorSet structures describing the descriptor sets to 3170 write to. 3171 * pname:descriptorCopyCount is the number of elements in the 3172 pname:pDescriptorCopies array. 3173 * pname:pDescriptorCopies is a pointer to an array of 3174 slink:VkCopyDescriptorSet structures describing the descriptor sets to 3175 copy between. 3176 3177The operations described by pname:pDescriptorWrites are performed first, 3178followed by the operations described by pname:pDescriptorCopies. 3179Within each array, the operations are performed in the order they appear in 3180the array. 3181 3182Each element in the pname:pDescriptorWrites array describes an operation 3183updating the descriptor set using descriptors for resources specified in the 3184structure. 3185 3186Each element in the pname:pDescriptorCopies array is a 3187slink:VkCopyDescriptorSet structure describing an operation copying 3188descriptors between sets. 3189 3190If the pname:dstSet member of any element of pname:pDescriptorWrites or 3191pname:pDescriptorCopies is bound, accessed, or modified by any command that 3192was recorded to a command buffer which is currently in the 3193<<commandbuffers-lifecycle, recording or executable state>>, 3194ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3195and any of the descriptor bindings that are updated were not created with 3196the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT or 3197ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT bits set, 3198endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3199that command buffer becomes <<commandbuffers-lifecycle, invalid>>. 3200 3201.Valid Usage 3202**** 3203 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06236]] 3204 For each element [eq]#i# where 3205 pname:pDescriptorWrites[i].pname:descriptorType is 3206 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 3207 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, elements of the 3208 pname:pTexelBufferView member of pname:pDescriptorWrites[i] must: have 3209 been created on pname:device 3210 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06237]] 3211 For each element [eq]#i# where 3212 pname:pDescriptorWrites[i].pname:descriptorType is 3213 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3214 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3215 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3216 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:buffer member 3217 of any element of the pname:pBufferInfo member of 3218 pname:pDescriptorWrites[i] must: have been created on pname:device 3219 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06238]] 3220 For each element [eq]#i# where 3221 pname:pDescriptorWrites[i].pname:descriptorType is 3222 ename:VK_DESCRIPTOR_TYPE_SAMPLER or 3223 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 3224 not allocated with a layout that included immutable samplers for 3225 pname:dstBinding with pname:descriptorType, the pname:sampler member of 3226 any element of the pname:pImageInfo member of pname:pDescriptorWrites[i] 3227 must: have been created on pname:device 3228 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06239]] 3229 For each element [eq]#i# where 3230 pname:pDescriptorWrites[i].pname:descriptorType is 3231 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3232 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3233 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, or 3234 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER the pname:imageView 3235 member of any element of pname:pDescriptorWrites[i] must: have been 3236 created on pname:device 3237ifdef::VK_KHR_acceleration_structure[] 3238 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06240]] 3239 For each element [eq]#i# where 3240 pname:pDescriptorWrites[i].pname:descriptorType is 3241 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, elements of the 3242 pname:pAccelerationStructures member of a 3243 slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 3244 pname:pNext chain of pname:pDescriptorWrites[i] must: have been created 3245 on pname:device 3246endif::VK_KHR_acceleration_structure[] 3247ifdef::VK_NV_ray_tracing[] 3248 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06241]] 3249 For each element [eq]#i# where 3250 pname:pDescriptorWrites[i].pname:descriptorType is 3251 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, elements of the 3252 pname:pAccelerationStructures member of a 3253 slink:VkWriteDescriptorSetAccelerationStructureNV structure in the 3254 pname:pNext chain of pname:pDescriptorWrites[i] must: have been created 3255 on pname:device 3256endif::VK_NV_ray_tracing[] 3257ifdef::VK_QCOM_image_processing[] 3258 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06940]] 3259 For each element [eq]#i# where 3260 pname:pDescriptorWrites[i].pname:descriptorType is 3261 ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM or 3262 ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM, the pname:imageView 3263 member of any element of pname:pDescriptorWrites[i] must: have been 3264 created on pname:device 3265endif::VK_QCOM_image_processing[] 3266 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06493]] 3267 For each element [eq]#i# where 3268 pname:pDescriptorWrites[i].pname:descriptorType is 3269 ename:VK_DESCRIPTOR_TYPE_SAMPLER, 3270 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3271 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3272 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3273 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3274 pname:pDescriptorWrites[i].pname:pImageInfo must: be a valid pointer to 3275 an array of pname:pDescriptorWrites[i].pname:descriptorCount valid 3276 sname:VkDescriptorImageInfo structures 3277ifdef::VK_QCOM_image_processing[] 3278 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06941]] 3279 For each element [eq]#i# where 3280 pname:pDescriptorWrites[i].pname:descriptorType is 3281 ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM or 3282 ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM, 3283 pname:pDescriptorWrites[i].pname:pImageInfo must: be a valid pointer to 3284 an array of pname:pDescriptorWrites[i].pname:descriptorCount valid 3285 sname:VkDescriptorImageInfo structures 3286endif::VK_QCOM_image_processing[] 3287 * [[VUID-vkUpdateDescriptorSets-None-03047]] 3288 The pname:dstSet member of each element of pname:pDescriptorWrites or 3289 pname:pDescriptorCopies 3290ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3291 for bindings which were created without the 3292 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT or 3293 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT bits set 3294endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3295 must: not be used by any command that was recorded to a command buffer 3296 which is in the <<commandbuffers-lifecycle,pending state>> 3297 * [[VUID-vkUpdateDescriptorSets-pDescriptorWrites-06993]] 3298 Host access to pname:pDescriptorWrites[i].pname:dstSet and 3299 pname:pDescriptorCopies[i].pname:dstSet must: be 3300 <<fundamentals-threadingbehavior,externally synchronized>> 3301ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3302 unless explicitly denoted otherwise for specific flags 3303endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3304**** 3305 3306include::{generated}/validity/protos/vkUpdateDescriptorSets.adoc[] 3307-- 3308 3309[open,refpage='VkWriteDescriptorSet',desc='Structure specifying the parameters of a descriptor set write operation',type='structs'] 3310-- 3311The sname:VkWriteDescriptorSet structure is defined as: 3312 3313include::{generated}/api/structs/VkWriteDescriptorSet.adoc[] 3314 3315 * pname:sType is a elink:VkStructureType value identifying this structure. 3316 * pname:pNext is `NULL` or a pointer to a structure extending this 3317 structure. 3318 * pname:dstSet is the destination descriptor set to update. 3319 * pname:dstBinding is the descriptor binding within that set. 3320 * pname:dstArrayElement is the starting element in that array. 3321ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3322 If the descriptor binding identified by pname:dstSet and 3323 pname:dstBinding has a descriptor type of 3324 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then pname:dstArrayElement 3325 specifies the starting byte offset within the binding. 3326endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3327 * pname:descriptorCount is the number of descriptors to update. 3328ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3329 If the descriptor binding identified by pname:dstSet and 3330 pname:dstBinding has a descriptor type of 3331 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, then 3332 pname:descriptorCount specifies the number of bytes to update. 3333 Otherwise, 3334endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3335 pname:descriptorCount is one of 3336 ** the number of elements in pname:pImageInfo 3337 ** the number of elements in pname:pBufferInfo 3338 ** the number of elements in pname:pTexelBufferView 3339ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3340 ** a value matching the pname:dataSize member of a 3341 slink:VkWriteDescriptorSetInlineUniformBlock structure in the 3342 pname:pNext chain 3343endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3344ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 3345 ** a value matching the pname:accelerationStructureCount of a 3346 slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 3347 pname:pNext chain 3348endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 3349 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 3350 each descriptor in pname:pImageInfo, pname:pBufferInfo, or 3351 pname:pTexelBufferView, as described below. 3352ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3353 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3354 pname:dstBinding is not equal to ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, 3355 pname:descriptorType must: 3356endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3357ifndef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3358 It must: 3359endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3360 be the same type as the pname:descriptorType specified in 3361 sname:VkDescriptorSetLayoutBinding for pname:dstSet at pname:dstBinding. 3362 The type of the descriptor also controls which array the descriptors are 3363 taken from. 3364 * pname:pImageInfo is a pointer to an array of slink:VkDescriptorImageInfo 3365 structures or is ignored, as described below. 3366 * pname:pBufferInfo is a pointer to an array of 3367 slink:VkDescriptorBufferInfo structures or is ignored, as described 3368 below. 3369 * pname:pTexelBufferView is a pointer to an array of slink:VkBufferView 3370 handles as described in the <<resources-buffer-views,Buffer Views>> 3371 section or is ignored, as described below. 3372 3373Only one of pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView 3374members is used according to the descriptor type specified in the 3375pname:descriptorType member of the containing sname:VkWriteDescriptorSet 3376structure, 3377ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3378or none of them in case pname:descriptorType is 3379ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, in which case the source data 3380for the descriptor writes is taken from the 3381slink:VkWriteDescriptorSetInlineUniformBlock structure included in the 3382pname:pNext chain of sname:VkWriteDescriptorSet, 3383endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3384ifdef::VK_KHR_acceleration_structure[] 3385or if pname:descriptorType is 3386ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, in which case the 3387source data for the descriptor writes is taken from the 3388slink:VkWriteDescriptorSetAccelerationStructureKHR structure in the 3389pname:pNext chain of sname:VkWriteDescriptorSet, 3390endif::VK_KHR_acceleration_structure[] 3391ifdef::VK_NV_ray_tracing[] 3392or if pname:descriptorType is 3393ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, in which case the source 3394data for the descriptor writes is taken from the 3395slink:VkWriteDescriptorSetAccelerationStructureNV structure in the 3396pname:pNext chain of sname:VkWriteDescriptorSet, 3397endif::VK_NV_ray_tracing[] 3398as specified below. 3399 3400ifdef::VK_EXT_robustness2[] 3401If the <<features-nullDescriptor, pname:nullDescriptor>> feature is enabled, 3402the buffer, 3403ifdef::VK_KHR_acceleration_structure[] 3404acceleration structure, 3405endif::VK_KHR_acceleration_structure[] 3406imageView, or bufferView can: be dlink:VK_NULL_HANDLE. 3407Loads from a null descriptor return zero values and stores and atomics to a 3408null descriptor are discarded. 3409ifdef::VK_KHR_acceleration_structure[] 3410A null acceleration structure descriptor results in the miss shader being 3411invoked. 3412endif::VK_KHR_acceleration_structure[] 3413endif::VK_EXT_robustness2[] 3414 3415ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3416If the destination descriptor is a mutable descriptor, the active descriptor 3417type for the destination descriptor becomes pname:descriptorType. 3418endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3419 3420[[descriptorsets-updates-consecutive, consecutive binding updates]] 3421If the pname:dstBinding has fewer than pname:descriptorCount array elements 3422remaining starting from pname:dstArrayElement, then the remainder will be 3423used to update the subsequent binding - [eq]#pname:dstBinding+1# starting at 3424array element zero. 3425If a binding has a pname:descriptorCount of zero, it is skipped. 3426This behavior applies recursively, with the update affecting consecutive 3427bindings as needed to update all pname:descriptorCount descriptors. 3428Consecutive bindings must: have identical elink:VkDescriptorType, 3429tlink:VkShaderStageFlags, 3430ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3431elink:VkDescriptorBindingFlagBits, 3432endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 3433and immutable samplers references. 3434ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3435In addition, if the elink:VkDescriptorType is 3436ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the supported descriptor types in 3437slink:VkMutableDescriptorTypeCreateInfoEXT must: be equally defined. 3438endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3439 3440ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3441[NOTE] 3442.Note 3443==== 3444The same behavior applies to bindings with a descriptor type of 3445ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK where pname:descriptorCount 3446specifies the number of bytes to update while pname:dstArrayElement 3447specifies the starting byte offset, thus in this case if the 3448pname:dstBinding has a smaller byte size than the sum of 3449pname:dstArrayElement and pname:descriptorCount, then the remainder will be 3450used to update the subsequent binding - [eq]#pname:dstBinding+1# starting at 3451offset zero. 3452This falls out as a special case of the above rule. 3453==== 3454endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3455 3456.Valid Usage 3457**** 3458 * [[VUID-VkWriteDescriptorSet-dstBinding-00315]] 3459 pname:dstBinding must: be less than or equal to the maximum value of 3460 pname:binding of all slink:VkDescriptorSetLayoutBinding structures 3461 specified when pname:dstSet's descriptor set layout was created 3462 * [[VUID-VkWriteDescriptorSet-dstBinding-00316]] 3463 pname:dstBinding must: be a binding with a non-zero 3464 pname:descriptorCount 3465 * [[VUID-VkWriteDescriptorSet-descriptorCount-00317]] 3466 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 3467 structure, except those with a pname:descriptorCount of zero, must: have 3468 identical pname:descriptorType and pname:stageFlags 3469 * [[VUID-VkWriteDescriptorSet-descriptorCount-00318]] 3470 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 3471 structure, except those with a pname:descriptorCount of zero, must: all 3472 either use immutable samplers or must: all not use immutable samplers 3473 * [[VUID-VkWriteDescriptorSet-descriptorType-00319]] 3474 pname:descriptorType must: match the type of pname:dstBinding within 3475 pname:dstSet 3476 * [[VUID-VkWriteDescriptorSet-dstSet-00320]] 3477 pname:dstSet must: be a valid slink:VkDescriptorSet handle 3478 * [[VUID-VkWriteDescriptorSet-dstArrayElement-00321]] 3479 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 3480 than or equal to the number of array elements in the descriptor set 3481 binding specified by pname:dstBinding, and all applicable consecutive 3482 bindings, as described by <<descriptorsets-updates-consecutive>> 3483ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3484 * [[VUID-VkWriteDescriptorSet-descriptorType-02219]] 3485 If pname:descriptorType is 3486 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, pname:dstArrayElement 3487 must: be an integer multiple of `4` 3488 * [[VUID-VkWriteDescriptorSet-descriptorType-02220]] 3489 If pname:descriptorType is 3490 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, pname:descriptorCount 3491 must: be an integer multiple of `4` 3492endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3493 * [[VUID-VkWriteDescriptorSet-descriptorType-02994]] 3494 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 3495 or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 3496 pname:pTexelBufferView must: be either a valid sname:VkBufferView handle 3497 or dlink:VK_NULL_HANDLE 3498 * [[VUID-VkWriteDescriptorSet-descriptorType-02995]] 3499 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 3500 or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER and the 3501 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 3502 enabled, each element of pname:pTexelBufferView must: not be 3503 dlink:VK_NULL_HANDLE 3504 * [[VUID-VkWriteDescriptorSet-descriptorType-00324]] 3505 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3506 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3507 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3508 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, pname:pBufferInfo must: 3509 be a valid pointer to an array of pname:descriptorCount valid 3510 sname:VkDescriptorBufferInfo structures 3511 * [[VUID-VkWriteDescriptorSet-descriptorType-00325]] 3512 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 3513 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 3514 not allocated with a layout that included immutable samplers for 3515 pname:dstBinding with pname:descriptorType, the pname:sampler member of 3516 each element of pname:pImageInfo must: be a valid sname:VkSampler object 3517 * [[VUID-VkWriteDescriptorSet-descriptorType-02996]] 3518 If pname:descriptorType is 3519 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3520 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, or 3521 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the pname:imageView member of 3522 each element of pname:pImageInfo must: be either a valid 3523 sname:VkImageView handle or dlink:VK_NULL_HANDLE 3524 * [[VUID-VkWriteDescriptorSet-descriptorType-02997]] 3525 If pname:descriptorType is 3526 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3527 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, or 3528 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and the 3529 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 3530 enabled, the pname:imageView member of each element of pname:pImageInfo 3531 must: not be dlink:VK_NULL_HANDLE 3532 * [[VUID-VkWriteDescriptorSet-descriptorType-07683]] 3533 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3534 the pname:imageView member of each element of pname:pImageInfo must: not 3535 be dlink:VK_NULL_HANDLE 3536ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3537 * [[VUID-VkWriteDescriptorSet-descriptorType-02221]] 3538 If pname:descriptorType is 3539 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, the pname:pNext chain 3540 must: include a slink:VkWriteDescriptorSetInlineUniformBlock structure 3541 whose pname:dataSize member equals pname:descriptorCount 3542endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3543ifdef::VK_KHR_acceleration_structure[] 3544 * [[VUID-VkWriteDescriptorSet-descriptorType-02382]] 3545 If pname:descriptorType is 3546 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, the pname:pNext 3547 chain must: include a slink:VkWriteDescriptorSetAccelerationStructureKHR 3548 structure whose pname:accelerationStructureCount member equals 3549 pname:descriptorCount 3550endif::VK_KHR_acceleration_structure[] 3551ifdef::VK_NV_ray_tracing[] 3552 * [[VUID-VkWriteDescriptorSet-descriptorType-03817]] 3553 If pname:descriptorType is 3554 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, the pname:pNext 3555 chain must: include a slink:VkWriteDescriptorSetAccelerationStructureNV 3556 structure whose pname:accelerationStructureCount member equals 3557 pname:descriptorCount 3558endif::VK_NV_ray_tracing[] 3559ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 3560 * [[VUID-VkWriteDescriptorSet-descriptorType-01946]] 3561 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, then 3562 the pname:imageView member of each pname:pImageInfo element must: have 3563 been created without a sname:VkSamplerYcbcrConversionInfo structure in 3564 its pname:pNext chain 3565 * [[VUID-VkWriteDescriptorSet-descriptorType-02738]] 3566 If pname:descriptorType is 3567 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and if any element of 3568 pname:pImageInfo has a pname:imageView member that was created with a 3569 sname:VkSamplerYcbcrConversionInfo structure in its pname:pNext chain, 3570 then pname:dstSet must: have been allocated with a layout that included 3571 immutable samplers for pname:dstBinding, and the corresponding immutable 3572 sampler must: have been created with an _identically defined_ 3573 sname:VkSamplerYcbcrConversionInfo object 3574 * [[VUID-VkWriteDescriptorSet-descriptorType-01948]] 3575 If pname:descriptorType is 3576 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 3577 allocated with a layout that included immutable samplers for 3578 pname:dstBinding, then the pname:imageView member of each element of 3579 pname:pImageInfo which corresponds to an immutable sampler that enables 3580 <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>> must: have been 3581 created with a sname:VkSamplerYcbcrConversionInfo structure in its 3582 pname:pNext chain with an _identically defined_ 3583 sname:VkSamplerYcbcrConversionInfo to the corresponding immutable 3584 sampler 3585endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 3586 * [[VUID-VkWriteDescriptorSet-descriptorType-00327]] 3587 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3588 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:offset member 3589 of each element of pname:pBufferInfo must: be a multiple of 3590 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 3591 * [[VUID-VkWriteDescriptorSet-descriptorType-00328]] 3592 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3593 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:offset member 3594 of each element of pname:pBufferInfo must: be a multiple of 3595 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 3596 * [[VUID-VkWriteDescriptorSet-descriptorType-00329]] 3597 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3598 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, 3599 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, or 3600 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, and the pname:buffer 3601 member of any element of pname:pBufferInfo is the handle of a non-sparse 3602 buffer, then that buffer must: be bound completely and contiguously to a 3603 single sname:VkDeviceMemory object 3604 * [[VUID-VkWriteDescriptorSet-descriptorType-00330]] 3605 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3606 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:buffer member 3607 of each element of pname:pBufferInfo must: have been created with 3608 ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT set 3609 * [[VUID-VkWriteDescriptorSet-descriptorType-00331]] 3610 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3611 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:buffer member 3612 of each element of pname:pBufferInfo must: have been created with 3613 ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT set 3614 * [[VUID-VkWriteDescriptorSet-descriptorType-00332]] 3615 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 3616 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:range member 3617 of each element of pname:pBufferInfo, or the 3618 <<buffer-info-effective-range,effective range>> if pname:range is 3619 ename:VK_WHOLE_SIZE, must: be less than or equal to 3620 sname:VkPhysicalDeviceLimits::pname:maxUniformBufferRange 3621 * [[VUID-VkWriteDescriptorSet-descriptorType-00333]] 3622 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 3623 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:range member 3624 of each element of pname:pBufferInfo, or the 3625 <<buffer-info-effective-range,effective range>> if pname:range is 3626 ename:VK_WHOLE_SIZE, must: be less than or equal to 3627 sname:VkPhysicalDeviceLimits::pname:maxStorageBufferRange 3628 * [[VUID-VkWriteDescriptorSet-descriptorType-08765]] 3629 If pname:descriptorType is 3630 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, the 3631 pname:pTexelBufferView <<resources-buffer-views-usage, buffer view 3632 usage>> must: include ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT 3633 * [[VUID-VkWriteDescriptorSet-descriptorType-08766]] 3634 If pname:descriptorType is 3635 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the 3636 pname:pTexelBufferView <<resources-buffer-views-usage, buffer view 3637 usage>> must: include ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT 3638 * [[VUID-VkWriteDescriptorSet-descriptorType-00336]] 3639 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE or 3640 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of 3641 each element of pname:pImageInfo must: have been created with the 3642 identity swizzle 3643 * [[VUID-VkWriteDescriptorSet-descriptorType-00337]] 3644 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 3645 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageView 3646 member of each element of pname:pImageInfo must: have been created with 3647 ename:VK_IMAGE_USAGE_SAMPLED_BIT set 3648 * [[VUID-VkWriteDescriptorSet-descriptorType-04149]] 3649 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE the 3650 pname:imageLayout member of each element of pname:pImageInfo must: be a 3651 member of the list given in <<descriptorsets-sampledimage, Sampled 3652 Image>> 3653 * [[VUID-VkWriteDescriptorSet-descriptorType-04150]] 3654 If pname:descriptorType is 3655 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER the pname:imageLayout 3656 member of each element of pname:pImageInfo must: be a member of the list 3657 given in <<descriptorsets-combinedimagesampler, Combined Image Sampler>> 3658 * [[VUID-VkWriteDescriptorSet-descriptorType-04151]] 3659 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT the 3660 pname:imageLayout member of each element of pname:pImageInfo must: be a 3661 member of the list given in <<descriptorsets-inputattachment, Input 3662 Attachment>> 3663 * [[VUID-VkWriteDescriptorSet-descriptorType-04152]] 3664 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE the 3665 pname:imageLayout member of each element of pname:pImageInfo must: be a 3666 member of the list given in <<descriptorsets-storageimage, Storage 3667 Image>> 3668 * [[VUID-VkWriteDescriptorSet-descriptorType-00338]] 3669 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3670 the pname:imageView member of each element of pname:pImageInfo must: 3671 have been created with ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set 3672 * [[VUID-VkWriteDescriptorSet-descriptorType-00339]] 3673 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the 3674 pname:imageView member of each element of pname:pImageInfo must: have 3675 been created with ename:VK_IMAGE_USAGE_STORAGE_BIT set 3676 * [[VUID-VkWriteDescriptorSet-descriptorType-02752]] 3677 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER, then 3678 pname:dstSet must: not have been allocated with a layout that included 3679 immutable samplers for pname:dstBinding 3680ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3681 * [[VUID-VkWriteDescriptorSet-dstSet-04611]] 3682 If the sname:VkDescriptorSetLayoutBinding for pname:dstSet at 3683 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the new active 3684 descriptor type pname:descriptorType must: exist in the corresponding 3685 pname:pMutableDescriptorTypeLists list for pname:dstBinding 3686endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3687ifdef::VK_EXT_image_view_min_lod[] 3688 * [[VUID-VkWriteDescriptorSet-descriptorType-06450]] 3689 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 3690 the pname:imageView member of each element of pname:pImageInfo must: 3691 have either been created without a slink:VkImageViewMinLodCreateInfoEXT 3692 included in the pname:pNext chain or with a 3693 slink:VkImageViewMinLodCreateInfoEXT::pname:minLod of `0.0` 3694endif::VK_EXT_image_view_min_lod[] 3695ifdef::VK_QCOM_image_processing[] 3696 * [[VUID-VkWriteDescriptorSet-descriptorType-06942]] 3697 If pname:descriptorType is 3698 ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM, the pname:imageView 3699 member of each element of pname:pImageInfo must: have been created with 3700 a view created with an pname:image created with 3701 ename:VK_IMAGE_USAGE_SAMPLE_WEIGHT_BIT_QCOM 3702 * [[VUID-VkWriteDescriptorSet-descriptorType-06943]] 3703 If pname:descriptorType is 3704 ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM, the pname:imageView 3705 member of each element of pname:pImageInfo must: have been created with 3706 a view created with an pname:image created with 3707 ename:VK_IMAGE_USAGE_SAMPLE_BLOCK_MATCH_BIT_QCOM 3708endif::VK_QCOM_image_processing[] 3709 3710 3711**** 3712 3713include::{generated}/validity/structs/VkWriteDescriptorSet.adoc[] 3714-- 3715 3716[open,refpage='VkDescriptorType',desc='Specifies the type of a descriptor in a descriptor set',type='enums'] 3717-- 3718The type of descriptors in a descriptor set is specified by 3719slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the 3720values: 3721 3722include::{generated}/api/enums/VkDescriptorType.adoc[] 3723 3724 * ename:VK_DESCRIPTOR_TYPE_SAMPLER specifies a <<descriptorsets-sampler, 3725 sampler descriptor>>. 3726 * ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER specifies a 3727 <<descriptorsets-combinedimagesampler, combined image sampler 3728 descriptor>>. 3729 * ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE specifies a 3730 <<descriptorsets-sampledimage, sampled image descriptor>>. 3731 * ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE specifies a 3732 <<descriptorsets-storageimage, storage image descriptor>>. 3733 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER specifies a 3734 <<descriptorsets-uniformtexelbuffer, uniform texel buffer descriptor>>. 3735 * ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER specifies a 3736 <<descriptorsets-storagetexelbuffer, storage texel buffer descriptor>>. 3737 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER specifies a 3738 <<descriptorsets-uniformbuffer, uniform buffer descriptor>>. 3739 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER specifies a 3740 <<descriptorsets-storagebuffer, storage buffer descriptor>>. 3741 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC specifies a 3742 <<descriptorsets-uniformbufferdynamic, dynamic uniform buffer 3743 descriptor>>. 3744 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC specifies a 3745 <<descriptorsets-storagebufferdynamic, dynamic storage buffer 3746 descriptor>>. 3747 * ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT specifies an 3748 <<descriptorsets-inputattachment, input attachment descriptor>>. 3749ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3750 * ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK specifies an 3751 <<descriptorsets-inlineuniformblock, inline uniform block>>. 3752endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3753ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3754 * ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT specifies a 3755 <<descriptorsets-mutable, descriptor of mutable type>>. 3756endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 3757ifdef::VK_QCOM_image_processing[] 3758 * ename:VK_DESCRIPTOR_TYPE_SAMPLE_WEIGHT_IMAGE_QCOM specifies a 3759 <<descriptorsets-weightimage, sampled weight image descriptor>>. 3760 * ename:VK_DESCRIPTOR_TYPE_BLOCK_MATCH_IMAGE_QCOM specifies a 3761 <<descriptorsets-blockmatch, block matching image descriptor>>. 3762 3763endif::VK_QCOM_image_processing[] 3764 3765When a descriptor set is updated via elements of slink:VkWriteDescriptorSet, 3766members of pname:pImageInfo, pname:pBufferInfo and pname:pTexelBufferView 3767are only accessed by the implementation when they correspond to descriptor 3768type being defined - otherwise they are ignored. 3769The members accessed are as follows for each descriptor type: 3770 3771 * For ename:VK_DESCRIPTOR_TYPE_SAMPLER, only the pname:sampler member of 3772 each element of slink:VkWriteDescriptorSet::pname:pImageInfo is 3773 accessed. 3774 * For ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3775 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 3776 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only the pname:imageView and 3777 pname:imageLayout members of each element of 3778 slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3779 * For ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each 3780 element of slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 3781 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 3782 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 3783 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 3784 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each 3785 element of slink:VkWriteDescriptorSet::pname:pBufferInfo are accessed. 3786 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 3787 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 3788 slink:VkWriteDescriptorSet::pname:pTexelBufferView is accessed. 3789 3790ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3791When updating descriptors with a pname:descriptorType of 3792ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, none of the pname:pImageInfo, 3793pname:pBufferInfo, or pname:pTexelBufferView members are accessed, instead 3794the source data of the descriptor update operation is taken from the 3795slink:VkWriteDescriptorSetInlineUniformBlock structure in the pname:pNext 3796chain of sname:VkWriteDescriptorSet. 3797endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3798ifdef::VK_KHR_acceleration_structure[] 3799When updating descriptors with a pname:descriptorType of 3800ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, none of the 3801pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3802accessed, instead the source data of the descriptor update operation is 3803taken from the slink:VkWriteDescriptorSetAccelerationStructureKHR structure 3804in the pname:pNext chain of sname:VkWriteDescriptorSet. 3805endif::VK_KHR_acceleration_structure[] 3806ifdef::VK_NV_ray_tracing[] 3807When updating descriptors with a pname:descriptorType of 3808ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, none of the 3809pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView members are 3810accessed, instead the source data of the descriptor update operation is 3811taken from the slink:VkWriteDescriptorSetAccelerationStructureNV structure 3812in the pname:pNext chain of sname:VkWriteDescriptorSet. 3813endif::VK_NV_ray_tracing[] 3814-- 3815 3816[open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer information',type='structs'] 3817-- 3818The sname:VkDescriptorBufferInfo structure is defined as: 3819 3820include::{generated}/api/structs/VkDescriptorBufferInfo.adoc[] 3821 3822 * pname:buffer is 3823ifdef::VK_EXT_robustness2[] 3824dlink:VK_NULL_HANDLE or 3825endif::VK_EXT_robustness2[] 3826the buffer resource. 3827 * pname:offset is the offset in bytes from the start of pname:buffer. 3828 Access to buffer memory via this descriptor uses addressing that is 3829 relative to this starting offset. 3830 * pname:range is the size in bytes that is used for this descriptor 3831 update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the 3832 end of the buffer. 3833+ 3834[NOTE] 3835.Note 3836==== 3837When setting pname:range to ename:VK_WHOLE_SIZE, the 3838<<buffer-info-effective-range, effective range>> must: not be larger than 3839the maximum range for the descriptor type (<<limits-maxUniformBufferRange, 3840pname:maxUniformBufferRange>> or <<limits-maxStorageBufferRange, 3841pname:maxStorageBufferRange>>). 3842This means that ename:VK_WHOLE_SIZE is not typically useful in the common 3843case where uniform buffer descriptors are suballocated from a buffer that is 3844much larger than pname:maxUniformBufferRange. 3845==== 3846 3847For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and 3848ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, 3849pname:offset is the base offset from which the dynamic offset is applied and 3850pname:range is the static size used for all dynamic offsets. 3851 3852[[buffer-info-effective-range]] 3853When pname:range is ename:VK_WHOLE_SIZE the effective range is calculated at 3854flink:vkUpdateDescriptorSets is by taking the size of pname:buffer minus the 3855pname:offset. 3856 3857.Valid Usage 3858**** 3859 * [[VUID-VkDescriptorBufferInfo-offset-00340]] 3860 pname:offset must: be less than the size of pname:buffer 3861 * [[VUID-VkDescriptorBufferInfo-range-00341]] 3862 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3863 greater than `0` 3864 * [[VUID-VkDescriptorBufferInfo-range-00342]] 3865 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 3866 less than or equal to the size of pname:buffer minus pname:offset 3867 * [[VUID-VkDescriptorBufferInfo-buffer-02998]] 3868 If the <<features-nullDescriptor, pname:nullDescriptor>> feature is not 3869 enabled, pname:buffer must: not be dlink:VK_NULL_HANDLE 3870ifdef::VK_EXT_robustness2[] 3871 * [[VUID-VkDescriptorBufferInfo-buffer-02999]] 3872 If pname:buffer is dlink:VK_NULL_HANDLE, pname:offset must: be zero and 3873 pname:range must: be ename:VK_WHOLE_SIZE 3874endif::VK_EXT_robustness2[] 3875**** 3876 3877include::{generated}/validity/structs/VkDescriptorBufferInfo.adoc[] 3878-- 3879 3880[open,refpage='VkDescriptorImageInfo',desc='Structure specifying descriptor image information',type='structs'] 3881-- 3882The sname:VkDescriptorImageInfo structure is defined as: 3883 3884include::{generated}/api/structs/VkDescriptorImageInfo.adoc[] 3885 3886 * pname:sampler is a sampler handle, and is used in descriptor updates for 3887 types ename:VK_DESCRIPTOR_TYPE_SAMPLER and 3888 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER if the binding being 3889 updated does not use immutable samplers. 3890 * pname:imageView is 3891ifdef::VK_EXT_robustness2[] 3892 dlink:VK_NULL_HANDLE or 3893endif::VK_EXT_robustness2[] 3894 an image view handle, and is used in descriptor updates for types 3895 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3896 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3897 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3898 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3899 * pname:imageLayout is the layout that the image subresources accessible 3900 from pname:imageView will be in at the time this descriptor is accessed. 3901 pname:imageLayout is used in descriptor updates for types 3902 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 3903 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3904 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 3905 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 3906 3907Members of sname:VkDescriptorImageInfo that are not used in an update (as 3908described above) are ignored. 3909 3910.Valid Usage 3911**** 3912ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 3913 * [[VUID-VkDescriptorImageInfo-imageView-06712]] 3914 pname:imageView must: not be a 2D array image view created from a 3D 3915 image 3916ifdef::VK_EXT_image_2d_view_of_3d[] 3917 * [[VUID-VkDescriptorImageInfo-imageView-07795]] 3918 If pname:imageView is a 2D view created from a 3D image, then 3919 pname:descriptorType must: be ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 3920 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, or 3921 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER 3922 * [[VUID-VkDescriptorImageInfo-imageView-07796]] 3923 If pname:imageView is a 2D view created from a 3D image, then the image 3924 must: have been created with 3925 ename:VK_IMAGE_CREATE_2D_VIEW_COMPATIBLE_BIT_EXT set 3926endif::VK_EXT_image_2d_view_of_3d[] 3927 * [[VUID-VkDescriptorImageInfo-descriptorType-06713]] 3928ifdef::VK_EXT_image_2d_view_of_3d[] 3929 If the <<features-image2DViewOf3D, pname:image2DViewOf3D>> feature is 3930 not enabled or pname:descriptorType is not 3931 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE then 3932endif::VK_EXT_image_2d_view_of_3d[] 3933 pname:imageView must: not be a 2D view created from a 3D image 3934 * [[VUID-VkDescriptorImageInfo-descriptorType-06714]] 3935ifdef::VK_EXT_image_2d_view_of_3d[] 3936 If the <<features-sampler2DViewOf3D, pname:sampler2DViewOf3D>> feature 3937 is not enabled or pname:descriptorType is not 3938 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 3939 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER then 3940endif::VK_EXT_image_2d_view_of_3d[] 3941 pname:imageView must: not be a 2D view created from a 3D image 3942endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 3943 * [[VUID-VkDescriptorImageInfo-imageView-01976]] 3944 If pname:imageView is created from a depth/stencil image, the 3945 pname:aspectMask used to create the pname:imageView must: include either 3946 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT but 3947 not both 3948 * [[VUID-VkDescriptorImageInfo-imageLayout-00344]] 3949 pname:imageLayout must: match the actual elink:VkImageLayout of each 3950 subresource accessible from pname:imageView at the time this descriptor 3951 is accessed as defined by the <<resources-image-layouts-matching-rule, 3952 image layout matching rules>> 3953ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3954 * [[VUID-VkDescriptorImageInfo-sampler-01564]] 3955 If pname:sampler is used and the elink:VkFormat of the image is a 3956 <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, the 3957 image must: have been created with 3958 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the pname:aspectMask of 3959 the pname:imageView must: be a valid 3960 <<formats-planes-image-aspect,multi-planar aspect mask>> bit 3961endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 3962ifdef::VK_KHR_portability_subset[] 3963 * [[VUID-VkDescriptorImageInfo-mutableComparisonSamplers-04450]] 3964 If the `apiext:VK_KHR_portability_subset` extension is enabled, and 3965 slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:mutableComparisonSamplers 3966 is ename:VK_FALSE, then pname:sampler must: have been created with 3967 slink:VkSamplerCreateInfo::pname:compareEnable set to ename:VK_FALSE 3968endif::VK_KHR_portability_subset[] 3969**** 3970 3971 3972include::{generated}/validity/structs/VkDescriptorImageInfo.adoc[] 3973-- 3974 3975ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 3976[open,refpage='VkWriteDescriptorSetInlineUniformBlock',desc='Structure specifying inline uniform block data',type='structs',alias='VkWriteDescriptorSetInlineUniformBlockEXT'] 3977-- 3978If the pname:descriptorType member of slink:VkWriteDescriptorSet is 3979ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then the data to write to the 3980descriptor set is specified through a 3981sname:VkWriteDescriptorSetInlineUniformBlock structure included in the 3982pname:pNext chain of sname:VkWriteDescriptorSet. 3983 3984The sname:VkWriteDescriptorSetInlineUniformBlock structure is defined as: 3985 3986include::{generated}/api/structs/VkWriteDescriptorSetInlineUniformBlock.adoc[] 3987 3988ifdef::VK_EXT_inline_uniform_block[] 3989or the equivalent 3990 3991include::{generated}/api/structs/VkWriteDescriptorSetInlineUniformBlockEXT.adoc[] 3992endif::VK_EXT_inline_uniform_block[] 3993 3994 * pname:sType is a elink:VkStructureType value identifying this structure. 3995 * pname:pNext is `NULL` or a pointer to a structure extending this 3996 structure. 3997 * pname:dataSize is the number of bytes of inline uniform block data 3998 pointed to by pname:pData. 3999 * pname:pData is a pointer to pname:dataSize number of bytes of data to 4000 write to the inline uniform block. 4001 4002.Valid Usage 4003**** 4004 * [[VUID-VkWriteDescriptorSetInlineUniformBlock-dataSize-02222]] 4005 pname:dataSize must: be an integer multiple of `4` 4006**** 4007 4008include::{generated}/validity/structs/VkWriteDescriptorSetInlineUniformBlock.adoc[] 4009-- 4010endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4011 4012ifdef::VK_KHR_acceleration_structure[] 4013[open,refpage='VkWriteDescriptorSetAccelerationStructureKHR',desc='Structure specifying acceleration structure descriptor information',type='structs'] 4014-- 4015:refpage: VkWriteDescriptorSetAccelerationStructureKHR 4016 4017The sname:VkWriteDescriptorSetAccelerationStructureKHR structure is defined 4018as: 4019 4020include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureKHR.adoc[] 4021 4022 * pname:sType is a elink:VkStructureType value identifying this structure. 4023 * pname:pNext is `NULL` or a pointer to a structure extending this 4024 structure. 4025 * pname:accelerationStructureCount is the number of elements in 4026 pname:pAccelerationStructures. 4027 * pname:pAccelerationStructures is a pointer to an array of 4028 slink:VkAccelerationStructureKHR structures specifying the acceleration 4029 structures to update. 4030 4031.Valid Usage 4032**** 4033 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-accelerationStructureCount-02236]] 4034 pname:accelerationStructureCount must: be equal to pname:descriptorCount 4035 in the extended structure 4036 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03579]] 4037 Each acceleration structure in pname:pAccelerationStructures must: have 4038 been created with a pname:type of 4039 ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR or 4040 ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR 4041 * [[VUID-VkWriteDescriptorSetAccelerationStructureKHR-pAccelerationStructures-03580]] 4042 If the <<features-nullDescriptor, pname:nullDescriptor>> feature is not 4043 enabled, each element of pname:pAccelerationStructures must: not be 4044 dlink:VK_NULL_HANDLE 4045**** 4046 4047include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureKHR.adoc[] 4048-- 4049endif::VK_KHR_acceleration_structure[] 4050 4051ifdef::VK_NV_ray_tracing[] 4052[open,refpage='VkWriteDescriptorSetAccelerationStructureNV',desc='Structure specifying acceleration structure descriptor information',type='structs'] 4053-- 4054:refpage: VkWriteDescriptorSetAccelerationStructureNV 4055 4056The sname:VkWriteDescriptorSetAccelerationStructureNV structure is defined 4057as: 4058 4059include::{generated}/api/structs/VkWriteDescriptorSetAccelerationStructureNV.adoc[] 4060 4061 * pname:sType is a elink:VkStructureType value identifying this structure. 4062 * pname:pNext is `NULL` or a pointer to a structure extending this 4063 structure. 4064 * pname:accelerationStructureCount is the number of elements in 4065 pname:pAccelerationStructures. 4066 * pname:pAccelerationStructures is a pointer to an array of 4067 slink:VkAccelerationStructureNV structures specifying the acceleration 4068 structures to update. 4069 4070.Valid Usage 4071**** 4072 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-accelerationStructureCount-03747]] 4073 pname:accelerationStructureCount must: be equal to pname:descriptorCount 4074 in the extended structure 4075 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03748]] 4076 Each acceleration structure in pname:pAccelerationStructures must: have 4077 been created with ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR 4078 * [[VUID-VkWriteDescriptorSetAccelerationStructureNV-pAccelerationStructures-03749]] 4079 If the <<features-nullDescriptor, pname:nullDescriptor>> feature is not 4080 enabled, each member of pname:pAccelerationStructures must: not be 4081 dlink:VK_NULL_HANDLE 4082**** 4083 4084include::{generated}/validity/structs/VkWriteDescriptorSetAccelerationStructureNV.adoc[] 4085-- 4086endif::VK_NV_ray_tracing[] 4087 4088[open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] 4089-- 4090The sname:VkCopyDescriptorSet structure is defined as: 4091 4092include::{generated}/api/structs/VkCopyDescriptorSet.adoc[] 4093 4094 * pname:sType is a elink:VkStructureType value identifying this structure. 4095 * pname:pNext is `NULL` or a pointer to a structure extending this 4096 structure. 4097 * pname:srcSet, pname:srcBinding, and pname:srcArrayElement are the source 4098 set, binding, and array element, respectively. 4099ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4100 If the descriptor binding identified by pname:srcSet and 4101 pname:srcBinding has a descriptor type of 4102 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then pname:srcArrayElement 4103 specifies the starting byte offset within the binding to copy from. 4104endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4105 * pname:dstSet, pname:dstBinding, and pname:dstArrayElement are the 4106 destination set, binding, and array element, respectively. 4107ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4108 If the descriptor binding identified by pname:dstSet and 4109 pname:dstBinding has a descriptor type of 4110 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then pname:dstArrayElement 4111 specifies the starting byte offset within the binding to copy to. 4112endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4113 * pname:descriptorCount is the number of descriptors to copy from the 4114 source to destination. 4115 If pname:descriptorCount is greater than the number of remaining array 4116 elements in the source or destination binding, those affect consecutive 4117 bindings in a manner similar to slink:VkWriteDescriptorSet above. 4118ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4119 If the descriptor binding identified by pname:srcSet and 4120 pname:srcBinding has a descriptor type of 4121 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then pname:descriptorCount 4122 specifies the number of bytes to copy and the remaining array elements 4123 in the source or destination binding refer to the remaining number of 4124 bytes in those. 4125endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4126 4127ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4128If the sname:VkDescriptorSetLayoutBinding for pname:dstBinding is 4129ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT and pname:srcBinding is not 4130ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the new active descriptor type becomes 4131the descriptor type of pname:srcBinding. 4132If both sname:VkDescriptorSetLayoutBinding for pname:srcBinding and 4133pname:dstBinding are ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the active 4134descriptor type in each source descriptor is copied into the corresponding 4135destination descriptor. 4136The active descriptor type can: be different for each source descriptor. 4137 4138[NOTE] 4139.Note 4140==== 4141The intention is that copies to and from mutable descriptors is a simple 4142memcpy. 4143Copies between non-mutable and mutable descriptors are expected to require 4144one memcpy per descriptor to handle the difference in size, but this use 4145case with more than one pname:descriptorCount is considered rare. 4146==== 4147endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4148 4149.Valid Usage 4150**** 4151 * [[VUID-VkCopyDescriptorSet-srcBinding-00345]] 4152 pname:srcBinding must: be a valid binding within pname:srcSet 4153 * [[VUID-VkCopyDescriptorSet-srcArrayElement-00346]] 4154 The sum of pname:srcArrayElement and pname:descriptorCount must: be less 4155 than or equal to the number of array elements in the descriptor set 4156 binding specified by pname:srcBinding, and all applicable consecutive 4157 bindings, as described by <<descriptorsets-updates-consecutive>> 4158 * [[VUID-VkCopyDescriptorSet-dstBinding-00347]] 4159 pname:dstBinding must: be a valid binding within pname:dstSet 4160 * [[VUID-VkCopyDescriptorSet-dstArrayElement-00348]] 4161 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 4162 than or equal to the number of array elements in the descriptor set 4163 binding specified by pname:dstBinding, and all applicable consecutive 4164 bindings, as described by <<descriptorsets-updates-consecutive>> 4165 * [[VUID-VkCopyDescriptorSet-dstBinding-02632]] 4166 The type of pname:dstBinding within pname:dstSet must: be equal to the 4167 type of pname:srcBinding within pname:srcSet 4168 * [[VUID-VkCopyDescriptorSet-srcSet-00349]] 4169 If pname:srcSet is equal to pname:dstSet, then the source and 4170 destination ranges of descriptors must: not overlap, where the ranges 4171 may: include array elements from consecutive bindings as described by 4172 <<descriptorsets-updates-consecutive>> 4173ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4174 * [[VUID-VkCopyDescriptorSet-srcBinding-02223]] 4175 If the descriptor type of the descriptor set binding specified by 4176 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, 4177 pname:srcArrayElement must: be an integer multiple of `4` 4178 * [[VUID-VkCopyDescriptorSet-dstBinding-02224]] 4179 If the descriptor type of the descriptor set binding specified by 4180 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, 4181 pname:dstArrayElement must: be an integer multiple of `4` 4182 * [[VUID-VkCopyDescriptorSet-srcBinding-02225]] 4183 If the descriptor type of the descriptor set binding specified by either 4184 pname:srcBinding or pname:dstBinding is 4185 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, pname:descriptorCount 4186 must: be an integer multiple of `4` 4187endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4188ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4189 * [[VUID-VkCopyDescriptorSet-srcSet-01918]] 4190 If pname:srcSet's layout was created with the 4191 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 4192 set, then pname:dstSet's layout must: also have been created with the 4193 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 4194 set 4195 * [[VUID-VkCopyDescriptorSet-srcSet-04885]] 4196 If pname:srcSet's layout was created without 4197ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4198 either the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_EXT 4199 flag or 4200endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4201 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT 4202 flag set, then pname:dstSet's layout must: have been created without the 4203 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT flag 4204 set 4205 * [[VUID-VkCopyDescriptorSet-srcSet-01920]] 4206 If the descriptor pool from which pname:srcSet was allocated was created 4207 with the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set, 4208 then the descriptor pool from which pname:dstSet was allocated must: 4209 also have been created with the 4210 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 4211 * [[VUID-VkCopyDescriptorSet-srcSet-04887]] 4212 If the descriptor pool from which pname:srcSet was allocated was created 4213 without 4214ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4215 either the ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT flag or 4216endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4217 the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set, then 4218 the descriptor pool from which pname:dstSet was allocated must: have 4219 been created without the 4220 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT flag set 4221endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4222 * [[VUID-VkCopyDescriptorSet-dstBinding-02753]] 4223 If the descriptor type of the descriptor set binding specified by 4224 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_SAMPLER, then pname:dstSet 4225 must: not have been allocated with a layout that included immutable 4226 samplers for pname:dstBinding 4227ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4228 * [[VUID-VkCopyDescriptorSet-dstSet-04612]] 4229 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 4230 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the new active 4231 descriptor type must: exist in the corresponding 4232 pname:pMutableDescriptorTypeLists list for pname:dstBinding if the new 4233 active descriptor type is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 4234 * [[VUID-VkCopyDescriptorSet-srcSet-04613]] 4235 If sname:VkDescriptorSetLayoutBinding for pname:srcSet at 4236 pname:srcBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT and the 4237 sname:VkDescriptorSetLayoutBinding for pname:dstSet at pname:dstBinding 4238 is not ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the active descriptor type 4239 for the source descriptor must: match the descriptor type of 4240 pname:dstBinding 4241 * [[VUID-VkCopyDescriptorSet-dstSet-04614]] 4242 If sname:VkDescriptorSetLayoutBinding for pname:dstSet at 4243 pname:dstBinding is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, and the new 4244 active descriptor type is ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT, the 4245 pname:pMutableDescriptorTypeLists for pname:srcBinding and 4246 pname:dstBinding must: match exactly 4247endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4248**** 4249 4250include::{generated}/validity/structs/VkCopyDescriptorSet.adoc[] 4251-- 4252 4253 4254ifdef::VKSC_VERSION_1_0[] 4255ifdef::hidden[] 4256// tag::scremoved[] 4257 * elink:VkStructureType 4258 ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR 4259 <<SCID-8>> 4260 * elink:VkObjectType 4261 ** ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR <<SCID-8>> 4262 * fname:vkCreateDescriptorUpdateTemplateKHR, 4263 fname:vkDestroyDescriptorUpdateTemplateKHR, 4264 fname:vkUpdateDescriptorSetWithTemplateKHR, 4265 fname:vkCmdPushDescriptorSetWithTemplateKHR <<SCID-8>> 4266 * sname:VkDescriptorUpdateTemplateKHR, 4267 sname:VkDescriptorUpdateTemplateEntryKHR, 4268 sname:VkDescriptorUpdateTemplateCreateInfoKHR <<SCID-8>> 4269 * ename:VkDescriptorUpdateTemplateTypeKHR <<SCID-8>> 4270 * tname:VkDescriptorUpdateTemplateCreateFlagsKHR <<SCID-8>> 4271 * ename:VkDescriptorUpdateTemplateType 4272 ** ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR <<SCID-8>> 4273 ** ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 4274 <<SCID-8>> 4275// end::scremoved[] 4276endif::hidden[] 4277endif::VKSC_VERSION_1_0[] 4278 4279 4280ifndef::VKSC_VERSION_1_0[] 4281 4282ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4283[[descriptorsets-updates-with-template]] 4284=== Descriptor Update Templates 4285 4286[open,refpage='VkDescriptorUpdateTemplate',desc='Opaque handle to a descriptor update template',type='handles'] 4287-- 4288A descriptor update template specifies a mapping from descriptor update 4289information in host memory to descriptors in a descriptor set. 4290It is designed to avoid passing redundant information to the driver when 4291frequently updating the same set of descriptors in descriptor sets. 4292 4293Descriptor update template objects are represented by 4294sname:VkDescriptorUpdateTemplate handles: 4295 4296include::{generated}/api/handles/VkDescriptorUpdateTemplate.adoc[] 4297 4298ifdef::VK_KHR_descriptor_update_template[] 4299or the equivalent 4300 4301include::{generated}/api/handles/VkDescriptorUpdateTemplateKHR.adoc[] 4302endif::VK_KHR_descriptor_update_template[] 4303-- 4304 4305 4306=== Descriptor Set Updates With Templates 4307 4308[open,refpage='vkCreateDescriptorUpdateTemplate',desc='Create a new descriptor update template',type='protos'] 4309-- 4310Updating a large sname:VkDescriptorSet array can: be an expensive operation 4311since an application must: specify one slink:VkWriteDescriptorSet structure 4312for each descriptor or descriptor array to update, each of which 4313re-specifies the same state when updating the same descriptor in multiple 4314descriptor sets. 4315For cases when an application wishes to update the same set of descriptors 4316in multiple descriptor sets allocated using the same 4317sname:VkDescriptorSetLayout, flink:vkUpdateDescriptorSetWithTemplate can: be 4318used as a replacement for flink:vkUpdateDescriptorSets. 4319 4320sname:VkDescriptorUpdateTemplate allows implementations to convert a set of 4321descriptor update operations on a single descriptor set to an internal 4322format that, in conjunction with flink:vkUpdateDescriptorSetWithTemplate 4323ifdef::VK_KHR_push_descriptor[] 4324or flink:vkCmdPushDescriptorSetWithTemplateKHR 4325endif::VK_KHR_push_descriptor[] 4326, can: be more efficient compared to calling flink:vkUpdateDescriptorSets 4327ifdef::VK_KHR_push_descriptor[] 4328or flink:vkCmdPushDescriptorSetKHR 4329endif::VK_KHR_push_descriptor[] 4330. 4331The descriptors themselves are not specified in the 4332sname:VkDescriptorUpdateTemplate, rather, offsets into an application 4333provided pointer to host memory are specified, which are combined with a 4334pointer passed to flink:vkUpdateDescriptorSetWithTemplate 4335ifdef::VK_KHR_push_descriptor[] 4336or flink:vkCmdPushDescriptorSetWithTemplateKHR 4337endif::VK_KHR_push_descriptor[] 4338. 4339This allows large batches of updates to be executed without having to 4340convert application data structures into a strictly-defined Vulkan data 4341structure. 4342 4343To create a descriptor update template, call: 4344 4345ifdef::VK_VERSION_1_1[] 4346include::{generated}/api/protos/vkCreateDescriptorUpdateTemplate.adoc[] 4347endif::VK_VERSION_1_1[] 4348 4349ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4350 4351ifdef::VK_KHR_descriptor_update_template[] 4352include::{generated}/api/protos/vkCreateDescriptorUpdateTemplateKHR.adoc[] 4353endif::VK_KHR_descriptor_update_template[] 4354 4355 * pname:device is the logical device that creates the descriptor update 4356 template. 4357 * pname:pCreateInfo is a pointer to a 4358 slink:VkDescriptorUpdateTemplateCreateInfo structure specifying the set 4359 of descriptors to update with a single call to 4360ifdef::VK_KHR_push_descriptor[] 4361 flink:vkCmdPushDescriptorSetWithTemplateKHR or 4362endif::VK_KHR_push_descriptor[] 4363 flink:vkUpdateDescriptorSetWithTemplate. 4364 * pname:pAllocator controls host memory allocation as described in the 4365 <<memory-allocation, Memory Allocation>> chapter. 4366 * pname:pDescriptorUpdateTemplate is a pointer to a 4367 sname:VkDescriptorUpdateTemplate handle in which the resulting 4368 descriptor update template object is returned. 4369 4370include::{generated}/validity/protos/vkCreateDescriptorUpdateTemplate.adoc[] 4371-- 4372 4373[open,refpage='VkDescriptorUpdateTemplateCreateInfo',desc='Structure specifying parameters of a newly created descriptor update template',type='structs'] 4374-- 4375The slink:VkDescriptorUpdateTemplateCreateInfo structure is defined as: 4376include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfo.adoc[] 4377 4378ifdef::VK_KHR_descriptor_update_template[] 4379or the equivalent 4380 4381include::{generated}/api/structs/VkDescriptorUpdateTemplateCreateInfoKHR.adoc[] 4382endif::VK_KHR_descriptor_update_template[] 4383 4384 * pname:sType is a elink:VkStructureType value identifying this structure. 4385 * pname:pNext is `NULL` or a pointer to a structure extending this 4386 structure. 4387 * pname:flags is reserved for future use. 4388 * pname:descriptorUpdateEntryCount is the number of elements in the 4389 pname:pDescriptorUpdateEntries array. 4390 * pname:pDescriptorUpdateEntries is a pointer to an array of 4391 slink:VkDescriptorUpdateTemplateEntry structures describing the 4392 descriptors to be updated by the descriptor update template. 4393 * pname:templateType Specifies the type of the descriptor update template. 4394 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET it 4395 can: only be used to update descriptor sets with a fixed 4396 pname:descriptorSetLayout. 4397ifdef::VK_KHR_push_descriptor[] 4398 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 4399 it can: only be used to push descriptor sets using the provided 4400 pname:pipelineBindPoint, pname:pipelineLayout, and pname:set number. 4401endif::VK_KHR_push_descriptor[] 4402 * pname:descriptorSetLayout is the descriptor set layout used to build the 4403 descriptor update template. 4404 All descriptor sets which are going to be updated through the newly 4405 created descriptor update template must: be created with a layout that 4406 matches (is the same as, or defined identically to) this layout. 4407 This parameter is ignored if pname:templateType is not 4408 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET. 4409ifdef::VK_KHR_push_descriptor[] 4410 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4411 type of the pipeline that will use the descriptors. 4412 This parameter is ignored if pname:templateType is not 4413 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 4414 * pname:pipelineLayout is a slink:VkPipelineLayout object used to program 4415 the bindings. 4416 This parameter is ignored if pname:templateType is not 4417 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 4418 * pname:set is the set number of the descriptor set in the pipeline layout 4419 that will be updated. 4420 This parameter is ignored if pname:templateType is not 4421 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 4422endif::VK_KHR_push_descriptor[] 4423ifndef::VK_KHR_push_descriptor[] 4424 * pname:pipelineBindPoint is reserved for future use and is ignored 4425 * pname:pipelineLayout is reserved for future use and is ignored 4426 * pname:set is reserved for future use and is ignored 4427endif::VK_KHR_push_descriptor[] 4428 4429.Valid Usage 4430**** 4431 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00350]] 4432 If pname:templateType is 4433 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 4434 pname:descriptorSetLayout must: be a valid sname:VkDescriptorSetLayout 4435 handle 4436ifdef::VK_KHR_push_descriptor[] 4437 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00351]] 4438 If pname:templateType is 4439 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 4440 pname:pipelineBindPoint must: be a valid elink:VkPipelineBindPoint value 4441 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00352]] 4442 If pname:templateType is 4443 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 4444 pname:pipelineLayout must: be a valid sname:VkPipelineLayout handle 4445 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00353]] 4446 If pname:templateType is 4447 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, pname:set 4448 must: be the unique set number in the pipeline layout that uses a 4449 descriptor set layout that was created with 4450 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 4451endif::VK_KHR_push_descriptor[] 4452ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4453 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-04615]] 4454 If pname:templateType is 4455 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 4456 pname:descriptorSetLayout must: not contain a binding with type 4457 ename:VK_DESCRIPTOR_TYPE_MUTABLE_EXT 4458endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4459**** 4460 4461 4462include::{generated}/validity/structs/VkDescriptorUpdateTemplateCreateInfo.adoc[] 4463-- 4464 4465[open,refpage='VkDescriptorUpdateTemplateCreateFlags',desc='Reserved for future use',type='flags'] 4466-- 4467include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlags.adoc[] 4468 4469ifdef::VK_KHR_descriptor_update_template[] 4470or the equivalent 4471 4472include::{generated}/api/flags/VkDescriptorUpdateTemplateCreateFlagsKHR.adoc[] 4473endif::VK_KHR_descriptor_update_template[] 4474 4475tname:VkDescriptorUpdateTemplateCreateFlags is a bitmask type for setting a 4476mask, but is currently reserved for future use. 4477-- 4478 4479[open,refpage='VkDescriptorUpdateTemplateType',desc='Indicates the valid usage of the descriptor update template',type='enums'] 4480-- 4481The descriptor update template type is determined by the 4482slink:VkDescriptorUpdateTemplateCreateInfo::pname:templateType property, 4483which takes the following values: 4484 4485include::{generated}/api/enums/VkDescriptorUpdateTemplateType.adoc[] 4486 4487ifdef::VK_KHR_descriptor_update_template[] 4488or the equivalent 4489 4490include::{generated}/api/enums/VkDescriptorUpdateTemplateTypeKHR.adoc[] 4491endif::VK_KHR_descriptor_update_template[] 4492 4493 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET specifies that 4494 the descriptor update template will be used for descriptor set updates 4495 only. 4496ifdef::VK_KHR_push_descriptor[] 4497 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR specifies 4498 that the descriptor update template will be used for push descriptor 4499 updates only. 4500endif::VK_KHR_push_descriptor[] 4501-- 4502 4503 4504[open,refpage='VkDescriptorUpdateTemplateEntry',desc='Describes a single descriptor update of the descriptor update template',type='structs'] 4505-- 4506The sname:VkDescriptorUpdateTemplateEntry structure is defined as: 4507include::{generated}/api/structs/VkDescriptorUpdateTemplateEntry.adoc[] 4508 4509ifdef::VK_KHR_descriptor_update_template[] 4510or the equivalent 4511 4512include::{generated}/api/structs/VkDescriptorUpdateTemplateEntryKHR.adoc[] 4513endif::VK_KHR_descriptor_update_template[] 4514 4515 * pname:dstBinding is the descriptor binding to update when using this 4516 descriptor update template. 4517 * pname:dstArrayElement is the starting element in the array belonging to 4518 pname:dstBinding. 4519ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4520 If the descriptor binding identified by pname:dstBinding has a 4521 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 4522 pname:dstArrayElement specifies the starting byte offset to update. 4523endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4524 * pname:descriptorCount is the number of descriptors to update. 4525 If pname:descriptorCount is greater than the number of remaining array 4526 elements in the destination binding, those affect consecutive bindings 4527 in a manner similar to slink:VkWriteDescriptorSet above. 4528ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4529 If the descriptor binding identified by pname:dstBinding has a 4530 descriptor type of ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK then 4531 pname:descriptorCount specifies the number of bytes to update and the 4532 remaining array elements in the destination binding refer to the 4533 remaining number of bytes in it. 4534endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4535 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 4536 the descriptor. 4537 * pname:offset is the offset in bytes of the first binding in the raw data 4538 structure. 4539 * pname:stride is the stride in bytes between two consecutive array 4540 elements of the descriptor update information in the raw data structure. 4541 The actual pointer ptr for each array element j of update entry i is 4542 computed using the following formula: 4543+ 4544[source,c++] 4545---- 4546 const char *ptr = (const char *)pData + pDescriptorUpdateEntries[i].offset + j * pDescriptorUpdateEntries[i].stride 4547---- 4548+ 4549The stride is useful in case the bindings are stored in structs along with 4550other data. 4551ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4552If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 4553then the value of pname:stride is ignored and the stride is assumed to be 4554`1`, i.e. the descriptor update information for them is always specified as 4555a contiguous range. 4556endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4557 4558.Valid Usage 4559**** 4560 * [[VUID-VkDescriptorUpdateTemplateEntry-dstBinding-00354]] 4561 pname:dstBinding must: be a valid binding in the descriptor set layout 4562 implicitly specified when using a descriptor update template to update 4563 descriptors 4564 * [[VUID-VkDescriptorUpdateTemplateEntry-dstArrayElement-00355]] 4565 pname:dstArrayElement and pname:descriptorCount must: be less than or 4566 equal to the number of array elements in the descriptor set binding 4567 implicitly specified when using a descriptor update template to update 4568 descriptors, and all applicable consecutive bindings, as described by 4569 <<descriptorsets-updates-consecutive>> 4570ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4571 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02226]] 4572 If pname:descriptor type is 4573 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, pname:dstArrayElement 4574 must: be an integer multiple of `4` 4575 * [[VUID-VkDescriptorUpdateTemplateEntry-descriptor-02227]] 4576 If pname:descriptor type is 4577 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, pname:descriptorCount 4578 must: be an integer multiple of `4` 4579endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 4580**** 4581 4582include::{generated}/validity/structs/VkDescriptorUpdateTemplateEntry.adoc[] 4583-- 4584 4585[open,refpage='vkDestroyDescriptorUpdateTemplate',desc='Destroy a descriptor update template object',type='protos'] 4586-- 4587To destroy a descriptor update template, call: 4588 4589ifdef::VK_VERSION_1_1[] 4590include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplate.adoc[] 4591endif::VK_VERSION_1_1[] 4592 4593ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4594 4595ifdef::VK_KHR_descriptor_update_template[] 4596include::{generated}/api/protos/vkDestroyDescriptorUpdateTemplateKHR.adoc[] 4597endif::VK_KHR_descriptor_update_template[] 4598 4599 * pname:device is the logical device that has been used to create the 4600 descriptor update template 4601 * pname:descriptorUpdateTemplate is the descriptor update template to 4602 destroy. 4603 * pname:pAllocator controls host memory allocation as described in the 4604 <<memory-allocation, Memory Allocation>> chapter. 4605 4606ifndef::VKSC_VERSION_1_0[] 4607.Valid Usage 4608**** 4609 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00356]] 4610 If sname:VkAllocationCallbacks were provided when 4611 pname:descriptorUpdateTemplate was created, a compatible set of 4612 callbacks must: be provided here 4613 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00357]] 4614 If no sname:VkAllocationCallbacks were provided when 4615 pname:descriptorUpdateTemplate was created, pname:pAllocator must: be 4616 `NULL` 4617**** 4618endif::VKSC_VERSION_1_0[] 4619 4620include::{generated}/validity/protos/vkDestroyDescriptorUpdateTemplate.adoc[] 4621-- 4622 4623[open,refpage='vkUpdateDescriptorSetWithTemplate',desc='Update the contents of a descriptor set object using an update template',type='protos'] 4624-- 4625Once a sname:VkDescriptorUpdateTemplate has been created, descriptor sets 4626can: be updated by calling: 4627 4628ifdef::VK_VERSION_1_1[] 4629include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplate.adoc[] 4630endif::VK_VERSION_1_1[] 4631 4632ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 4633 4634ifdef::VK_KHR_descriptor_update_template[] 4635include::{generated}/api/protos/vkUpdateDescriptorSetWithTemplateKHR.adoc[] 4636endif::VK_KHR_descriptor_update_template[] 4637 4638 * pname:device is the logical device that updates the descriptor set. 4639 * pname:descriptorSet is the descriptor set to update 4640 * pname:descriptorUpdateTemplate is a slink:VkDescriptorUpdateTemplate 4641 object specifying the update mapping between pname:pData and the 4642 descriptor set to update. 4643 * pname:pData is a pointer to memory containing one or more 4644 slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or 4645 slink:VkBufferView structures 4646ifdef::VK_KHR_acceleration_structure[or slink:VkAccelerationStructureKHR] 4647ifdef::VK_NV_ray_tracing[or slink:VkAccelerationStructureNV] 4648ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[handles] 4649 used to write the descriptors. 4650 4651.Valid Usage 4652**** 4653 * [[VUID-vkUpdateDescriptorSetWithTemplate-pData-01685]] 4654 pname:pData must: be a valid pointer to a memory containing one or more 4655 valid instances of slink:VkDescriptorImageInfo, 4656 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 4657 by pname:descriptorUpdateTemplate when it was created with 4658 flink:vkCreateDescriptorUpdateTemplate 4659 * [[VUID-vkUpdateDescriptorSetWithTemplate-descriptorSet-06995]] 4660 Host access to pname:descriptorSet must: be 4661 <<fundamentals-threadingbehavior,externally synchronized>> 4662ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4663 unless explicitly denoted otherwise for specific flags 4664endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4665**** 4666 4667include::{generated}/validity/protos/vkUpdateDescriptorSetWithTemplate.adoc[] 4668 4669.API example 4670[source,c++] 4671---- 4672struct AppBufferView { 4673 VkBufferView bufferView; 4674 uint32_t applicationRelatedInformation; 4675}; 4676 4677struct AppDataStructure 4678{ 4679 VkDescriptorImageInfo imageInfo; // a single image info 4680 VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array 4681 AppBufferView bufferView[2]; // An application defined structure containing a bufferView 4682 // ... some more application related data 4683}; 4684 4685const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 4686{ 4687 // binding to a single image descriptor 4688 { 4689 .binding = 0, 4690 .dstArrayElement = 0, 4691 .descriptorCount = 1, 4692 .descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 4693 .offset = offsetof(AppDataStructure, imageInfo), 4694 .stride = 0 // stride not required if descriptorCount is 1 4695 }, 4696 4697 // binding to an array of buffer descriptors 4698 { 4699 .binding = 1, 4700 .dstArrayElement = 0, 4701 .descriptorCount = 3, 4702 .descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 4703 .offset = offsetof(AppDataStructure, bufferInfoArray), 4704 .stride = sizeof(VkDescriptorBufferInfo) // descriptor buffer infos are compact 4705 }, 4706 4707 // binding to an array of buffer views 4708 { 4709 .binding = 2, 4710 .dstArrayElement = 0, 4711 .descriptorCount = 2, 4712 .descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, 4713 .offset = offsetof(AppDataStructure, bufferView) + 4714 offsetof(AppBufferView, bufferView), 4715 .stride = sizeof(AppBufferView) // bufferViews do not have to be compact 4716 }, 4717}; 4718 4719// create a descriptor update template for descriptor set updates 4720const VkDescriptorUpdateTemplateCreateInfo createInfo = 4721{ 4722 .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, 4723 .pNext = NULL, 4724 .flags = 0, 4725 .descriptorUpdateEntryCount = 3, 4726 .pDescriptorUpdateEntries = descriptorUpdateTemplateEntries, 4727 .templateType = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 4728 .descriptorSetLayout = myLayout, 4729 .pipelineBindPoint = 0, // ignored by given templateType 4730 .pipelineLayout = 0, // ignored by given templateType 4731 .set = 0, // ignored by given templateType 4732}; 4733 4734VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 4735myResult = vkCreateDescriptorUpdateTemplate( 4736 myDevice, 4737 &createInfo, 4738 NULL, 4739 &myDescriptorUpdateTemplate); 4740 4741AppDataStructure appData; 4742 4743// fill appData here or cache it in your engine 4744vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData); 4745---- 4746-- 4747endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 4748 4749endif::VKSC_VERSION_1_0[] 4750 4751 4752[[descriptorsets-binding]] 4753=== Descriptor Set Binding 4754 4755[open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] 4756-- 4757To bind one or more descriptor sets to a command buffer, call: 4758 4759include::{generated}/api/protos/vkCmdBindDescriptorSets.adoc[] 4760 4761 * pname:commandBuffer is the command buffer that the descriptor sets will 4762 be bound to. 4763 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4764 type of the pipeline that will use the descriptors. 4765 There is a separate set of bind points for each pipeline type, so 4766 binding one does not disturb the others. 4767 * pname:layout is a slink:VkPipelineLayout object used to program the 4768 bindings. 4769 * pname:firstSet is the set number of the first descriptor set to be 4770 bound. 4771 * pname:descriptorSetCount is the number of elements in the 4772 pname:pDescriptorSets array. 4773 * pname:pDescriptorSets is a pointer to an array of handles to 4774 slink:VkDescriptorSet objects describing the descriptor sets to bind to. 4775 * pname:dynamicOffsetCount is the number of dynamic offsets in the 4776 pname:pDynamicOffsets array. 4777 * pname:pDynamicOffsets is a pointer to an array of code:uint32_t values 4778 specifying dynamic offsets. 4779 4780fname:vkCmdBindDescriptorSets binds descriptor sets 4781pname:pDescriptorSets[0..pname:descriptorSetCount-1] to set numbers 4782[pname:firstSet..pname:firstSet+pname:descriptorSetCount-1] for subsequent 4783<<pipelines-bindpoint-commands, bound pipeline commands>> set by 4784pname:pipelineBindPoint. 4785Any bindings that were previously applied via these sets 4786ifdef::VK_EXT_descriptor_buffer[] 4787, or calls to flink:vkCmdSetDescriptorBufferOffsetsEXT or 4788flink:vkCmdBindDescriptorBufferEmbeddedSamplersEXT, 4789endif::VK_EXT_descriptor_buffer[] 4790are no longer valid. 4791 4792Once bound, a descriptor set affects rendering of subsequent commands that 4793interact with the given pipeline type in the command buffer until either a 4794different set is bound to the same set number, or the set is disturbed as 4795described in <<descriptorsets-compatibility, Pipeline Layout 4796Compatibility>>. 4797 4798A compatible descriptor set must: be bound for all set numbers that any 4799shaders in a pipeline access, at the time that a drawing or dispatching 4800command is recorded to execute using that pipeline. 4801However, if none of the shaders in a pipeline statically use any bindings 4802with a particular set number, then no descriptor set need be bound for that 4803set number, even if the pipeline layout includes a non-trivial descriptor 4804set layout for that set number. 4805 4806[[descriptor-validity]] 4807When consuming a descriptor, a descriptor is considered valid if the 4808descriptor is not undefined: as described by 4809<<descriptor-set-initial-state,descriptor set allocation>>. 4810ifdef::VK_EXT_robustness2[] 4811If the <<features-nullDescriptor, pname:nullDescriptor>> feature is enabled, 4812a null descriptor is also considered valid. 4813endif::VK_EXT_robustness2[] 4814A descriptor that was disturbed by <<descriptorsets-compatibility, Pipeline 4815Layout Compatibility>>, or was never bound by fname:vkCmdBindDescriptorSets 4816is not considered valid. 4817If a pipeline accesses a descriptor either statically or dynamically 4818depending on the elink:VkDescriptorBindingFlagBits, the consuming descriptor 4819type in the pipeline must: match the elink:VkDescriptorType in 4820slink:VkDescriptorSetLayoutCreateInfo for the descriptor to be considered 4821valid. 4822ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4823If a descriptor is a mutable descriptor, the consuming descriptor type in 4824the pipeline must: match the active descriptor type for the descriptor to be 4825considered valid. 4826endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4827 4828[NOTE] 4829.Note 4830==== 4831Further validation may be carried out beyond validation for descriptor 4832types, e.g. <<textures-input-validation,Texel Input Validation>>. 4833==== 4834 4835[[descriptorsets-binding-dynamicoffsets]] 4836If any of the sets being bound include dynamic uniform or storage buffers, 4837then pname:pDynamicOffsets includes one element for each array element in 4838each dynamic descriptor type binding in each set. 4839Values are taken from pname:pDynamicOffsets in an order such that all 4840entries for set N come before set N+1; within a set, entries are ordered by 4841the binding numbers in the descriptor set layouts; and within a binding 4842array, elements are in order. 4843pname:dynamicOffsetCount must: equal the total number of dynamic descriptors 4844in the sets being bound. 4845 4846[[dynamic-effective-offset]] 4847The effective offset used for dynamic uniform and storage buffer bindings is 4848the sum of the relative offset taken from pname:pDynamicOffsets, and the 4849base address of the buffer plus base offset in the descriptor set. 4850The range of the dynamic uniform and storage buffer bindings is the buffer 4851range as specified in the descriptor set. 4852 4853Each of the pname:pDescriptorSets must: be compatible with the pipeline 4854layout specified by pname:layout. 4855The layout used to program the bindings must: also be compatible with the 4856pipeline used in subsequent <<pipelines-bindpoint-commands, bound pipeline 4857commands>> with that pipeline type, as defined in the 4858<<descriptorsets-compatibility, Pipeline Layout Compatibility>> section. 4859 4860The descriptor set contents bound by a call to fname:vkCmdBindDescriptorSets 4861may: be consumed at the following times: 4862 4863ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4864 * For descriptor bindings created with the 4865 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT bit set, the contents 4866 may: be consumed when the command buffer is submitted to a queue, or 4867 during shader execution of the resulting draws and dispatches, or any 4868 time in between. 4869 Otherwise, 4870endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 4871 * during host execution of the command, or during shader execution of the 4872 resulting draws and dispatches, or any time in between. 4873 4874Thus, the contents of a descriptor set binding must: not be altered 4875(overwritten by an update command, or freed) between the first point in time 4876that it may: be consumed, and when the command completes executing on the 4877queue. 4878 4879The contents of pname:pDynamicOffsets are consumed immediately during 4880execution of fname:vkCmdBindDescriptorSets. 4881Once all pending uses have completed, it is legal to update and reuse a 4882descriptor set. 4883 4884.Valid Usage 4885**** 4886 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-00358]] 4887 Each element of pname:pDescriptorSets must: have been allocated with a 4888 sname:VkDescriptorSetLayout that matches (is the same as, or identically 4889 defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, 4890 where _n_ is the sum of pname:firstSet and the index into 4891 pname:pDescriptorSets 4892 * [[VUID-vkCmdBindDescriptorSets-dynamicOffsetCount-00359]] 4893 pname:dynamicOffsetCount must: be equal to the total number of dynamic 4894 descriptors in pname:pDescriptorSets 4895 * [[VUID-vkCmdBindDescriptorSets-firstSet-00360]] 4896 The sum of pname:firstSet and pname:descriptorSetCount must: be less 4897 than or equal to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount 4898 provided when pname:layout was created 4899 * [[VUID-vkCmdBindDescriptorSets-pipelineBindPoint-00361]] 4900 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 4901 parent sname:VkCommandPool's queue family 4902 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01971]] 4903 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4904 binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: 4905 be a multiple of 4906 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 4907 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01972]] 4908 Each element of pname:pDynamicOffsets which corresponds to a descriptor 4909 binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: 4910 be a multiple of 4911 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 4912 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-01979]] 4913 For each dynamic uniform or storage buffer binding in 4914 pname:pDescriptorSets, the sum of the <<dynamic-effective-offset, 4915 effective offset>> and the range of the binding must: be less than or 4916 equal to the size of the buffer 4917 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-06715]] 4918 For each dynamic uniform or storage buffer binding in 4919 pname:pDescriptorSets, if the range was set with ename:VK_WHOLE_SIZE 4920 then pname:pDynamicOffsets which corresponds to the descriptor binding 4921 must: be 0 4922ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4923 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-04616]] 4924 Each element of pname:pDescriptorSets must: not have been allocated from 4925 a sname:VkDescriptorPool with the 4926 ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT flag set 4927endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] 4928 * [[VUID-vkCmdBindDescriptorSets-graphicsPipelineLibrary-06754]] 4929ifdef::VK_EXT_graphics_pipeline_library[] 4930 If <<features-graphicsPipelineLibrary, pname:graphicsPipelineLibrary>> 4931 is not enabled, each 4932endif::VK_EXT_graphics_pipeline_library[] 4933ifndef::VK_EXT_graphics_pipeline_library[Each] 4934 element of pname:pDescriptorSets must: be a valid slink:VkDescriptorSet 4935ifdef::VK_EXT_descriptor_buffer[] 4936 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-08010]] 4937 Each element of pname:pDescriptorSets must: have been allocated with a 4938 sname:VkDescriptorSetLayout which was not created with 4939 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT 4940endif::VK_EXT_descriptor_buffer[] 4941**** 4942 4943include::{generated}/validity/protos/vkCmdBindDescriptorSets.adoc[] 4944-- 4945 4946 4947ifdef::VK_KHR_push_descriptor[] 4948[[descriptorsets-push-descriptors]] 4949=== Push Descriptor Updates 4950 4951[open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] 4952-- 4953In addition to allocating descriptor sets and binding them to a command 4954buffer, an application can: record descriptor updates into the command 4955buffer. 4956 4957To push descriptor updates into a command buffer, call: 4958 4959include::{generated}/api/protos/vkCmdPushDescriptorSetKHR.adoc[] 4960 4961 * pname:commandBuffer is the command buffer that the descriptors will be 4962 recorded in. 4963 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 4964 type of the pipeline that will use the descriptors. 4965 There is a separate set of push descriptor bindings for each pipeline 4966 type, so binding one does not disturb the others. 4967 * pname:layout is a slink:VkPipelineLayout object used to program the 4968 bindings. 4969 * pname:set is the set number of the descriptor set in the pipeline layout 4970 that will be updated. 4971 * pname:descriptorWriteCount is the number of elements in the 4972 pname:pDescriptorWrites array. 4973 * pname:pDescriptorWrites is a pointer to an array of 4974 slink:VkWriteDescriptorSet structures describing the descriptors to be 4975 updated. 4976 4977_Push descriptors_ are a small bank of descriptors whose storage is 4978internally managed by the command buffer rather than being written into a 4979descriptor set and later bound to a command buffer. 4980Push descriptors allow for incremental updates of descriptors without 4981managing the lifetime of descriptor sets. 4982 4983When a command buffer begins recording, all push descriptors are undefined:. 4984Push descriptors can: be updated incrementally and cause shaders to use the 4985updated descriptors for subsequent <<pipelines-bindpoint-commands, bound 4986pipeline commands>> with the pipeline type set by pname:pipelineBindPoint 4987until the descriptor is overwritten, or else until the set is disturbed as 4988described in <<descriptorsets-compatibility, Pipeline Layout 4989Compatibility>>. 4990When the set is disturbed or push descriptors with a different descriptor 4991set layout are set, all push descriptors are undefined:. 4992 4993Push descriptors that are <<shaders-staticuse,statically used>> by a 4994pipeline must: not be undefined: at the time that a drawing or dispatching 4995command is recorded to execute using that pipeline. 4996This includes immutable sampler descriptors, which must: be pushed before 4997they are accessed by a pipeline (the immutable samplers are pushed, rather 4998than the samplers in pname:pDescriptorWrites). 4999Push descriptors that are not statically used can: remain undefined:. 5000 5001Push descriptors do not use dynamic offsets. 5002Instead, the corresponding non-dynamic descriptor types can: be used and the 5003pname:offset member of slink:VkDescriptorBufferInfo can: be changed each 5004time the descriptor is written. 5005 5006Each element of pname:pDescriptorWrites is interpreted as in 5007slink:VkWriteDescriptorSet, except the pname:dstSet member is ignored. 5008 5009To push an immutable sampler, use a slink:VkWriteDescriptorSet with 5010pname:dstBinding and pname:dstArrayElement selecting the immutable sampler's 5011binding. 5012If the descriptor type is ename:VK_DESCRIPTOR_TYPE_SAMPLER, the 5013pname:pImageInfo parameter is ignored and the immutable sampler is taken 5014from the push descriptor set layout in the pipeline layout. 5015If the descriptor type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 5016the pname:sampler member of the pname:pImageInfo parameter is ignored and 5017the immutable sampler is taken from the push descriptor set layout in the 5018pipeline layout. 5019 5020.Valid Usage 5021**** 5022 * [[VUID-vkCmdPushDescriptorSetKHR-pipelineBindPoint-00363]] 5023 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 5024 parent sname:VkCommandPool's queue family 5025 * [[VUID-vkCmdPushDescriptorSetKHR-set-00364]] 5026 pname:set must: be less than 5027 slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 5028 pname:layout was created 5029 * [[VUID-vkCmdPushDescriptorSetKHR-set-00365]] 5030 pname:set must: be the unique set number in the pipeline layout that 5031 uses a descriptor set layout that was created with 5032 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 5033 * [[VUID-vkCmdPushDescriptorSetKHR-pDescriptorWrites-06494]] 5034 For each element [eq]#i# where 5035 pname:pDescriptorWrites[i].pname:descriptorType is 5036 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 5037 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 5038 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 5039 pname:pDescriptorWrites[i].pname:pImageInfo must: be a valid pointer to 5040 an array of pname:pDescriptorWrites[i].pname:descriptorCount valid 5041 sname:VkDescriptorImageInfo structures 5042**** 5043 5044include::{generated}/validity/protos/vkCmdPushDescriptorSetKHR.adoc[] 5045-- 5046 5047 5048ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 5049=== Push Descriptor Updates With Descriptor Update Templates 5050 5051[open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] 5052-- 5053It is also possible to use a descriptor update template to specify the push 5054descriptors to update. 5055To do so, call: 5056 5057include::{generated}/api/protos/vkCmdPushDescriptorSetWithTemplateKHR.adoc[] 5058 5059 * pname:commandBuffer is the command buffer that the descriptors will be 5060 recorded in. 5061 * pname:descriptorUpdateTemplate is a descriptor update template defining 5062 how to interpret the descriptor information in pname:pData. 5063 * pname:layout is a slink:VkPipelineLayout object used to program the 5064 bindings. 5065 It must: be compatible with the layout used to create the 5066 pname:descriptorUpdateTemplate handle. 5067 * pname:set is the set number of the descriptor set in the pipeline layout 5068 that will be updated. 5069 This must: be the same number used to create the 5070 pname:descriptorUpdateTemplate handle. 5071 * pname:pData is a pointer to memory containing descriptors for the 5072 templated update. 5073 5074.Valid Usage 5075**** 5076 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366]] 5077 The pname:pipelineBindPoint specified during the creation of the 5078 descriptor update template must: be supported by the 5079 pname:commandBuffer's parent sname:VkCommandPool's queue family 5080 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] 5081 pname:pData must: be a valid pointer to a memory containing one or more 5082 valid instances of slink:VkDescriptorImageInfo, 5083 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 5084 by pname:descriptorUpdateTemplate when it was created with 5085 flink:vkCreateDescriptorUpdateTemplate 5086 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-layout-07993]] 5087 pname:layout must: be compatible with the layout used to create 5088 pname:descriptorUpdateTemplate 5089 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-descriptorUpdateTemplate-07994]] 5090 pname:descriptorUpdateTemplate must: have been created with a 5091 pname:templateType of 5092 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 5093 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07995]] 5094 pname:set must: be the same value used to create 5095 pname:descriptorUpdateTemplate 5096 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07304]] 5097 pname:set must: be less than 5098 slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 5099 pname:layout was created 5100 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07305]] 5101 pname:set must: be the unique set number in the pipeline layout that 5102 uses a descriptor set layout that was created with 5103 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 5104**** 5105 5106include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.adoc[] 5107 5108.API example 5109[source,c++] 5110---- 5111 5112struct AppDataStructure 5113{ 5114 VkDescriptorImageInfo imageInfo; // a single image info 5115 // ... some more application related data 5116}; 5117 5118const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 5119{ 5120 // binding to a single image descriptor 5121 { 5122 .binding = 0, 5123 .dstArrayElement = 0, 5124 .descriptorCount = 1, 5125 .descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 5126 .offset = offsetof(AppDataStructure, imageInfo), 5127 .stride = 0 // not required if descriptorCount is 1 5128 } 5129}; 5130 5131// create a descriptor update template for push descriptor set updates 5132const VkDescriptorUpdateTemplateCreateInfo createInfo = 5133{ 5134 .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, 5135 .pNext = NULL, 5136 .flags = 0, 5137 .descriptorUpdateEntryCount = 1, 5138 .pDescriptorUpdateEntries = descriptorUpdateTemplateEntries, 5139 .templateType = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 5140 .descriptorSetLayout = 0, // ignored by given templateType 5141 .pipelineBindPoint = VK_PIPELINE_BIND_POINT_GRAPHICS, 5142 .pipelineLayout = myPipelineLayout, 5143 .set = 0, 5144}; 5145 5146VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 5147myResult = vkCreateDescriptorUpdateTemplate( 5148 myDevice, 5149 &createInfo, 5150 NULL, 5151 &myDescriptorUpdateTemplate); 5152 5153AppDataStructure appData; 5154// fill appData here or cache it in your engine 5155vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); 5156---- 5157-- 5158endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 5159endif::VK_KHR_push_descriptor[] 5160 5161 5162[[descriptorsets-push-constants]] 5163=== Push Constant Updates 5164 5165As described above in section <<descriptorsets-pipelinelayout, Pipeline 5166Layouts>>, the pipeline layout defines shader push constants which are 5167updated via Vulkan commands rather than via writes to memory or copy 5168commands. 5169 5170[NOTE] 5171.Note 5172==== 5173Push constants represent a high speed path to modify constant data in 5174pipelines that is expected to outperform memory-backed resource updates. 5175==== 5176 5177[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] 5178-- 5179To update push constants, call: 5180 5181include::{generated}/api/protos/vkCmdPushConstants.adoc[] 5182 5183 * pname:commandBuffer is the command buffer in which the push constant 5184 update will be recorded. 5185 * pname:layout is the pipeline layout used to program the push constant 5186 updates. 5187 * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying 5188 the shader stages that will use the push constants in the updated range. 5189 * pname:offset is the start offset of the push constant range to update, 5190 in units of bytes. 5191 * pname:size is the size of the push constant range to update, in units of 5192 bytes. 5193 * pname:pValues is a pointer to an array of pname:size bytes containing 5194 the new push constant values. 5195 5196When a command buffer begins recording, all push constant values are 5197undefined:. 5198ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] 5199Reads of undefined: push constant values by the executing shader return 5200undefined: values. 5201endif::VK_VERSION_1_3,VK_KHR_maintenance4[] 5202 5203Push constant values can: be updated incrementally, causing shader stages in 5204pname:stageFlags to read the new data from pname:pValues for push constants 5205modified by this command, while still reading the previous data for push 5206constants not modified by this command. 5207When a <<pipelines-bindpoint-commands, bound pipeline command>> is issued, 5208the bound pipeline's layout must: be compatible with the layouts used to set 5209the values of all push constants in the pipeline layout's push constant 5210ranges, as described in <<descriptorsets-compatibility,Pipeline Layout 5211Compatibility>>. 5212Binding a pipeline with a layout that is not compatible with the push 5213constant layout does not disturb the push constant values. 5214 5215[NOTE] 5216.Note 5217==== 5218As pname:stageFlags needs to include all flags the relevant push constant 5219ranges were created with, any flags that are not supported by the queue 5220family that the slink:VkCommandPool used to allocate pname:commandBuffer was 5221created on are ignored. 5222==== 5223 5224.Valid Usage 5225**** 5226 * [[VUID-vkCmdPushConstants-offset-01795]] 5227 For each byte in the range specified by pname:offset and pname:size and 5228 for each shader stage in pname:stageFlags, there must: be a push 5229 constant range in pname:layout that includes that byte and that stage 5230 * [[VUID-vkCmdPushConstants-offset-01796]] 5231 For each byte in the range specified by pname:offset and pname:size and 5232 for each push constant range that overlaps that byte, pname:stageFlags 5233 must: include all stages in that push constant range's 5234 slink:VkPushConstantRange::pname:stageFlags 5235 * [[VUID-vkCmdPushConstants-offset-00368]] 5236 pname:offset must: be a multiple of `4` 5237 * [[VUID-vkCmdPushConstants-size-00369]] 5238 pname:size must: be a multiple of `4` 5239 * [[VUID-vkCmdPushConstants-offset-00370]] 5240 pname:offset must: be less than 5241 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 5242 * [[VUID-vkCmdPushConstants-size-00371]] 5243 pname:size must: be less than or equal to 5244 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 5245 pname:offset 5246**** 5247 5248include::{generated}/validity/protos/vkCmdPushConstants.adoc[] 5249-- 5250 5251 5252ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 5253[[descriptorsets-physical-storage-buffer]] 5254== Physical Storage Buffer Access 5255 5256[open,refpage='vkGetBufferDeviceAddress',desc='Query an address of a buffer',type='protos',alias='vkGetBufferDeviceAddressKHR'] 5257-- 5258To query a 64-bit buffer device address value through which buffer memory 5259can: be accessed in a shader, call: 5260 5261ifdef::VK_VERSION_1_2[] 5262include::{generated}/api/protos/vkGetBufferDeviceAddress.adoc[] 5263endif::VK_VERSION_1_2[] 5264 5265ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 5266 5267ifdef::VK_KHR_buffer_device_address[] 5268include::{generated}/api/protos/vkGetBufferDeviceAddressKHR.adoc[] 5269endif::VK_KHR_buffer_device_address[] 5270 5271// Jon: 3-way conditional logic here is wrong 5272 5273ifdef::VK_EXT_buffer_device_address[] 5274or the equivalent command 5275 5276include::{generated}/api/protos/vkGetBufferDeviceAddressEXT.adoc[] 5277endif::VK_EXT_buffer_device_address[] 5278 5279 * pname:device is the logical device that the buffer was created on. 5280 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 5281 specifying the buffer to retrieve an address for. 5282 5283The 64-bit return value is an address of the start of pname:pInfo->buffer. 5284The address range starting at this value and whose size is the size of the 5285buffer can: be used in a shader to access the memory bound to that buffer, 5286using the 5287ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5288`SPV_KHR_physical_storage_buffer` extension 5289ifdef::VK_EXT_buffer_device_address[or the equivalent] 5290endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5291ifdef::VK_EXT_buffer_device_address[] 5292`SPV_EXT_physical_storage_buffer` extension 5293endif::VK_EXT_buffer_device_address[] 5294and the code:PhysicalStorageBuffer storage class. 5295For example, this value can: be stored in a uniform buffer, and the shader 5296can: read the value from the uniform buffer and use it to do a dependent 5297read/write to this buffer. 5298A value of zero is reserved as a "`null`" pointer and must: not be returned 5299as a valid buffer device address. 5300All loads, stores, and atomics in a shader through 5301code:PhysicalStorageBuffer pointers must: access addresses in the address 5302range of some buffer. 5303 5304If the buffer was created with a non-zero value of 5305ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5306ifdef::VK_EXT_buffer_device_address[slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress or] 5307ifndef::VK_EXT_buffer_device_address[slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress,] 5308endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5309ifdef::VK_EXT_buffer_device_address[] 5310slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress, 5311endif::VK_EXT_buffer_device_address[] 5312the return value will be the same address that was returned at capture time. 5313 5314The returned address must: satisfy the alignment requirement specified by 5315slink:VkMemoryRequirements::pname:alignment for the buffer in 5316slink:VkBufferDeviceAddressInfo::pname:buffer. 5317 5318If multiple slink:VkBuffer objects are bound to overlapping ranges of 5319slink:VkDeviceMemory, implementations may: return address ranges which 5320overlap. 5321In this case, it is ambiguous which slink:VkBuffer is associated with any 5322given device address. 5323For purposes of valid usage, if multiple slink:VkBuffer objects can: be 5324attributed to a device address, a slink:VkBuffer is selected such that valid 5325usage passes, if it exists. 5326 5327.Valid Usage 5328**** 5329 * [[VUID-vkGetBufferDeviceAddress-bufferDeviceAddress-03324]] 5330 The <<features-bufferDeviceAddress, pname:bufferDeviceAddress>> 5331ifdef::VK_EXT_buffer_device_address[] 5332 or <<features-bufferDeviceAddressEXT, 5333 sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddress>> 5334endif::VK_EXT_buffer_device_address[] 5335 feature must: be enabled 5336 * [[VUID-vkGetBufferDeviceAddress-device-03325]] 5337 If pname:device was created with multiple physical devices, then the 5338 <<features-bufferDeviceAddressMultiDevice, 5339 pname:bufferDeviceAddressMultiDevice>> 5340ifdef::VK_EXT_buffer_device_address[] 5341 or <<features-bufferDeviceAddressMultiDeviceEXT, 5342 sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddressMultiDevice>> 5343endif::VK_EXT_buffer_device_address[] 5344 feature must: be enabled 5345**** 5346 5347include::{generated}/validity/protos/vkGetBufferDeviceAddress.adoc[] 5348-- 5349 5350[open,refpage='VkBufferDeviceAddressInfo',desc='Structure specifying the buffer to query an address for',type='structs',alias='VkBufferDeviceAddressInfoKHR,VkBufferDeviceAddressInfoEXT'] 5351-- 5352The sname:VkBufferDeviceAddressInfo structure is defined as: 5353 5354include::{generated}/api/structs/VkBufferDeviceAddressInfo.adoc[] 5355 5356ifdef::VK_KHR_buffer_device_address[] 5357or the equivalent 5358 5359include::{generated}/api/structs/VkBufferDeviceAddressInfoKHR.adoc[] 5360endif::VK_KHR_buffer_device_address[] 5361 5362// Jon: three-way conditional logic is broken 5363ifdef::VK_EXT_buffer_device_address[] 5364or the equivalent 5365 5366include::{generated}/api/structs/VkBufferDeviceAddressInfoEXT.adoc[] 5367endif::VK_EXT_buffer_device_address[] 5368 5369 * pname:sType is a elink:VkStructureType value identifying this structure. 5370 * pname:pNext is `NULL` or a pointer to a structure extending this 5371 structure. 5372 * pname:buffer specifies the buffer whose address is being queried. 5373 5374.Valid Usage 5375**** 5376 * [[VUID-VkBufferDeviceAddressInfo-buffer-02600]] 5377 If pname:buffer is non-sparse and was not created with the 5378 ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag, then it 5379 must: be bound completely and contiguously to a single 5380 sname:VkDeviceMemory object 5381 * [[VUID-VkBufferDeviceAddressInfo-buffer-02601]] 5382 pname:buffer must: have been created with 5383 ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT 5384**** 5385 5386include::{generated}/validity/structs/VkBufferDeviceAddressInfo.adoc[] 5387-- 5388endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] 5389 5390ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5391[open,refpage='vkGetBufferOpaqueCaptureAddress',desc='Query an opaque capture address of a buffer',type='protos',alias='vkGetBufferOpaqueCaptureAddressKHR'] 5392-- 5393To query a 64-bit buffer opaque capture address, call: 5394 5395ifdef::VK_VERSION_1_2[] 5396include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddress.adoc[] 5397endif::VK_VERSION_1_2[] 5398 5399ifdef::VK_VERSION_1_2+VK_KHR_buffer_device_address[or the equivalent command] 5400 5401ifdef::VK_KHR_buffer_device_address[] 5402include::{generated}/api/protos/vkGetBufferOpaqueCaptureAddressKHR.adoc[] 5403endif::VK_KHR_buffer_device_address[] 5404 5405 * pname:device is the logical device that the buffer was created on. 5406 * pname:pInfo is a pointer to a slink:VkBufferDeviceAddressInfo structure 5407 specifying the buffer to retrieve an address for. 5408 5409The 64-bit return value is an opaque capture address of the start of 5410pname:pInfo->buffer. 5411 5412If the buffer was created with a non-zero value of 5413slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress the 5414return value must: be the same address. 5415 5416.Valid Usage 5417**** 5418 * [[VUID-vkGetBufferOpaqueCaptureAddress-None-03326]] 5419 The <<features-bufferDeviceAddress, pname:bufferDeviceAddress>> feature 5420 must: be enabled 5421 * [[VUID-vkGetBufferOpaqueCaptureAddress-device-03327]] 5422 If pname:device was created with multiple physical devices, then the 5423 <<features-bufferDeviceAddressMultiDevice, 5424 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 5425**** 5426 5427include::{generated}/validity/protos/vkGetBufferOpaqueCaptureAddress.adoc[] 5428-- 5429endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] 5430 5431 5432ifdef::VK_EXT_descriptor_buffer[] 5433[[descriptorbuffers]] 5434== Descriptor Buffers 5435 5436If the <<features-descriptorBuffer, pname:descriptorBuffer>> feature is 5437enabled, an alternative way to specify descriptor sets is via buffers, 5438rather than descriptor set objects. 5439 5440 5441[[descriptorbuffers-puttingdescriptorsinmemory]] 5442=== Putting Descriptors in Memory 5443 5444Commands are provided to retrieve descriptor data, and also to locate where 5445in memory that data must: be written to match the given descriptor set 5446layout. 5447 5448[open,refpage='vkGetDescriptorSetLayoutSizeEXT',desc='Get the size of a descriptor set layout in memory',type='protos'] 5449-- 5450To determine the amount of memory needed to store all descriptors with a 5451given layout, call: 5452 5453include::{generated}/api/protos/vkGetDescriptorSetLayoutSizeEXT.adoc[] 5454 5455 * pname:device is the logical device that gets the size. 5456 * pname:layout is the descriptor set layout being queried. 5457 * pname:pLayoutSizeInBytes is a pointer to basetype:VkDeviceSize where the 5458 size in bytes will be written. 5459 5460The size of a descriptor set layout will be at least as large as the sum 5461total of the size of all descriptors in the layout, and may: be larger. 5462This size represents the amount of memory that will be required to store all 5463of the descriptors for this layout in memory, when placed according to the 5464layout's offsets as obtained by 5465flink:vkGetDescriptorSetLayoutBindingOffsetEXT. 5466 5467ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 5468If any pname:binding in pname:layout is 5469ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, the returned size 5470includes space for the maximum pname:descriptorCount descriptors as declared 5471for that pname:binding. 5472To compute the required size of a descriptor set with a 5473ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT: 5474 5475 {empty}:: [eq]#size = offset + descriptorSize {times} 5476 variableDescriptorCount# 5477 5478where [eq]#offset# is obtained by 5479flink:vkGetDescriptorSetLayoutBindingOffsetEXT and [eq]#descriptorSize# is 5480the size of the relevant descriptor as obtained from 5481slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT, and 5482[eq]#variableDescriptorCount# is the equivalent of 5483slink:VkDescriptorSetVariableDescriptorCountAllocateInfo::pname:pDescriptorCounts. 5484ifdef::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 5485For ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK, 5486[eq]#variableDescriptorCount# is the size in bytes for the inline uniform 5487block, and [eq]#descriptorSize# is 1. 5488endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] 5489 5490If 5491slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:combinedImageSamplerDescriptorSingleArray 5492is ename:VK_FALSE and the variable descriptor type is 5493ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 5494[eq]#variableDescriptorCount# is always considered to be the upper bound. 5495endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 5496 5497.Valid Usage 5498**** 5499 * [[VUID-vkGetDescriptorSetLayoutSizeEXT-None-08011]] 5500 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 5501 be enabled 5502 * [[VUID-vkGetDescriptorSetLayoutSizeEXT-layout-08012]] 5503 pname:layout must: have been created with the 5504 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT flag set 5505**** 5506 5507include::{generated}/validity/protos/vkGetDescriptorSetLayoutSizeEXT.adoc[] 5508-- 5509 5510[open,refpage='vkGetDescriptorSetLayoutBindingOffsetEXT',desc='Get the offset of a binding within a descriptor set layout',type='protos'] 5511-- 5512To get the offset of a binding within a descriptor set layout in memory, 5513call: 5514 5515include::{generated}/api/protos/vkGetDescriptorSetLayoutBindingOffsetEXT.adoc[] 5516 5517 * pname:device is the logical device that gets the offset. 5518 * pname:layout is the descriptor set layout being queried. 5519 * pname:binding is the binding number being queried. 5520 * pname:pOffset is a pointer to basetype:VkDeviceSize where the byte 5521 offset of the binding will be written. 5522 5523Each binding in a descriptor set layout is assigned an offset in memory by 5524the implementation. 5525When a shader accesses a resource with that binding, it will access the 5526bound descriptor buffer from that offset to look for its descriptor. 5527This command provides an application with that offset, so that descriptors 5528can be placed in the correct locations. 5529The precise location accessed by a shader for a given descriptor is as 5530follows: 5531 5532 {empty}:: [eq]#location = bufferAddress {plus} setOffset {plus} 5533 descriptorOffset {plus} (arrayElement {times} descriptorSize)# 5534 5535where [eq]#bufferAddress# and [eq]#setOffset# are the base address and 5536offset for the identified descriptor set as specified by 5537flink:vkCmdBindDescriptorBuffersEXT and 5538flink:vkCmdSetDescriptorBufferOffsetsEXT, [eq]#descriptorOffset# is the 5539offset for the binding returned by this command, [eq]#arrayElement# is the 5540index into the array specified in the shader, and [eq]#descriptorSize# is 5541the size of the relevant descriptor as obtained from 5542slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT. 5543Applications are responsible for placing valid descriptors at the expected 5544location in order for a shader to access it. 5545The overall offset added to [eq]#bufferAddress# to calculate [eq]#location# 5546must: be less than 5547slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxSamplerDescriptorBufferRange 5548for samplers and 5549slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxResourceDescriptorBufferRange 5550for resources. 5551 5552ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 5553If any pname:binding in pname:layout is 5554ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, that 5555pname:binding must: have the largest offset of any pname:binding. 5556endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 5557 5558ifdef::VK_VALVE_mutable_descriptor_type[] 5559A descriptor pname:binding with type ename:VK_DESCRIPTOR_TYPE_MUTABLE_VALVE 5560can: be used. 5561Any potential types in 5562slink:VkMutableDescriptorTypeCreateInfoVALVE::pname:pDescriptorTypes for 5563pname:binding share the same offset. 5564If the size of the <<descriptorsets-mutable, mutable descriptor>> is larger 5565than the size of a concrete descriptor type being accessed, the padding area 5566is ignored by the implementation. 5567endif::VK_VALVE_mutable_descriptor_type[] 5568 5569.Valid Usage 5570**** 5571 * [[VUID-vkGetDescriptorSetLayoutBindingOffsetEXT-None-08013]] 5572 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 5573 be enabled 5574 * [[VUID-vkGetDescriptorSetLayoutBindingOffsetEXT-layout-08014]] 5575 pname:layout must: have been created with the 5576 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT flag set 5577**** 5578 5579include::{generated}/validity/protos/vkGetDescriptorSetLayoutBindingOffsetEXT.adoc[] 5580-- 5581 5582[open,refpage='vkGetDescriptorEXT',desc='To get a descriptor to place in a buffer',type='protos'] 5583-- 5584To get descriptor data to place in a buffer, call: 5585 5586include::{generated}/api/protos/vkGetDescriptorEXT.adoc[] 5587 5588 * pname:device is the logical device that gets the descriptor. 5589 * pname:pDescriptorInfo is a pointer to a slink:VkDescriptorGetInfoEXT 5590 structure specifying the parameters of the descriptor to get. 5591 * pname:dataSize is the amount of the descriptor data to get in bytes. 5592 * pname:pDescriptor is a pointer to a user-allocated buffer where the 5593 descriptor will be written. 5594 5595The size of the data for each descriptor type is determined by the value in 5596slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT. 5597This value also defines the stride in bytes for arrays of that descriptor 5598type. 5599 5600If the 5601slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:combinedImageSamplerDescriptorSingleArray 5602property is ename:VK_FALSE the implementation requires an array of 5603ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors to be written 5604into a descriptor buffer as an array of image descriptors, immediately 5605followed by an array of sampler descriptors. 5606Applications must: write the first 5607slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:sampledImageDescriptorSize 5608bytes of the data returned through pname:pDescriptor to the first array, and 5609the remaining 5610slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:samplerDescriptorSize 5611bytes of the data to the second array. 5612For variable-sized descriptor bindings of 5613ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors, the two arrays 5614each have a size equal to the upper bound pname:descriptorCount of that 5615binding. 5616 5617A descriptor obtained by this command references the underlying 5618slink:VkImageView or slink:VkSampler, and these objects must: not be 5619destroyed before the last time a descriptor is dynamically accessed. 5620For descriptor types which consume an address instead of an object, the 5621underlying slink:VkBuffer is referenced instead. 5622 5623.Valid Usage 5624**** 5625 * [[VUID-vkGetDescriptorEXT-None-08015]] 5626 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 5627 be enabled 5628 * [[VUID-vkGetDescriptorEXT-dataSize-08125]] 5629 pname:dataSize must: equal the size of a descriptor of type 5630 slink:VkDescriptorGetInfoEXT::pname:type determined by the value in 5631 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT 5632ifdef::VK_EXT_fragment_density_map[] 5633 , or determined by 5634 slink:VkPhysicalDeviceDescriptorBufferDensityMapPropertiesEXT::pname:combinedImageSamplerDensityMapDescriptorSize 5635 if pname:pDescriptorInfo specifies a 5636 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER whose slink:VkSampler 5637 was created with ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT set 5638endif::VK_EXT_fragment_density_map[] 5639 * [[VUID-vkGetDescriptorEXT-pDescriptor-08016]] 5640 pname:pDescriptor must: be a valid pointer to an array of at least 5641 pname:dataSize bytes 5642**** 5643 5644include::{generated}/validity/protos/vkGetDescriptorEXT.adoc[] 5645-- 5646 5647[open,refpage='VkDescriptorGetInfoEXT',desc='Structure specifying parameters of descriptor to get',type='structs'] 5648-- 5649Information about the descriptor to get is passed in a 5650sname:VkDescriptorGetInfoEXT structure: 5651 5652include::{generated}/api/structs/VkDescriptorGetInfoEXT.adoc[] 5653 5654 * pname:sType is a elink:VkStructureType value identifying this structure. 5655 * pname:pNext is `NULL` or a pointer to a structure extending this 5656 structure. 5657 * pname:type is the type of descriptor to get. 5658 * pname:data is a structure containing the information needed to get the 5659 descriptor. 5660 5661.Valid Usage 5662**** 5663 * [[VUID-VkDescriptorGetInfoEXT-type-08018]] 5664 pname:type must: not be ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, 5665 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC or 5666 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK 5667 * [[VUID-VkDescriptorGetInfoEXT-type-08019]] 5668 If pname:type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the 5669 pname:pCombinedImageSampler->sampler member of pname:data must: be a 5670 slink:VkSampler created on pname:device 5671 * [[VUID-VkDescriptorGetInfoEXT-type-08020]] 5672 If pname:type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the 5673 pname:pCombinedImageSampler->imageView member of pname:data must: be a 5674 slink:VkImageView created on pname:device, or dlink:VK_NULL_HANDLE 5675 * [[VUID-VkDescriptorGetInfoEXT-type-08021]] 5676 If pname:type is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the 5677 pname:pInputAttachmentImage->imageView member of pname:data must: be a 5678 slink:VkImageView created on pname:device 5679 * [[VUID-VkDescriptorGetInfoEXT-type-08022]] 5680 If pname:type is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and if 5681 pname:pSampledImage is not `NULL`, the pname:pSampledImage->imageView 5682 member of pname:data must: be a slink:VkImageView created on 5683 pname:device, or dlink:VK_NULL_HANDLE 5684 * [[VUID-VkDescriptorGetInfoEXT-type-08023]] 5685 If pname:type is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and if 5686 pname:pStorageImage is not `NULL`, the pname:pStorageImage->imageView 5687 member of pname:data must: be a slink:VkImageView created on 5688 pname:device, or dlink:VK_NULL_HANDLE 5689 * [[VUID-VkDescriptorGetInfoEXT-type-08024]] 5690 If pname:type is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, 5691 pname:pUniformTexelBuffer is not `NULL` and 5692 pname:pUniformTexelBuffer->address is not zero, 5693 pname:pUniformTexelBuffer->address must be an address within a 5694 slink:VkBuffer created on pname:device 5695 * [[VUID-VkDescriptorGetInfoEXT-type-08025]] 5696 If pname:type is ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, 5697 pname:pStorageTexelBuffer is not `NULL` and 5698 pname:pStorageTexelBuffer->address is not zero, 5699 pname:pStorageTexelBuffer->address must be an address within a 5700 slink:VkBuffer created on pname:device 5701 * [[VUID-VkDescriptorGetInfoEXT-type-08026]] 5702 If pname:type is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 5703 pname:pUniformBuffer is not `NULL` and pname:pUniformBuffer->address is 5704 not zero, pname:pUniformBuffer->address must be an address within a 5705 slink:VkBuffer created on pname:device 5706 * [[VUID-VkDescriptorGetInfoEXT-type-08027]] 5707 If pname:type is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 5708 pname:pStorageBuffer is not `NULL` and pname:pStorageBuffer->address is 5709 not zero, pname:pStorageBuffer->address must be an address within a 5710 slink:VkBuffer created on pname:device 5711ifdef::VK_KHR_acceleration_structure[] 5712 * [[VUID-VkDescriptorGetInfoEXT-type-08028]] 5713 If pname:type is ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR and 5714 pname:accelerationStructure is not `0`, pname:accelerationStructure 5715 must: contain the address of a slink:VkAccelerationStructureKHR created 5716 on pname:device 5717endif::VK_KHR_acceleration_structure[] 5718ifdef::VK_NV_ray_tracing[] 5719 * [[VUID-VkDescriptorGetInfoEXT-type-08029]] 5720 If pname:type is ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV and 5721 pname:accelerationStructure is not `0`, pname:accelerationStructure 5722 must: contain the handle of a slink:VkAccelerationStructureNV created on 5723 pname:device, returned by flink:vkGetAccelerationStructureHandleNV 5724endif::VK_NV_ray_tracing[] 5725**** 5726 5727include::{generated}/validity/structs/VkDescriptorGetInfoEXT.adoc[] 5728-- 5729 5730[open,refpage='VkDescriptorDataEXT',desc='Structure specifying descriptor data',type='structs'] 5731-- 5732Data describing the descriptor is passed in a sname:VkDescriptorDataEXT 5733structure: 5734 5735include::{generated}/api/structs/VkDescriptorDataEXT.adoc[] 5736 5737 * pname:pSampler is a pointer to a slink:VkSampler handle specifying the 5738 parameters of a ename:VK_DESCRIPTOR_TYPE_SAMPLER descriptor. 5739 * pname:pCombinedImageSampler is a pointer to a 5740 slink:VkDescriptorImageInfo structure specifying the parameters of a 5741 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptor. 5742 * pname:pInputAttachmentImage is a pointer to a 5743 slink:VkDescriptorImageInfo structure specifying the parameters of a 5744 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT descriptor. 5745 * pname:pSampledImage is a pointer to a slink:VkDescriptorImageInfo 5746 structure specifying the parameters of a 5747 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE descriptor. 5748 * pname:pStorageImage is a pointer to a slink:VkDescriptorImageInfo 5749 structure specifying the parameters of a 5750 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE descriptor. 5751 * pname:pUniformTexelBuffer is a pointer to a 5752 slink:VkDescriptorAddressInfoEXT structure specifying the parameters of 5753 a ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER descriptor. 5754 * pname:pStorageTexelBuffer is a pointer to a 5755 slink:VkDescriptorAddressInfoEXT structure specifying the parameters of 5756 a ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor. 5757 * pname:pUniformBuffer is a pointer to a slink:VkDescriptorAddressInfoEXT 5758 structure specifying the parameters of a 5759 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER descriptor. 5760 * pname:pStorageBuffer is a pointer to a slink:VkDescriptorAddressInfoEXT 5761 structure specifying the parameters of a 5762 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER descriptor. 5763ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[] 5764 * pname:accelerationStructure is 5765ifdef::VK_KHR_acceleration_structure[] 5766 the address of a slink:VkAccelerationStructureKHR specifying the 5767 parameters of a ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR 5768 descriptor 5769endif::VK_KHR_acceleration_structure[] 5770ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[, or ] 5771ifdef::VK_NV_ray_tracing[] 5772 a slink:VkAccelerationStructureNV handle specifying the parameters of a 5773 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV descriptor. 5774endif::VK_NV_ray_tracing[] 5775endif::VK_KHR_acceleration_structure+VK_NV_ray_tracing[] 5776ifndef::VK_NV_ray_tracing,VK_NV_ray_tracing[] 5777 * pname:accelerationStructure is reserved for future use and is ignored. 5778endif::VK_NV_ray_tracing,VK_NV_ray_tracing[] 5779 5780ifdef::VK_EXT_robustness2[] 5781If the <<features-nullDescriptor, pname:nullDescriptor>> feature is enabled, 5782pname:pSampledImage, pname:pStorageImage, pname:pUniformTexelBuffer, 5783pname:pStorageTexelBuffer, pname:pUniformBuffer, and pname:pStorageBuffer 5784can: each be `NULL`. 5785Loads from a null descriptor return zero values and stores and atomics to a 5786null descriptor are discarded. 5787 5788ifdef::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 5789If the <<features-nullDescriptor, pname:nullDescriptor>> feature is enabled, 5790pname:accelerationStructure can: be `0`. 5791A null acceleration structure descriptor results in the miss shader being 5792invoked. 5793endif::VK_KHR_acceleration_structure,VK_NV_ray_tracing[] 5794 5795.Valid Usage 5796**** 5797 * [[VUID-VkDescriptorDataEXT-type-08030]] 5798 If slink:VkDescriptorGetInfoEXT:pname:type is 5799 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, and 5800 pname:pUniformBuffer->address is the address of a non-sparse buffer, 5801 then that buffer must: be bound completely and contiguously to a single 5802 sname:VkDeviceMemory object 5803 * [[VUID-VkDescriptorDataEXT-type-08031]] 5804 If slink:VkDescriptorGetInfoEXT:pname:type is 5805 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, and 5806 pname:pStorageBuffer->address is the address of a non-sparse buffer, 5807 then that buffer must: be bound completely and contiguously to a single 5808 sname:VkDeviceMemory object 5809 * [[VUID-VkDescriptorDataEXT-type-08032]] 5810 If slink:VkDescriptorGetInfoEXT:pname:type is 5811 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, and 5812 pname:pUniformTexelBuffer->address is the address of a non-sparse 5813 buffer, then that buffer must: be bound completely and contiguously to a 5814 single sname:VkDeviceMemory object 5815 * [[VUID-VkDescriptorDataEXT-type-08033]] 5816 If slink:VkDescriptorGetInfoEXT:pname:type is 5817 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, and 5818 pname:pStorageTexelBuffer->address is the address of a non-sparse 5819 buffer, then that buffer must: be bound completely and contiguously to a 5820 single sname:VkDeviceMemory object 5821ifdef::VK_EXT_robustness2[] 5822 * [[VUID-VkDescriptorDataEXT-type-08034]] 5823 If slink:VkDescriptorGetInfoEXT:pname:type is 5824 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and the 5825 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5826 enabled, pname:pCombinedImageSampler->imageView must: not be 5827 dlink:VK_NULL_HANDLE 5828 * [[VUID-VkDescriptorDataEXT-type-08035]] 5829 If slink:VkDescriptorGetInfoEXT:pname:type is 5830 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and the 5831 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5832 enabled, pname:pSampledImage must: not be `NULL` and 5833 pname:pSampledImage->imageView must: not be dlink:VK_NULL_HANDLE 5834 * [[VUID-VkDescriptorDataEXT-type-08036]] 5835 If slink:VkDescriptorGetInfoEXT:pname:type is 5836 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and the 5837 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5838 enabled, pname:pStorageImage must: not be `NULL` and 5839 pname:pStorageImage->imageView must: not be dlink:VK_NULL_HANDLE 5840 * [[VUID-VkDescriptorDataEXT-type-08037]] 5841 If slink:VkDescriptorGetInfoEXT:pname:type is 5842 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, and the 5843 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5844 enabled, pname:pUniformTexelBuffer must: not be `NULL` 5845 * [[VUID-VkDescriptorDataEXT-type-08038]] 5846 If slink:VkDescriptorGetInfoEXT:pname:type is 5847 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, and the 5848 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5849 enabled, pname:pStorageTexelBuffer must: not be `NULL` 5850 * [[VUID-VkDescriptorDataEXT-type-08039]] 5851 If slink:VkDescriptorGetInfoEXT:pname:type is 5852 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, and the 5853 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5854 enabled, pname:pUniformBuffer must: not be `NULL` 5855 * [[VUID-VkDescriptorDataEXT-type-08040]] 5856 If slink:VkDescriptorGetInfoEXT:pname:type is 5857 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, and the 5858 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5859 enabled, pname:pStorageBuffer must: not be `NULL` 5860ifdef::VK_KHR_acceleration_structure[] 5861 * [[VUID-VkDescriptorDataEXT-type-08041]] 5862 If slink:VkDescriptorGetInfoEXT:pname:type is 5863 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR, and the 5864 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5865 enabled, pname:accelerationStructure must: not be `0` 5866endif::VK_KHR_acceleration_structure[] 5867ifdef::VK_NV_ray_tracing[] 5868 * [[VUID-VkDescriptorDataEXT-type-08042]] 5869 If slink:VkDescriptorGetInfoEXT:pname:type is 5870 ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV, and the 5871 <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5872 enabled, pname:accelerationStructure must: not be `0` 5873endif::VK_NV_ray_tracing[] 5874endif::VK_EXT_robustness2[] 5875**** 5876 5877include::{generated}/validity/structs/VkDescriptorDataEXT.adoc[] 5878 5879endif::VK_EXT_robustness2[] 5880-- 5881 5882[open,refpage='VkDescriptorAddressInfoEXT',desc='Structure specifying descriptor buffer address info',type='structs'] 5883-- 5884Data describing a ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 5885ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 5886ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, or 5887ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER descriptor is passed in a 5888sname:VkDescriptorAddressInfoEXT structure: 5889 5890include::{generated}/api/structs/VkDescriptorAddressInfoEXT.adoc[] 5891 5892 * pname:sType is a elink:VkStructureType value identifying this structure. 5893 * pname:pNext is `NULL` or a pointer to a structure extending this 5894 structure. 5895 * pname:address is either `0` or a device address at an offset in a 5896 buffer, where the base address can be queried from 5897 flink:vkGetBufferDeviceAddress. 5898 * pname:range is the size in bytes of the buffer or buffer view used by 5899 the descriptor. 5900 * pname:format is the format of the data elements in the buffer view and 5901 is ignored for buffers. 5902 5903.Valid Usage 5904**** 5905 * [[VUID-VkDescriptorAddressInfoEXT-address-08043]] 5906ifdef::VK_EXT_robustness2[] 5907 If the <<features-nullDescriptor, pname:nullDescriptor>> feature is not 5908 enabled, 5909endif::VK_EXT_robustness2[] 5910 pname:address must: not be zero 5911ifdef::VK_EXT_robustness2[] 5912 * [[VUID-VkDescriptorAddressInfoEXT-nullDescriptor-08938]] 5913 If pname:address is zero, pname:range must: be ename:VK_WHOLE_SIZE 5914endif::VK_EXT_robustness2[] 5915 * [[VUID-VkDescriptorAddressInfoEXT-nullDescriptor-08939]] 5916ifdef::VK_EXT_robustness2[] 5917 If pname:address is not zero, 5918endif::VK_EXT_robustness2[] 5919 pname:range must: not be ename:VK_WHOLE_SIZE 5920 * [[VUID-VkDescriptorAddressInfoEXT-None-08044]] 5921 If pname:address is not zero, pname:address must: be a valid device 5922 address at an offset within a slink:VkBuffer 5923 * [[VUID-VkDescriptorAddressInfoEXT-range-08045]] 5924 pname:range must: be less than or equal to the size of the buffer 5925 containing pname:address minus the offset of pname:address from the base 5926 address of the buffer 5927 * [[VUID-VkDescriptorAddressInfoEXT-range-08940]] 5928 pname:range must: not be zero 5929**** 5930 5931include::{generated}/validity/structs/VkDescriptorAddressInfoEXT.adoc[] 5932 5933ifdef::VK_EXT_robustness2[] 5934If the <<features-nullDescriptor, pname:nullDescriptor>> feature is enabled, 5935pname:address can: be zero. 5936Loads from a null descriptor return zero values and stores and atomics to a 5937null descriptor are discarded. 5938endif::VK_EXT_robustness2[] 5939-- 5940 5941Immutable samplers specified in a descriptor set layout through 5942pname:pImmutableSamplers must: be provided by applications when obtaining 5943descriptor data. 5944Immutable samplers written in a descriptor buffer must: have identical 5945parameters to the immutable samplers in the descriptor set layout that 5946consumes the sampler. 5947 5948[NOTE] 5949.Note 5950==== 5951If the descriptor set layout was created with 5952ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT, 5953there is no buffer backing for the immutable sampler, so this requirement 5954does not exist. 5955The implementation handles allocation of these descriptors internally. 5956==== 5957 5958[NOTE] 5959.Note 5960==== 5961As descriptors are now in regular memory, drivers cannot hide copies of 5962immutable samplers that end up in descriptor sets from the application. 5963As such, applications are required to provide these samplers as if they were 5964not provided immutably. 5965==== 5966 5967 5968[[descriptorbuffers-binding]] 5969=== Binding Descriptor Buffers 5970 5971Descriptor buffers have their own separate binding point on the command 5972buffer, with buffers bound using flink:vkCmdBindDescriptorBuffersEXT. 5973flink:vkCmdSetDescriptorBufferOffsetsEXT assigns pairs of buffer binding 5974indices and buffer offsets to the same binding point on the command buffer 5975as flink:vkCmdBindDescriptorSets, allowing subsequent 5976<<pipelines-bindpoint-commands, bound pipeline commands>> to use the 5977specified descriptor buffers. 5978Bindings applied via flink:vkCmdBindDescriptorSets cannot: exist 5979simultaneously with those applied via calls to 5980flink:vkCmdSetDescriptorBufferOffsetsEXT or 5981flink:vkCmdBindDescriptorBufferEmbeddedSamplersEXT, as calls to 5982flink:vkCmdSetDescriptorBufferOffsetsEXT or 5983flink:vkCmdBindDescriptorBufferEmbeddedSamplersEXT invalidate any bindings 5984by previous calls to flink:vkCmdBindDescriptorSets and vice-versa. 5985 5986[open,refpage='vkCmdBindDescriptorBuffersEXT',desc='Binding descriptor buffers to a command buffer',type='protos'] 5987-- 5988To bind descriptor buffers to a command buffer, call: 5989 5990include::{generated}/api/protos/vkCmdBindDescriptorBuffersEXT.adoc[] 5991 5992 * pname:commandBuffer is the command buffer that the descriptor buffers 5993 will be bound to. 5994 * pname:bufferCount is the number of elements in the pname:pBindingInfos 5995 array. 5996 * pname:pBindingInfos is a pointer to an array of 5997 slink:VkDescriptorBufferBindingInfoEXT structures. 5998 5999`vkCmdBindDescriptorBuffersEXT` causes any offsets previously set by 6000flink:vkCmdSetDescriptorBufferOffsetsEXT that use the bindings numbered 6001[`0`.. 6002pname:bufferCount-1] to be no longer valid for subsequent bound pipeline 6003commands. 6004Any previously bound buffers at binding points greater than or equal to 6005pname:bufferCount are unbound. 6006 6007.Valid Usage 6008**** 6009 * [[VUID-vkCmdBindDescriptorBuffersEXT-None-08047]] 6010 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 6011 be enabled 6012 * [[VUID-vkCmdBindDescriptorBuffersEXT-maxSamplerDescriptorBufferBindings-08048]] 6013 There must: be no more than 6014 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxSamplerDescriptorBufferBindings 6015 descriptor buffers containing sampler descriptor data bound 6016 * [[VUID-vkCmdBindDescriptorBuffersEXT-maxResourceDescriptorBufferBindings-08049]] 6017 There must: be no more than 6018 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxResourceDescriptorBufferBindings 6019 descriptor buffers containing resource descriptor data bound 6020 * [[VUID-vkCmdBindDescriptorBuffersEXT-None-08050]] 6021 There must: be no more than `1` descriptor buffer bound that was created 6022 with the 6023 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT bit set 6024 * [[VUID-vkCmdBindDescriptorBuffersEXT-bufferCount-08051]] 6025 pname:bufferCount must: be less than or equal to 6026 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxDescriptorBufferBindings 6027 * [[VUID-vkCmdBindDescriptorBuffersEXT-pBindingInfos-08052]] 6028 For any element of pname:pBindingInfos, if the buffer from which 6029 pname:address was queried is non-sparse then it must: be bound 6030 completely and contiguously to a single slink:VkDeviceMemory object 6031 * [[VUID-vkCmdBindDescriptorBuffersEXT-pBindingInfos-08053]] 6032 For any element of pname:pBindingInfos, the buffer from which 6033 pname:address was queried must: have been created with the 6034 ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT bit set if it 6035 contains sampler descriptor data 6036 * [[VUID-vkCmdBindDescriptorBuffersEXT-pBindingInfos-08054]] 6037 For any element of pname:pBindingInfos, the buffer from which 6038 pname:address was queried must: have been created with the 6039 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT bit set if it 6040 contains resource descriptor data 6041 * [[VUID-vkCmdBindDescriptorBuffersEXT-pBindingInfos-08055]] 6042 For any element of pname:pBindingInfos, pname:usage must: match the 6043 buffer from which pname:address was queried 6044**** 6045 6046include::{generated}/validity/protos/vkCmdBindDescriptorBuffersEXT.adoc[] 6047-- 6048 6049[open,refpage='VkDescriptorBufferBindingInfoEXT',desc='Structure specifying descriptor buffer binding information',type='structs'] 6050-- 6051Data describing a descriptor buffer binding is passed in a 6052sname:VkDescriptorBufferBindingInfoEXT structure: 6053 6054include::{generated}/api/structs/VkDescriptorBufferBindingInfoEXT.adoc[] 6055 6056 * pname:sType is a elink:VkStructureType value identifying this structure. 6057 * pname:pNext is `NULL` or a pointer to a structure extending this 6058 structure. 6059 * pname:address is a basetype:VkDeviceAddress specifying the device 6060 address defining the descriptor buffer to be bound. 6061 * pname:usage is a bitmask of elink:VkBufferUsageFlagBits specifying the 6062 slink:VkBufferCreateInfo::pname:usage for the buffer from which 6063 pname:address was queried. 6064 6065ifdef::VK_KHR_maintenance5[] 6066If a slink:VkPipelineCreateFlags2CreateInfoKHR structure is present in the 6067pname:pNext chain, slink:VkPipelineCreateFlags2CreateInfoKHR::pname:flags 6068from that structure is used instead of pname:flags from this structure. 6069endif::VK_KHR_maintenance5[] 6070 6071.Valid Usage 6072**** 6073 * [[VUID-VkDescriptorBufferBindingInfoEXT-bufferlessPushDescriptors-08056]] 6074 If <<limits-bufferlessPushDescriptors, 6075 sname:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferlessPushDescriptors>> 6076 is ename:VK_FALSE, and pname:usage contains 6077 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, then 6078 the pname:pNext chain must: include a 6079 slink:VkDescriptorBufferBindingPushDescriptorBufferHandleEXT structure 6080 * [[VUID-VkDescriptorBufferBindingInfoEXT-address-08057]] 6081 pname:address must: be aligned to 6082 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferOffsetAlignment 6083 * [[VUID-VkDescriptorBufferBindingInfoEXT-usage-08122]] 6084 If pname:usage includes 6085 ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT, pname:address 6086 must: be an address within a valid buffer that was created with 6087 ename:VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT 6088 * [[VUID-VkDescriptorBufferBindingInfoEXT-usage-08123]] 6089 If pname:usage includes 6090 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT, pname:address 6091 must: be an address within a valid buffer that was created with 6092 ename:VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT 6093ifdef::VK_KHR_push_descriptor[] 6094 * [[VUID-VkDescriptorBufferBindingInfoEXT-usage-08124]] 6095 If pname:usage includes 6096 ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT, 6097 pname:address must: be an address within a valid buffer that was created 6098 with ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT 6099endif::VK_KHR_push_descriptor[] 6100**** 6101 6102include::{generated}/validity/structs/VkDescriptorBufferBindingInfoEXT.adoc[] 6103-- 6104 6105[open,refpage='VkDescriptorBufferBindingPushDescriptorBufferHandleEXT',desc='Structure specifying push descriptor buffer binding information',type='structs'] 6106-- 6107When the <<limits-bufferlessPushDescriptors, 6108sname:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferlessPushDescriptors>> 6109property is ename:VK_FALSE, the sname:VkBuffer handle of the buffer for push 6110descriptors is passed in a 6111sname:VkDescriptorBufferBindingPushDescriptorBufferHandleEXT structure: 6112 6113include::{generated}/api/structs/VkDescriptorBufferBindingPushDescriptorBufferHandleEXT.adoc[] 6114 * pname:sType is a elink:VkStructureType value identifying this structure. 6115 * pname:pNext is `NULL` or a pointer to a structure extending this 6116 structure. 6117 * pname:buffer is the sname:VkBuffer handle of the buffer for push 6118 descriptors. 6119 6120.Valid Usage 6121**** 6122 * [[VUID-VkDescriptorBufferBindingPushDescriptorBufferHandleEXT-bufferlessPushDescriptors-08059]] 6123 <<limits-bufferlessPushDescriptors, 6124 sname:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferlessPushDescriptors>> 6125 must: be ename:VK_FALSE 6126**** 6127 6128include::{generated}/validity/structs/VkDescriptorBufferBindingPushDescriptorBufferHandleEXT.adoc[] 6129-- 6130 6131[open,refpage='vkCmdSetDescriptorBufferOffsetsEXT',desc='Setting descriptor buffer offsets in a command buffer',type='protos'] 6132-- 6133To set descriptor buffer offsets in a command buffer, call: 6134 6135include::{generated}/api/protos/vkCmdSetDescriptorBufferOffsetsEXT.adoc[] 6136 6137 * pname:commandBuffer is the command buffer in which the descriptor buffer 6138 offsets will be set. 6139 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 6140 type of the pipeline that will use the descriptors. 6141 * pname:layout is a slink:VkPipelineLayout object used to program the 6142 bindings. 6143 * pname:firstSet is the number of the first set to be bound. 6144 * pname:setCount is the number of elements in the pname:pBufferIndices and 6145 pname:pOffsets arrays. 6146 * pname:pBufferIndices is a pointer to an array of indices into the 6147 descriptor buffer binding points set by 6148 flink:vkCmdBindDescriptorBuffersEXT. 6149 * pname:pOffsets is a pointer to an array of basetype:VkDeviceSize offsets 6150 to apply to the bound descriptor buffers. 6151 6152fname:vkCmdSetDescriptorBufferOffsetsEXT binds pname:setCount pairs of 6153descriptor buffers, specified by indices into the binding points bound using 6154flink:vkCmdBindDescriptorBuffersEXT, and buffer offsets to set numbers 6155[pname:firstSet..pname:firstSet+pname:descriptorSetCount-1] for subsequent 6156<<pipelines-bindpoint-commands, bound pipeline commands>> set by 6157pname:pipelineBindPoint. 6158Set [pname:firstSet + i] is bound to the descriptor buffer at binding 6159pname:pBufferIndices[i] at an offset of pname:pOffsets[i]. 6160Any bindings that were previously applied via these sets, or calls to 6161flink:vkCmdBindDescriptorSets, are no longer valid. 6162Other sets will also be invalidated upon calling this command if 6163pname:layout differs from the pipeline layout used to bind those other sets, 6164as described in <<descriptorsets-compatibility,Pipeline Layout 6165Compatibility>>. 6166 6167After binding descriptors, applications can: modify descriptor memory either 6168by performing writes on the host or with device commands. 6169When descriptor memory is updated with device commands, visibility for the 6170shader stage accessing a descriptor is ensured with the 6171ename:VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT access flag. 6172Implementations must: not access resources referenced by these descriptors 6173unless they are dynamically accessed by shaders. 6174Descriptors bound with this call can: be undefined: if they are not 6175dynamically accessed by shaders. 6176 6177Implementations may: read descriptor data for any statically accessed 6178ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6179descriptor if the pname:binding in pname:layout is not declared with the 6180ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT flag. 6181If the pname:binding in pname:layout is declared with 6182ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT, implementations 6183must: not read descriptor data that is not dynamically accessed. 6184endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6185ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6186descriptor. 6187endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6188 6189Applications must: ensure that any descriptor which the implementation may: 6190read must: be in-bounds of the underlying descriptor buffer binding. 6191 6192ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6193[NOTE] 6194.Note 6195==== 6196Applications can freely decide how large a variable descriptor buffer 6197binding is, so it may not be safe to read such descriptor payloads 6198statically. 6199The intention of these rules is to allow implementations to speculatively 6200prefetch descriptor payloads where feasible. 6201==== 6202endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6203 6204Dynamically accessing a resource through descriptor data from an unbound 6205region of a <<sparsememory-partially-resident-buffers, sparse 6206partially-resident buffer>> will result in invalid descriptor data being 6207read, and therefore undefined: behavior. 6208 6209[NOTE] 6210.Note 6211==== 6212For descriptors written by the host, visibility is implied through the 6213automatic visibility operation on queue submit, and there is no need to 6214consider etext:VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT. 6215Explicit synchronization for descriptors is only required when descriptors 6216are updated on the device. 6217==== 6218 6219ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6220[NOTE] 6221.Note 6222==== 6223The requirements above imply that all descriptor bindings have been defined 6224with the equivalent of ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT, 6225ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT and 6226ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT, but enabling those features 6227is not required to get this behavior. 6228==== 6229endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6230 6231.Valid Usage 6232**** 6233 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-None-08060]] 6234 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 6235 be enabled 6236 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08061]] 6237 The offsets in pname:pOffsets must: be aligned to 6238 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferOffsetAlignment 6239 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08063]] 6240 The offsets in pname:pOffsets must: be small enough such that any 6241 descriptor binding referenced by pname:layout 6242ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6243 without the ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT 6244 flag 6245endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] 6246 computes a valid address inside the underlying slink:VkBuffer 6247 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08126]] 6248 The offsets in pname:pOffsets must: be small enough such that any 6249 location accessed by a shader as a sampler descriptor must: be within 6250 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxSamplerDescriptorBufferRange 6251 of the sampler descriptor buffer binding 6252 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08127]] 6253 The offsets in pname:pOffsets must: be small enough such that any 6254 location accessed by a shader as a resource descriptor must: be within 6255 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxResourceDescriptorBufferRange 6256 of the resource descriptor buffer binding 6257 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pBufferIndices-08064]] 6258 Each element of pname:pBufferIndices must: be less than 6259 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxDescriptorBufferBindings 6260 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pBufferIndices-08065]] 6261 Each element of pname:pBufferIndices must: reference a valid descriptor 6262 buffer binding set by a previous call to 6263 flink:vkCmdBindDescriptorBuffersEXT in pname:commandBuffer 6264 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-firstSet-08066]] 6265 The sum of pname:firstSet and pname:setCount must: be less than or equal 6266 to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 6267 pname:layout was created 6268 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pipelineBindPoint-08067]] 6269 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 6270 parent sname:VkCommandPool's queue family 6271 * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-firstSet-09006]] 6272 The slink:VkDescriptorSetLayout for each set from pname:firstSet to 6273 [eq]#pname:firstSet {plus} pname:setCount# when pname:layout was created 6274 must: have been created with the 6275 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set 6276**** 6277 6278include::{generated}/validity/protos/vkCmdSetDescriptorBufferOffsetsEXT.adoc[] 6279-- 6280 6281[open,refpage='vkCmdBindDescriptorBufferEmbeddedSamplersEXT',desc='Setting embedded immutable samplers offsets in a command buffer',type='protos'] 6282-- 6283To bind an embedded immutable sampler set to a command buffer, call: 6284 6285include::{generated}/api/protos/vkCmdBindDescriptorBufferEmbeddedSamplersEXT.adoc[] 6286 6287 * pname:commandBuffer is the command buffer that the embedded immutable 6288 samplers will be bound to. 6289 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating the 6290 type of the pipeline that will use the embedded immutable samplers. 6291 * pname:layout is a slink:VkPipelineLayout object used to program the 6292 bindings. 6293 * pname:set is the number of the set to be bound. 6294 6295`vkCmdBindDescriptorBufferEmbeddedSamplersEXT` binds the embedded immutable 6296samplers in pname:set of pname:layout to pname:set for the command buffer 6297for subsequent <<pipelines-bindpoint-commands, bound pipeline commands>> set 6298by pname:pipelineBindPoint. 6299Any previous binding to this set by flink:vkCmdSetDescriptorBufferOffsetsEXT 6300or this command is overwritten. 6301Any sets that were last bound by a call to flink:vkCmdBindDescriptorSets are 6302invalidated upon calling this command. 6303Other sets will also be invalidated upon calling this command if 6304pname:layout differs from the pipeline layout used to bind those other sets, 6305as described in <<descriptorsets-compatibility,Pipeline Layout 6306Compatibility>>. 6307 6308.Valid Usage 6309**** 6310 * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-None-08068]] 6311 The <<features-descriptorBuffer, pname:descriptorBuffer>> feature must: 6312 be enabled 6313 * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-pipelineBindPoint-08069]] 6314 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 6315 parent sname:VkCommandPool's queue family 6316 * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-set-08070]] 6317 The slink:VkDescriptorSetLayout at index pname:set when pname:layout was 6318 created must: have been created with the 6319 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT 6320 bit set 6321 * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-set-08071]] 6322 pname:set must: be less than or equal to 6323 slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 6324 pname:layout was created 6325**** 6326 6327include::{generated}/validity/protos/vkCmdBindDescriptorBufferEmbeddedSamplersEXT.adoc[] 6328-- 6329 6330 6331[[descriptorbuffers-updates]] 6332=== Updating Descriptor Buffers 6333 6334Updates to descriptor data in buffers can: be performed by any operation on 6335either the host or device that can: access memory. 6336 6337Descriptor buffer reads can: be synchronized using 6338ename:VK_ACCESS_2_DESCRIPTOR_BUFFER_READ_BIT_EXT in the relevant shader 6339stage. 6340 6341 6342[[descriptorbuffers-push-descriptors]] 6343=== Push Descriptors With Descriptor Buffers 6344 6345If the <<features-descriptorBufferPushDescriptors, 6346pname:descriptorBufferPushDescriptors>> feature is enabled, push descriptors 6347can: be used with descriptor buffers in the same way as with descriptor 6348sets. 6349 6350The <<limits-bufferlessPushDescriptors, 6351sname:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferlessPushDescriptors>> 6352property indicates whether the implementation requires a buffer to back push 6353descriptors. 6354If the property is ename:VK_FALSE then before recording any push descriptors 6355the application must: bind exactly `1` descriptor buffer that was created 6356with the ename:VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT 6357bit set. 6358When this buffer is bound any previously recorded push descriptors that are 6359required for a subsequent command must: be recorded again. 6360 6361 6362[[descriptorbuffers-capturereplay]] 6363=== Capture and Replay 6364 6365In a similar way to <<features-bufferDeviceAddressCaptureReplay, 6366pname:bufferDeviceAddressCaptureReplay>>, the 6367<<features-descriptorBufferCaptureReplay, 6368pname:descriptorBufferCaptureReplay>> feature allows the creation of opaque 6369handles for objects at capture time that can: be passed into object creation 6370calls in a future replay, causing descriptors to be created with the same 6371data. 6372The opaque memory address for any memory used by these resources must: have 6373been captured using flink:vkGetDeviceMemoryOpaqueCaptureAddress and be 6374replayed using slink:VkMemoryOpaqueCaptureAddressAllocateInfo. 6375 6376[open,refpage='vkGetBufferOpaqueCaptureDescriptorDataEXT',desc='Get buffer opaque capture descriptor data',type='protos'] 6377-- 6378To get the opaque descriptor data for a buffer, call: 6379 6380include::{generated}/api/protos/vkGetBufferOpaqueCaptureDescriptorDataEXT.adoc[] 6381 6382 * pname:device is the logical device that gets the data. 6383 * pname:pInfo is a pointer to a slink:VkBufferCaptureDescriptorDataInfoEXT 6384 structure specifying the buffer. 6385 * pname:pData is a pointer to a user-allocated buffer where the data will 6386 be written. 6387 6388.Valid Usage 6389**** 6390 * [[VUID-vkGetBufferOpaqueCaptureDescriptorDataEXT-None-08072]] 6391 The <<features-descriptorBuffer, pname:descriptorBufferCaptureReplay>> 6392 feature must: be enabled 6393 * [[VUID-vkGetBufferOpaqueCaptureDescriptorDataEXT-pData-08073]] 6394 pname:pData must: point to a buffer that is at least 6395 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:bufferCaptureReplayDescriptorDataSize 6396 bytes in size 6397 * [[VUID-vkGetBufferOpaqueCaptureDescriptorDataEXT-device-08074]] 6398 If pname:device was created with multiple physical devices, then the 6399 <<features-bufferDeviceAddressMultiDevice, 6400 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6401**** 6402 6403include::{generated}/validity/protos/vkGetBufferOpaqueCaptureDescriptorDataEXT.adoc[] 6404-- 6405 6406[open,refpage='VkBufferCaptureDescriptorDataInfoEXT',desc='Structure specifying a buffer for descriptor capture',type='structs'] 6407-- 6408Information about the buffer to get descriptor buffer capture data for is 6409passed in a sname:VkBufferCaptureDescriptorDataInfoEXT structure: 6410 6411include::{generated}/api/structs/VkBufferCaptureDescriptorDataInfoEXT.adoc[] 6412 6413 * pname:sType is a elink:VkStructureType value identifying this structure. 6414 * pname:pNext is `NULL` or a pointer to a structure extending this 6415 structure. 6416 * pname:buffer is the sname:VkBuffer handle of the buffer to get opaque 6417 capture data for. 6418 6419.Valid Usage 6420**** 6421 * [[VUID-VkBufferCaptureDescriptorDataInfoEXT-buffer-08075]] 6422 pname:buffer must: have been created with 6423 ename:VK_BUFFER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT set in 6424 slink:VkBufferCreateInfo::pname:flags 6425**** 6426 6427include::{generated}/validity/structs/VkBufferCaptureDescriptorDataInfoEXT.adoc[] 6428-- 6429 6430 6431[open,refpage='vkGetImageOpaqueCaptureDescriptorDataEXT',desc='Get image opaque capture descriptor data',type='protos'] 6432-- 6433To get the opaque capture descriptor data for an image, call: 6434 6435include::{generated}/api/protos/vkGetImageOpaqueCaptureDescriptorDataEXT.adoc[] 6436 6437 * pname:device is the logical device that gets the data. 6438 * pname:pInfo is a pointer to a slink:VkImageCaptureDescriptorDataInfoEXT 6439 structure specifying the image. 6440 * pname:pData is a pointer to a user-allocated buffer where the data will 6441 be written. 6442 6443.Valid Usage 6444**** 6445 * [[VUID-vkGetImageOpaqueCaptureDescriptorDataEXT-None-08076]] 6446 The <<features-descriptorBuffer, pname:descriptorBufferCaptureReplay>> 6447 feature must: be enabled 6448 * [[VUID-vkGetImageOpaqueCaptureDescriptorDataEXT-pData-08077]] 6449 pname:pData must: point to a buffer that is at least 6450 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:imageCaptureReplayDescriptorDataSize 6451 bytes in size 6452 * [[VUID-vkGetImageOpaqueCaptureDescriptorDataEXT-device-08078]] 6453 If pname:device was created with multiple physical devices, then the 6454 <<features-bufferDeviceAddressMultiDevice, 6455 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6456**** 6457 6458include::{generated}/validity/protos/vkGetImageOpaqueCaptureDescriptorDataEXT.adoc[] 6459-- 6460 6461[open,refpage='VkImageCaptureDescriptorDataInfoEXT',desc='Structure specifying an image for descriptor capture',type='structs'] 6462-- 6463Information about the image to get descriptor buffer capture data for is 6464passed in a sname:VkImageCaptureDescriptorDataInfoEXT structure: 6465 6466include::{generated}/api/structs/VkImageCaptureDescriptorDataInfoEXT.adoc[] 6467 6468 * pname:sType is a elink:VkStructureType value identifying this structure. 6469 * pname:pNext is `NULL` or a pointer to a structure extending this 6470 structure. 6471 * pname:image is the sname:VkImage handle of the image to get opaque 6472 capture data for. 6473 6474.Valid Usage 6475**** 6476 * [[VUID-VkImageCaptureDescriptorDataInfoEXT-image-08079]] 6477 pname:image must: have been created with 6478 ename:VK_IMAGE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT set in 6479 slink:VkImageCreateInfo::pname:flags 6480**** 6481 6482include::{generated}/validity/structs/VkImageCaptureDescriptorDataInfoEXT.adoc[] 6483-- 6484 6485[open,refpage='vkGetImageViewOpaqueCaptureDescriptorDataEXT',desc='Get image view opaque capture descriptor data',type='protos'] 6486-- 6487To get the opaque capture descriptor data for an image view, call: 6488 6489include::{generated}/api/protos/vkGetImageViewOpaqueCaptureDescriptorDataEXT.adoc[] 6490 6491 * pname:device is the logical device that gets the data. 6492 * pname:pInfo is a pointer to a 6493 slink:VkImageViewCaptureDescriptorDataInfoEXT structure specifying the 6494 image view. 6495 * pname:pData is a pointer to a user-allocated buffer where the data will 6496 be written. 6497 6498.Valid Usage 6499**** 6500 * [[VUID-vkGetImageViewOpaqueCaptureDescriptorDataEXT-None-08080]] 6501 The <<features-descriptorBuffer, pname:descriptorBufferCaptureReplay>> 6502 feature must: be enabled 6503 * [[VUID-vkGetImageViewOpaqueCaptureDescriptorDataEXT-pData-08081]] 6504 pname:pData must: point to a buffer that is at least 6505 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:imageViewCaptureReplayDescriptorDataSize 6506 bytes in size 6507 * [[VUID-vkGetImageViewOpaqueCaptureDescriptorDataEXT-device-08082]] 6508 If pname:device was created with multiple physical devices, then the 6509 <<features-bufferDeviceAddressMultiDevice, 6510 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6511**** 6512 6513include::{generated}/validity/protos/vkGetImageViewOpaqueCaptureDescriptorDataEXT.adoc[] 6514-- 6515 6516[open,refpage='VkImageViewCaptureDescriptorDataInfoEXT',desc='Structure specifying an image view for descriptor capture',type='structs'] 6517-- 6518Information about the image view to get descriptor buffer capture data for 6519is passed in a sname:VkImageViewCaptureDescriptorDataInfoEXT structure: 6520 6521include::{generated}/api/structs/VkImageViewCaptureDescriptorDataInfoEXT.adoc[] 6522 6523 * pname:sType is a elink:VkStructureType value identifying this structure. 6524 * pname:pNext is `NULL` or a pointer to a structure extending this 6525 structure. 6526 * pname:imageView is the sname:VkImageView handle of the image view to get 6527 opaque capture data for. 6528 6529.Valid Usage 6530**** 6531 * [[VUID-VkImageViewCaptureDescriptorDataInfoEXT-imageView-08083]] 6532 pname:imageView must: have been created with 6533 ename:VK_IMAGE_VIEW_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT set 6534 in slink:VkImageViewCreateInfo::pname:flags 6535**** 6536 6537include::{generated}/validity/structs/VkImageViewCaptureDescriptorDataInfoEXT.adoc[] 6538-- 6539 6540[open,refpage='vkGetSamplerOpaqueCaptureDescriptorDataEXT',desc='Get sampler opaque capture descriptor data',type='protos'] 6541-- 6542To get the opaque capture descriptor data for a sampler, call: 6543 6544include::{generated}/api/protos/vkGetSamplerOpaqueCaptureDescriptorDataEXT.adoc[] 6545 6546 * pname:device is the logical device that gets the data. 6547 * pname:pInfo is a pointer to a 6548 slink:VkSamplerCaptureDescriptorDataInfoEXT structure specifying the 6549 sampler. 6550 * pname:pData is a pointer to a user-allocated buffer where the data will 6551 be written. 6552 6553.Valid Usage 6554**** 6555 * [[VUID-vkGetSamplerOpaqueCaptureDescriptorDataEXT-None-08084]] 6556 The <<features-descriptorBuffer, pname:descriptorBufferCaptureReplay>> 6557 feature must: be enabled 6558 * [[VUID-vkGetSamplerOpaqueCaptureDescriptorDataEXT-pData-08085]] 6559 pname:pData must: point to a buffer that is at least 6560 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:samplerCaptureReplayDescriptorDataSize 6561 bytes in size 6562 * [[VUID-vkGetSamplerOpaqueCaptureDescriptorDataEXT-device-08086]] 6563 If pname:device was created with multiple physical devices, then the 6564 <<features-bufferDeviceAddressMultiDevice, 6565 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6566**** 6567 6568include::{generated}/validity/protos/vkGetSamplerOpaqueCaptureDescriptorDataEXT.adoc[] 6569-- 6570 6571[open,refpage='VkSamplerCaptureDescriptorDataInfoEXT',desc='Structure specifying a sampler for descriptor capture',type='structs'] 6572-- 6573Information about the sampler to get descriptor buffer capture data for is 6574passed in a sname:VkSamplerCaptureDescriptorDataInfoEXT structure: 6575 6576include::{generated}/api/structs/VkSamplerCaptureDescriptorDataInfoEXT.adoc[] 6577 6578 * pname:sType is a elink:VkStructureType value identifying this structure. 6579 * pname:pNext is `NULL` or a pointer to a structure extending this 6580 structure. 6581 * pname:sampler is the sname:VkSampler handle of the sampler to get opaque 6582 capture data for. 6583 6584.Valid Usage 6585**** 6586 * [[VUID-VkSamplerCaptureDescriptorDataInfoEXT-sampler-08087]] 6587 pname:sampler must: have been created with 6588 ename:VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT set in 6589 slink:VkSamplerCreateInfo::pname:flags 6590**** 6591 6592include::{generated}/validity/structs/VkSamplerCaptureDescriptorDataInfoEXT.adoc[] 6593-- 6594 6595ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 6596[open,refpage='vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT',desc='Get acceleration structure opaque capture descriptor data',type='protos'] 6597-- 6598To get the opaque capture descriptor data for an acceleration structure, 6599call: 6600 6601include::{generated}/api/protos/vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT.adoc[] 6602 6603 * pname:device is the logical device that gets the data. 6604 * pname:pInfo is a pointer to a 6605 slink:VkAccelerationStructureCaptureDescriptorDataInfoEXT structure 6606 specifying the acceleration structure. 6607 * pname:pData is a pointer to a user-allocated buffer where the data will 6608 be written. 6609 6610.Valid Usage 6611**** 6612 * [[VUID-vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT-None-08088]] 6613 The <<features-descriptorBuffer, pname:descriptorBufferCaptureReplay>> 6614 feature must: be enabled 6615 * [[VUID-vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT-pData-08089]] 6616 pname:pData must: point to a buffer that is at least 6617 slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:accelerationStructureCaptureReplayDescriptorDataSize 6618 bytes in size 6619 * [[VUID-vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT-device-08090]] 6620 If pname:device was created with multiple physical devices, then the 6621 <<features-bufferDeviceAddressMultiDevice, 6622 pname:bufferDeviceAddressMultiDevice>> feature must: be enabled 6623**** 6624 6625include::{generated}/validity/protos/vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT.adoc[] 6626-- 6627 6628[open,refpage='VkAccelerationStructureCaptureDescriptorDataInfoEXT',desc='Structure specifying an acceleration structure for descriptor capture',type='structs'] 6629-- 6630Information about the acceleration structure to get descriptor buffer 6631capture data for is passed in a 6632sname:VkAccelerationStructureCaptureDescriptorDataInfoEXT structure: 6633 6634include::{generated}/api/structs/VkAccelerationStructureCaptureDescriptorDataInfoEXT.adoc[] 6635 6636 * pname:sType is a elink:VkStructureType value identifying this structure. 6637 * pname:pNext is `NULL` or a pointer to a structure extending this 6638 structure. 6639 * pname:accelerationStructure is the sname:VkAccelerationStructureKHR 6640 handle of the acceleration structure to get opaque capture data for. 6641 * pname:accelerationStructureNV is the sname:VkAccelerationStructureNV 6642 handle of the acceleration structure to get opaque capture data for. 6643 6644.Valid Usage 6645**** 6646 * [[VUID-VkAccelerationStructureCaptureDescriptorDataInfoEXT-accelerationStructure-08091]] 6647 If pname:accelerationStructure is not dlink:VK_NULL_HANDLE then 6648 pname:accelerationStructure must: have been created with 6649 ename:VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 6650 set in slink:VkAccelerationStructureCreateInfoKHR::pname:createFlags 6651 * [[VUID-VkAccelerationStructureCaptureDescriptorDataInfoEXT-accelerationStructureNV-08092]] 6652 If pname:accelerationStructureNV is not dlink:VK_NULL_HANDLE then 6653 pname:accelerationStructureNV must: have been created with 6654 ename:VK_ACCELERATION_STRUCTURE_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT 6655 set in slink:VkAccelerationStructureCreateInfoNV::pname:info.flags 6656 * [[VUID-VkAccelerationStructureCaptureDescriptorDataInfoEXT-accelerationStructure-08093]] 6657 If pname:accelerationStructure is not dlink:VK_NULL_HANDLE then 6658 pname:accelerationStructureNV must: be dlink:VK_NULL_HANDLE 6659 * [[VUID-VkAccelerationStructureCaptureDescriptorDataInfoEXT-accelerationStructureNV-08094]] 6660 If pname:accelerationStructureNV is not dlink:VK_NULL_HANDLE then 6661 pname:accelerationStructure must: be dlink:VK_NULL_HANDLE 6662**** 6663 6664include::{generated}/validity/structs/VkAccelerationStructureCaptureDescriptorDataInfoEXT.adoc[] 6665-- 6666endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] 6667 6668[open,refpage='VkOpaqueCaptureDescriptorDataCreateInfoEXT',desc='Structure specifying opaque capture descriptor data',type='structs'] 6669-- 6670The sname:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure is defined 6671as: 6672 6673include::{generated}/api/structs/VkOpaqueCaptureDescriptorDataCreateInfoEXT.adoc[] 6674 6675 * pname:sType is a elink:VkStructureType value identifying this structure. 6676 * pname:pNext is `NULL` or a pointer to a structure extending this 6677 structure. 6678 * pname:opaqueCaptureDescriptorData is a pointer to a user-allocated 6679 buffer containing opaque capture data retrieved using 6680 flink:vkGetBufferOpaqueCaptureDescriptorDataEXT, 6681 flink:vkGetImageOpaqueCaptureDescriptorDataEXT, 6682 flink:vkGetImageViewOpaqueCaptureDescriptorDataEXT, 6683 flink:vkGetSamplerOpaqueCaptureDescriptorDataEXT, or 6684 flink:vkGetAccelerationStructureOpaqueCaptureDescriptorDataEXT. 6685 6686During replay, opaque descriptor capture data can: be specified by adding a 6687sname:VkOpaqueCaptureDescriptorDataCreateInfoEXT structure to the relevant 6688pname:pNext chain of a slink:VkBufferCreateInfo, slink:VkImageCreateInfo, 6689slink:VkImageViewCreateInfo, slink:VkSamplerCreateInfo, 6690slink:VkAccelerationStructureCreateInfoNV or 6691slink:VkAccelerationStructureCreateInfoKHR structure. 6692 6693 6694include::{generated}/validity/structs/VkOpaqueCaptureDescriptorDataCreateInfoEXT.adoc[] 6695-- 6696 6697endif::VK_EXT_descriptor_buffer[] 6698