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