1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[[descriptorsets]] 6= Resource Descriptors 7 8A _descriptor_ is an opaque data structure representing a shader resource 9such as a buffer, buffer view, image view, sampler, or combined image 10sampler. 11Descriptors are organised into _descriptor sets_, which are bound during 12command recording for use in subsequent draw 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<<features-limits, Limits>>) descriptor sets. 20 21Shaders access resources via variables decorated with a descriptor set and 22binding number that link them to a descriptor in a descriptor set. 23The shader interface mapping to bound descriptor sets is described in the 24<<interfaces-resources, Shader Resource Interface>> section. 25 26 27[[descriptorsets-types]] 28== Descriptor Types 29 30There are a number of different types of descriptor supported by Vulkan, 31corresponding to different resources or usage. 32The following sections describe the API definitions of each descriptor type. 33The mapping of each type to SPIR-V is listed in the 34<<interfaces-resources-correspondence, Shader Resource and Descriptor Type 35Correspondence>> and <<interfaces-resources-storage-class-correspondence, 36Shader Resource and Storage Class Correspondence>> tables in the 37<<interfaces, Shader Interfaces>> chapter. 38 39 40[[descriptorsets-storageimage]] 41=== Storage Image 42 43A _storage image_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE) is a descriptor 44type associated with an <<resources-images, image resource>> via an 45<<resources-image-views, image view>> that load, store, and atomic 46operations can: be performed on. 47 48Storage image loads are supported in all shader stages for image views whose 49<<resources-image-view-format-features,format features>> contain 50<<features-formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 51 52Stores to storage images are supported in compute shaders for image views 53whose <<resources-image-view-format-features,format features>> contain 54<<features-formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT>>. 55 56Atomic operations on storage images are supported in compute shaders for 57image views whose <<resources-image-view-format-features,format features>> 58contain 59<<features-formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT>>. 60 61When the <<features-features-fragmentStoresAndAtomics, 62pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 63operations are also supported for storage images in fragment shaders with 64the same set of image formats as supported in compute shaders. 65When the <<features-features-vertexPipelineStoresAndAtomics, 66pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 67operations are also supported in vertex, tessellation, and geometry shaders 68with the same set of image formats as supported in compute shaders. 69 70The image subresources for a storage image must: be in the 71ifdef::VK_KHR_shared_presentable_image[] 72ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 73endif::VK_KHR_shared_presentable_image[] 74ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 75shader. 76 77 78[[descriptorsets-sampler]] 79=== Sampler 80 81A _sampler descriptor_ (ename:VK_DESCRIPTOR_TYPE_SAMPLER) is a descriptor 82type associated with a <<samplers,sampler>> object, used to control the 83behaviour of <<textures,sampling operations>> performed on a 84<<descriptorsets-sampledimage, sampled image>>. 85 86 87[[descriptorsets-sampledimage]] 88=== Sampled Image 89 90A _sampled image_ (ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE) is a descriptor 91type associated with an <<resources-images, image resource>> via an 92<<resources-image-views, image view>> that <<textures,sampling operations>> 93can: be performed on. 94 95Shaders combine a sampled image variable and a sampler variable to perform 96sampling operations. 97 98Sampled images are supported in all shader stages for image views whose 99<<resources-image-view-format-features,format features>> contain 100<<features-formats-properties,ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT>>. 101 102The image subresources for a sampled image must: be in the 103ifdef::VK_KHR_shared_presentable_image[] 104ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 105endif::VK_KHR_shared_presentable_image[] 106ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 107ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 108ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 109endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 110ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 111ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 112ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 113shader. 114 115 116[[descriptorsets-combinedimagesampler]] 117=== Combined Image Sampler 118 119A _combined image sampler_ (ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER) 120is a single descriptor type associated with both a <<samplers,sampler>> and 121an <<resources-images,image resource>>, combining both a 122<<descriptorsets-sampler,sampler>> and <<descriptorsets-sampledimage, 123sampled image>> descriptor into a single descriptor. 124 125ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 126If the descriptor refers to a sampler that performs 127<<samplers-YCbCr-conversion,Y'C~B~C~R~ conversion>>, the sampler must: only 128be used to sample the image in the same descriptor. 129Otherwise, the 130endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 131ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 132The 133endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 134sampler and image in this type of descriptor can: be used freely with any 135other samplers and images. 136 137The image subresources for a combined image sampler must: be in the 138ifdef::VK_KHR_shared_presentable_image[] 139ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 140endif::VK_KHR_shared_presentable_image[] 141ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 142ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 143ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 144endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 145ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 146ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 147ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 148shader. 149 150[NOTE] 151.Note 152==== 153On some implementations, it may: be more efficient to sample from an image 154using a combination of sampler and sampled image that are stored together in 155the descriptor set in a combined descriptor. 156==== 157 158 159[[descriptorsets-uniformtexelbuffer]] 160=== Uniform Texel Buffer 161 162A _uniform texel buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER) is 163a descriptor type associated with a <<resources-buffers,buffer resource>> 164via a <<resources-buffer-views, buffer view>> that <<textures,formatted load 165operations>> can: be performed on. 166 167Uniform texel buffers define a tightly-packed 1-dimensional linear array of 168texels, with texels going through format conversion when read in a shader in 169the same way as they are for an image. 170 171Load operations from uniform texel buffers are supported in all shader 172stages for image formats which report support for the 173<<features-formats-properties,ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT>> 174feature bit via flink:vkGetPhysicalDeviceFormatProperties in 175slink:VkFormatProperties::pname:bufferFeatures. 176 177 178[[descriptorsets-storagetexelbuffer]] 179=== Storage Texel Buffer 180 181A _storage texel buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER) is 182a descriptor type associated with a <<resources-buffers,buffer resource>> 183via a <<resources-buffer-views, buffer view>> that <<textures,formatted 184load, store, and atomic operations>> can: be performed on. 185 186Storage texel buffers define a tightly-packed 1-dimensional linear array of 187texels, with texels going through format conversion when read in a shader in 188the same way as they are for an image. 189Unlike <<descriptorsets-uniformtexelbuffer,uniform texel buffers>>, these 190buffers can also be written to in the same way as for 191<<descriptorsets-storageimage, storage images>>. 192 193Storage texel buffer loads are supported in all shader stages for texel 194buffer formats which report support for the 195<<features-formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT>> 196feature bit via flink:vkGetPhysicalDeviceFormatProperties in 197slink:VkFormatProperties::pname:bufferFeatures. 198 199Stores to storage texel buffers are supported in compute shaders for texel 200buffer formats which report support for the 201ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT feature via 202flink:vkGetPhysicalDeviceFormatProperties in 203slink:VkFormatProperties::pname:bufferFeatures. 204 205Atomic operations on storage texel buffers are supported in compute shaders 206for texel buffer formats which report support for the 207<<features-formats-properties,ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_ATOMIC_BIT>> 208feature via flink:vkGetPhysicalDeviceFormatProperties in 209slink:VkFormatProperties::pname:bufferFeatures. 210 211When the <<features-features-fragmentStoresAndAtomics, 212pname:fragmentStoresAndAtomics>> feature is enabled, stores and atomic 213operations are also supported for storage texel buffers in fragment shaders 214with the same set of texel buffer formats as supported in compute shaders. 215When the <<features-features-vertexPipelineStoresAndAtomics, 216pname:vertexPipelineStoresAndAtomics>> feature is enabled, stores and atomic 217operations are also supported in vertex, tessellation, and geometry shaders 218with the same set of texel buffer formats as supported in compute shaders. 219 220 221[[descriptorsets-storagebuffer]] 222=== Storage Buffer 223 224A _storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER) is a descriptor 225type associated with a <<resources-buffers,buffer resource>> directly, 226described in a shader as a structure with various members that load, store, 227and atomic operations can: be performed on. 228 229[NOTE] 230.Note 231==== 232Atomic operations can: only be performed on members of certain types as 233defined in the <<spirvenv, SPIR-V environment appendix>>. 234==== 235 236 237[[descriptorsets-uniformbuffer]] 238=== Uniform Buffer 239 240A _uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER) is a descriptor 241type associated with a <<resources-buffers,buffer resource>> directly, 242described in a shader as a structure with various members that load 243operations can: be performed on. 244 245 246[[descriptorsets-uniformbufferdynamic]] 247=== Dynamic Uniform Buffer 248 249A _dynamic uniform buffer_ (ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC) 250is almost identical to a <<descriptorsets-uniformbuffer, uniform buffer>>, 251and differs only in how the offset into the buffer is specified. 252The base offset calculated by the slink:VkDescriptorBufferInfo when 253initially <<descriptorsets-updates, updating the descriptor set>> is added 254to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 255the descriptor set. 256 257 258[[descriptorsets-storagebufferdynamic]] 259=== Dynamic Storage Buffer 260 261A _dynamic storage buffer_ (ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC) 262is almost identical to a <<descriptorsets-storagebuffer, storage buffer>>, 263and differs only in how the offset into the buffer is specified. 264The base offset calculated by the slink:VkDescriptorBufferInfo when 265initially <<descriptorsets-updates, updating the descriptor set>> is added 266to a <<descriptorsets-binding-dynamicoffsets, dynamic offset>> when binding 267the descriptor set. 268 269 270[[descriptorsets-inputattachment]] 271=== Input Attachment 272 273An _input attachment_ (ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT) is a 274descriptor type associated with an <<resources-images, image resource>> via 275an <<resources-image-views, image view>> that can: be used for 276<<synchronization-framebuffer-regions,framebuffer local>> load operations in 277fragment shaders. 278 279All image formats that are supported for color attachments 280(ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT) or depth/stencil attachments 281(ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT) for a given image 282tiling mode are also supported for input attachments. 283 284The image subresources for an input attachment must: be in the 285ifdef::VK_KHR_shared_presentable_image[] 286ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR, 287endif::VK_KHR_shared_presentable_image[] 288ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] 289ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL, 290ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL, 291endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 292ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL, 293ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, or 294ename:VK_IMAGE_LAYOUT_GENERAL layout in order to access its data in a 295shader. 296 297 298[[descriptorsets-sets]] 299== Descriptor Sets 300 301Descriptors are grouped together into descriptor set objects. 302A descriptor set object is an opaque object that contains storage for a set 303of descriptors, where the types and number of descriptors is defined by a 304descriptor set layout. 305The layout object may: be used to define the association of each descriptor 306binding with memory or other implementation resources. 307The layout is used both for determining the resources that need to be 308associated with the descriptor set, and determining the interface between 309shader stages and shader resources. 310 311 312[[descriptorsets-setlayout]] 313=== Descriptor Set Layout 314 315[open,refpage='VkDescriptorSetLayout',desc='Opaque handle to a descriptor set layout object',type='handles'] 316-- 317 318A descriptor set layout object is defined by an array of zero or more 319descriptor bindings. 320Each individual descriptor binding is specified by a descriptor type, a 321count (array size) of the number of descriptors in the binding, a set of 322shader stages that can: access the binding, and (if using immutable 323samplers) an array of sampler descriptors. 324 325Descriptor set layout objects are represented by sname:VkDescriptorSetLayout 326handles: 327 328include::../api/handles/VkDescriptorSetLayout.txt[] 329 330-- 331 332[open,refpage='vkCreateDescriptorSetLayout',desc='Create a new descriptor set layout',type='protos'] 333-- 334 335To create descriptor set layout objects, call: 336 337include::../api/protos/vkCreateDescriptorSetLayout.txt[] 338 339 * pname:device is the logical device that creates the descriptor set 340 layout. 341 * pname:pCreateInfo is a pointer to an instance of the 342 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 343 the descriptor set layout object. 344 * pname:pAllocator controls host memory allocation as described in the 345 <<memory-allocation, Memory Allocation>> chapter. 346 * pname:pSetLayout points to a slink:VkDescriptorSetLayout handle in which 347 the resulting descriptor set layout object is returned. 348 349include::../validity/protos/vkCreateDescriptorSetLayout.txt[] 350-- 351 352[open,refpage='VkDescriptorSetLayoutCreateInfo',desc='Structure specifying parameters of a newly created descriptor set layout',type='structs'] 353-- 354 355Information about the descriptor set layout is passed in an instance of the 356sname:VkDescriptorSetLayoutCreateInfo structure: 357 358include::../api/structs/VkDescriptorSetLayoutCreateInfo.txt[] 359 360 * pname:sType is the type of this structure. 361 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 362 * pname:flags is a bitmask 363ifdef::VK_KHR_push_descriptor[] 364 of elink:VkDescriptorSetLayoutCreateFlagBits 365endif::VK_KHR_push_descriptor[] 366 specifying options for descriptor set layout creation. 367 * pname:bindingCount is the number of elements in pname:pBindings. 368 * pname:pBindings is a pointer to an array of 369 slink:VkDescriptorSetLayoutBinding structures. 370 371.Valid Usage 372**** 373 * [[VUID-VkDescriptorSetLayoutCreateInfo-binding-00279]] 374 The slink:VkDescriptorSetLayoutBinding::pname:binding members of the 375 elements of the pname:pBindings array must: each have different values. 376ifdef::VK_KHR_push_descriptor[] 377 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00280]] 378 If pname:flags contains 379 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 380 elements of pname:pBindings must: not have a pname:descriptorType of 381 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 382 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 383 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00281]] 384 If pname:flags contains 385 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then the 386 total number of elements of all bindings must: be less than or equal to 387 slink:VkPhysicalDevicePushDescriptorPropertiesKHR::pname:maxPushDescriptors 388endif::VK_KHR_push_descriptor[] 389ifdef::VK_EXT_descriptor_indexing[] 390 * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-03000]] 391 If any binding has the 392 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set, 393 pname:flags must: include 394 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 395 * [[VUID-VkDescriptorSetLayoutCreateInfo-descriptorType-03001]] 396 If any binding has the 397 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set, then all 398 bindings must: not have pname:descriptorType of 399 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 400 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 401endif::VK_EXT_descriptor_indexing[] 402**** 403 404include::../validity/structs/VkDescriptorSetLayoutCreateInfo.txt[] 405-- 406 407[open,refpage='VkDescriptorSetLayoutCreateFlagBits',desc='Bitmask specifying descriptor set layout properties',type='enums'] 408-- 409 410Bits which can: be set in slink:VkDescriptorSetLayoutCreateInfo::pname:flags 411to specify options for descriptor set layout are: 412 413include::../api/enums/VkDescriptorSetLayoutCreateFlagBits.txt[] 414 415ifdef::VK_KHR_push_descriptor[] 416 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies 417 that descriptor sets must: not be allocated using this layout, and 418 descriptors are instead pushed by flink:vkCmdPushDescriptorSetKHR. 419endif::VK_KHR_push_descriptor[] 420ifdef::VK_EXT_descriptor_indexing[] 421 * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 422 specifies that descriptor sets using this layout must: be allocated from 423 a descriptor pool created with the 424 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT bit set. 425 Descriptor set layouts created with this bit set have alternate limits 426 for the maximum number of descriptors per-stage and per-pipeline layout. 427 The non-UpdateAfterBind limits only count descriptors in sets created 428 without this flag. 429 The UpdateAfterBind limits count all descriptors, but the limits may: be 430 higher than the non-UpdateAfterBind limits. 431endif::VK_EXT_descriptor_indexing[] 432 433ifndef::VK_KHR_push_descriptor[] 434[NOTE] 435.Note 436==== 437All bits for this type are defined by extensions, and none of those 438extensions are enabled in this build of the specification. 439==== 440endif::VK_KHR_push_descriptor[] 441-- 442 443[open,refpage='VkDescriptorSetLayoutCreateFlags',desc='Bitmask of VkDescriptorSetLayoutCreateFlagBits',type='enums'] 444-- 445include::../api/flags/VkDescriptorSetLayoutCreateFlags.txt[] 446 447sname:VkDescriptorSetLayoutCreateFlags is a bitmask type for setting a mask 448of zero or more slink:VkDescriptorSetLayoutCreateFlagBits. 449-- 450 451[open,refpage='VkDescriptorSetLayoutBinding',desc='Structure specifying a descriptor set layout binding',type='structs'] 452-- 453 454The sname:VkDescriptorSetLayoutBinding structure is defined as: 455 456include::../api/structs/VkDescriptorSetLayoutBinding.txt[] 457 458 * pname:binding is the binding number of this entry and corresponds to a 459 resource of the same binding number in the shader stages. 460 * pname:descriptorType is a elink:VkDescriptorType specifying which type 461 of resource descriptors are used for this binding. 462 * pname:descriptorCount is the number of descriptors contained in the 463 binding, accessed in a shader as an array. 464 If pname:descriptorCount is zero this binding entry is reserved and the 465 resource must: not be accessed from any stage via this binding within 466 any pipeline using the set layout. 467 * pname:stageFlags member is a bitmask of elink:VkShaderStageFlagBits 468 specifying which pipeline shader stages can: access a resource for this 469 binding. 470 ename:VK_SHADER_STAGE_ALL is a shorthand specifying that all defined 471 shader stages, including any additional stages defined by extensions, 472 can: access the resource. 473+ 474If a shader stage is not included in pname:stageFlags, then a resource must: 475not be accessed from that stage via this binding within any pipeline using 476the set layout. 477Other than input attachments which are limited to the fragment shader, there 478are no limitations on what combinations of stages can: use a descriptor 479binding, and in particular a binding can: be used by both graphics stages 480and the compute stage. 481 482 * pname:pImmutableSamplers affects initialization of samplers. 483 If pname:descriptorType specifies a ename:VK_DESCRIPTOR_TYPE_SAMPLER or 484 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then 485 pname:pImmutableSamplers can: be used to initialize a set of _immutable 486 samplers_. 487 Immutable samplers are permanently bound into the set layout; later 488 binding a sampler into an immutable sampler slot in a descriptor set is 489 not allowed. 490 If pname:pImmutableSamplers is not `NULL`, then it is considered to be a 491 pointer to an array of sampler handles that will be consumed by the set 492 layout and used for the corresponding binding. 493 If pname:pImmutableSamplers is `NULL`, then the sampler slots are 494 dynamic and sampler handles must: be bound into descriptor sets using 495 this layout. 496 If pname:descriptorType is not one of these descriptor types, then 497 pname:pImmutableSamplers is ignored. 498 499The above layout definition allows the descriptor bindings to be specified 500sparsely such that not all binding numbers between 0 and the maximum binding 501number need to be specified in the pname:pBindings array. 502Bindings that are not specified have a pname:descriptorCount and 503pname:stageFlags of zero, and the pname:descriptorType is treated as 504undefined. 505However, all binding numbers between 0 and the maximum binding number in the 506slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings array may: consume 507memory in the descriptor set layout even if not all descriptor bindings are 508used, though it should: not consume additional memory from the descriptor 509pool. 510 511[NOTE] 512.Note 513==== 514The maximum binding number specified should: be as compact as possible to 515avoid wasted memory. 516==== 517 518.Valid Usage 519**** 520 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-00282]] 521 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 522 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 523 pname:descriptorCount is not `0` and pname:pImmutableSamplers is not 524 `NULL`, pname:pImmutableSamplers must: be a valid pointer to an array of 525 pname:descriptorCount valid sname:VkSampler handles 526 * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-00283]] 527 If pname:descriptorCount is not `0`, pname:stageFlags must: be a valid 528 combination of elink:VkShaderStageFlagBits values 529 * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-01510]] 530 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and 531 pname:descriptorCount is not `0`, then pname:stageFlags must: be `0` or 532 ename:VK_SHADER_STAGE_FRAGMENT_BIT 533**** 534 535include::../validity/structs/VkDescriptorSetLayoutBinding.txt[] 536-- 537 538ifdef::VK_EXT_descriptor_indexing[] 539[open,refpage='VkDescriptorSetLayoutBindingFlagsCreateInfoEXT',desc='Structure specifying creation flags for descriptor set layout bindings',type='structs'] 540-- 541 542If the pname:pNext chain of a slink:VkDescriptorSetLayoutCreateInfo 543structure includes a sname:VkDescriptorSetLayoutBindingFlagsCreateInfoEXT 544structure, then that structure includes an array of flags, one for each 545descriptor set layout binding. 546 547The slink:VkDescriptorSetLayoutBindingFlagsCreateInfoEXT structure is 548defined as: 549 550include::../api/structs/VkDescriptorSetLayoutBindingFlagsCreateInfoEXT.txt[] 551 552 * pname:sType is the type of this structure. 553 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 554 * pname:bindingCount is zero or the number of elements in 555 pname:pBindingFlags. 556 * pname:pBindingFlags is a pointer to an array of 557 elink:VkDescriptorBindingFlagsEXT bitfields, one for each descriptor set 558 layout binding. 559 560If pname:bindingCount is zero or if this structure is not in the pname:pNext 561chain, the elink:VkDescriptorBindingFlagsEXT for each descriptor set layout 562binding is considered to be zero. 563Otherwise, the descriptor set layout binding at 564slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings[i] uses the flags in 565pname:pBindingFlags[i]. 566 567.Valid Usage 568**** 569 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-bindingCount-03002]] 570 If pname:bindingCount is not zero, pname:bindingCount must: equal 571 slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount 572ifdef::VK_KHR_push_descriptor[] 573 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-flags-03003]] 574 If slink:VkDescriptorSetLayoutCreateInfo::pname:flags includes 575 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all 576 elements of pname:pBindingFlags must: not include 577 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT, 578 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT, or 579 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT 580endif::VK_KHR_push_descriptor[] 581 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-pBindingFlags-03004]] 582 If an element of pname:pBindingFlags includes 583 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT, then all 584 other elements of slink:VkDescriptorSetLayoutCreateInfo::pname:pBindings 585 must: have a smaller value of pname:binding 586 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingUniformBufferUpdateAfterBind-03005]] 587 If 588 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingUniformBufferUpdateAfterBind 589 is not enabled, all bindings with descriptor type 590 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER must: not use 591 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 592 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingSampledImageUpdateAfterBind-03006]] 593 If 594 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingSampledImageUpdateAfterBind 595 is not enabled, all bindings with descriptor type 596 ename:VK_DESCRIPTOR_TYPE_SAMPLER, 597 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, or 598 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE must: not use 599 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 600 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingStorageImageUpdateAfterBind-03007]] 601 If 602 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingStorageImageUpdateAfterBind 603 is not enabled, all bindings with descriptor type 604 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE must: not use 605 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 606 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingStorageBufferUpdateAfterBind-03008]] 607 If 608 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingStorageBufferUpdateAfterBind 609 is not enabled, all bindings with descriptor type 610 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER must: not use 611 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 612 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingUniformTexelBufferUpdateAfterBind-03009]] 613 If 614 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingUniformTexelBufferUpdateAfterBind 615 is not enabled, all bindings with descriptor type 616 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER must: not use 617 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 618 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingStorageTexelBufferUpdateAfterBind-03010]] 619 If 620 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingStorageTexelBufferUpdateAfterBind 621 is not enabled, all bindings with descriptor type 622 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER must: not use 623 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 624 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-None-03011]] 625 All bindings with descriptor type 626 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 627 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 628 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: not use 629 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT 630 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingUpdateUnusedWhilePending-03012]] 631 If 632 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingUpdateUnusedWhilePending 633 is not enabled, all elements of pname:pBindingFlags must: not include 634 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT 635 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingPartiallyBound-03013]] 636 If 637 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingPartiallyBound 638 is not enabled, all elements of pname:pBindingFlags must: not include 639 ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT 640 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-descriptorBindingVariableDescriptorCount-03014]] 641 If 642 slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingVariableDescriptorCount 643 is not enabled, all elements of pname:pBindingFlags must: not include 644 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT 645 * [[VUID-VkDescriptorSetLayoutBindingFlagsCreateInfoEXT-pBindingFlags-03015]] 646 If an element of pname:pBindingFlags includes 647 ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT, that 648 element's pname:descriptorType must: not be 649 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or 650 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC 651**** 652 653include::../validity/structs/VkDescriptorSetLayoutBindingFlagsCreateInfoEXT.txt[] 654-- 655 656[open,refpage='VkDescriptorBindingFlagBitsEXT',desc='Bitmask specifying descriptor set layout binding properties',type='enums'] 657-- 658 659Bits which can: be set in each element of 660slink:VkDescriptorSetLayoutBindingFlagsCreateInfoEXT::pname:pBindingFlags to 661specify options for the corresponding descriptor set layout binding are: 662 663include::../api/enums/VkDescriptorBindingFlagBitsEXT.txt[] 664 665 * ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT indicates that if 666 descriptors in this binding are updated between when the descriptor set 667 is bound in a command buffer and when that command buffer is submitted 668 to a queue, then the submission will use the most recently set 669 descriptors for this binding and the updates do not invalidate the 670 command buffer. 671 Descriptor bindings created with this flag are also partially exempt 672 from the external synchronization requirement in 673ifdef::VK_KHR_descriptor_update_template[] 674 flink:vkUpdateDescriptorSetWithTemplateKHR and 675endif::VK_KHR_descriptor_update_template[] 676 flink:vkUpdateDescriptorSets. 677 They can: be updated concurrently with the set being bound to a command 678 buffer in another thread, but not concurrently with the set being reset 679 or freed. 680 * ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT indicates that 681 descriptors in this binding that are not _dynamically used_ need not 682 contain valid descriptors at the time the descriptors are consumed. 683 A descriptor is dynamically used if any shader invocation executes an 684 instruction that performs any memory access using the descriptor. 685 * ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT 686 indicates that descriptors in this binding can: be updated after a 687 command buffer has bound this descriptor set, or while a command buffer 688 that uses this descriptor set is pending execution, as long as the 689 descriptors that are updated are not used by those command buffers. 690 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT is also set, then 691 descriptors can: be updated as long as they are not dynamically used by 692 any shader invocations. 693 If ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT is not set, then 694 descriptors can: be updated as long as they are not statically used by 695 any shader invocations. 696 * ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT_EXT indicates 697 that this descriptor binding has a variable size that will be specified 698 when a descriptor set is allocated using this layout. 699 The value of pname:descriptorCount is treated as an upper bound on the 700 size of the binding. 701 This must: only be used for the last binding in the descriptor set 702 layout (i.e. the binding with the largest value of pname:binding). 703 For the purposes of counting against limits such as 704 pname:maxDescriptorSet* and pname:maxPerStageDescriptor*, the full value 705 of pname:descriptorCount is counted. 706 707[NOTE] 708.Note 709==== 710Note that while ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT and 711ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT both involve 712updates to descriptor sets after they are bound, 713ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT is a weaker 714requirement since it is only about descriptors that are not used, whereas 715ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT requires the 716implementation to observe updates to descriptors that are used. 717==== 718 719-- 720endif::VK_EXT_descriptor_indexing[] 721 722ifdef::VK_VERSION_1_1,VK_KHR_maintenance3[] 723 724[open,refpage='vkGetDescriptorSetLayoutSupport',desc='Query whether a descriptor set layout can be created',type='protos'] 725-- 726 727To query information about whether a descriptor set layout can: be created, 728call: 729 730ifdef::VK_VERSION_1_1[] 731include::../api/protos/vkGetDescriptorSetLayoutSupport.txt[] 732endif::VK_VERSION_1_1[] 733 734ifdef::VK_VERSION_1_1+VK_KHR_maintenance3[or the equivalent command] 735 736ifdef::VK_KHR_maintenance3[] 737include::../api/protos/vkGetDescriptorSetLayoutSupportKHR.txt[] 738endif::VK_KHR_maintenance3[] 739 740 * pname:device is the logical device that would create the descriptor set 741 layout. 742 * pname:pCreateInfo is a pointer to an instance of the 743 slink:VkDescriptorSetLayoutCreateInfo structure specifying the state of 744 the descriptor set layout object. 745 * pname:pSupport points to a slink:VkDescriptorSetLayoutSupport structure 746 in which information about support for the descriptor set layout object 747 is returned. 748 749Some implementations have limitations on what fits in a descriptor set which 750are not easily expressible in terms of existing limits like 751pname:maxDescriptorSet*, for example if all descriptor types share a limited 752space in memory but each descriptor is a different size or alignment. 753This command returns information about whether a descriptor set satisfies 754this limit. 755If the descriptor set layout satisfies the 756slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 757limit, this command is guaranteed to return ename:VK_TRUE in 758slink:VkDescriptorSetLayoutSupport::pname:supported. 759If the descriptor set layout exceeds the 760slink:VkPhysicalDeviceMaintenance3Properties::pname:maxPerSetDescriptors 761limit, whether the descriptor set layout is supported is 762implementation-dependent and may: depend on whether the descriptor sizes and 763alignments cause the layout to exceed an internal limit. 764 765This command does not consider other limits such as 766pname:maxPerStageDescriptor*, and so a descriptor set layout that is 767supported according to this command must: still satisfy the pipeline layout 768limits such as pname:maxPerStageDescriptor* in order to be used in a 769pipeline layout. 770 771[NOTE] 772.Note 773==== 774This is a sname:VkDevice query rather than sname:VkPhysicalDevice because 775the answer may: depend on enabled features. 776==== 777 778include::../validity/protos/vkGetDescriptorSetLayoutSupport.txt[] 779-- 780 781[open,refpage='VkDescriptorSetLayoutSupport',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs'] 782-- 783 784Information about support for the descriptor set layout is returned in an 785instance of the sname:VkDescriptorSetLayoutSupport structure: 786 787include::../api/structs/VkDescriptorSetLayoutSupport.txt[] 788 789ifdef::VK_KHR_maintenance3[] 790or the equivalent 791 792include::../api/structs/VkDescriptorSetLayoutSupportKHR.txt[] 793endif::VK_KHR_maintenance3[] 794 795 * pname:sType is the type of this structure. 796 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 797 * pname:supported specifies whether the descriptor set layout can: be 798 created. 799 800pname:supported is set to ename:VK_TRUE if the descriptor set can: be 801created, or else is set to ename:VK_FALSE. 802 803include::../validity/structs/VkDescriptorSetLayoutSupport.txt[] 804-- 805 806endif::VK_VERSION_1_1,VK_KHR_maintenance3[] 807 808ifdef::VK_EXT_descriptor_indexing[] 809 810[open,refpage='VkDescriptorSetVariableDescriptorCountLayoutSupportEXT',desc='Structure returning information about whether a descriptor set layout can be supported',type='structs'] 811-- 812 813If the pname:pNext chain of a slink:VkDescriptorSetLayoutSupport structure 814includes a sname:VkDescriptorSetVariableDescriptorCountLayoutSupportEXT 815structure, then that structure returns additional information about whether 816the descriptor set layout is supported. 817 818include::../api/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.txt[] 819 820 * pname:sType is the type of this structure. 821 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 822 * pname:maxVariableDescriptorCount indicates the maximum number of 823 descriptors supported in the highest numbered binding of the layout, if 824 that binding is variable-sized. 825 826If the create info includes a variable-sized descriptor, then 827pname:supported is determined assuming the requested size of the 828variable-sized descriptor, and pname:maxVariableDescriptorCount is set to 829the maximum size of that descriptor that can: be successfully created (which 830is greater than or equal to the requested size passed in). 831If the create info does not include a variable-sized descriptor or if the 832slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT::pname:descriptorBindingVariableDescriptorCount 833feature is not enabled, then pname:maxVariableDescriptorCount is set to 834zero. 835For the purposes of this command, a variable-sized descriptor binding with a 836pname:descriptorCount of zero is treated as if the pname:descriptorCount is 837one, and thus the binding is not ignored and the maximum descriptor count 838will be returned. 839If the layout is not supported, then the value written to 840pname:maxVariableDescriptorCount is undefined. 841 842include::../validity/structs/VkDescriptorSetVariableDescriptorCountLayoutSupportEXT.txt[] 843-- 844 845endif::VK_EXT_descriptor_indexing[] 846 847The following examples show a shader snippet using two descriptor sets, and 848application code that creates corresponding descriptor set layouts. 849 850.GLSL example 851[source,glsl] 852--------------------------------------------------- 853// 854// binding to a single sampled image descriptor in set 0 855// 856layout (set=0, binding=0) uniform texture2D mySampledImage; 857 858// 859// binding to an array of sampled image descriptors in set 0 860// 861layout (set=0, binding=1) uniform texture2D myArrayOfSampledImages[12]; 862 863// 864// binding to a single uniform buffer descriptor in set 1 865// 866layout (set=1, binding=0) uniform myUniformBuffer 867{ 868 vec4 myElement[32]; 869}; 870--------------------------------------------------- 871 872.SPIR-V example 873[source,spirv] 874--------------------------------------------------- 875 ... 876 %1 = OpExtInstImport "GLSL.std.450" 877 ... 878 OpName %9 "mySampledImage" 879 OpName %14 "myArrayOfSampledImages" 880 OpName %18 "myUniformBuffer" 881 OpMemberName %18 0 "myElement" 882 OpName %20 "" 883 OpDecorate %9 DescriptorSet 0 884 OpDecorate %9 Binding 0 885 OpDecorate %14 DescriptorSet 0 886 OpDecorate %14 Binding 1 887 OpDecorate %17 ArrayStride 16 888 OpMemberDecorate %18 0 Offset 0 889 OpDecorate %18 Block 890 OpDecorate %20 DescriptorSet 1 891 OpDecorate %20 Binding 0 892 %2 = OpTypeVoid 893 %3 = OpTypeFunction %2 894 %6 = OpTypeFloat 32 895 %7 = OpTypeImage %6 2D 0 0 0 1 Unknown 896 %8 = OpTypePointer UniformConstant %7 897 %9 = OpVariable %8 UniformConstant 898 %10 = OpTypeInt 32 0 899 %11 = OpConstant %10 12 900 %12 = OpTypeArray %7 %11 901 %13 = OpTypePointer UniformConstant %12 902 %14 = OpVariable %13 UniformConstant 903 %15 = OpTypeVector %6 4 904 %16 = OpConstant %10 32 905 %17 = OpTypeArray %15 %16 906 %18 = OpTypeStruct %17 907 %19 = OpTypePointer Uniform %18 908 %20 = OpVariable %19 Uniform 909 ... 910--------------------------------------------------- 911 912.API example 913[source,c++] 914--------------------------------------------------- 915VkResult myResult; 916 917const VkDescriptorSetLayoutBinding myDescriptorSetLayoutBinding[] = 918{ 919 // binding to a single image descriptor 920 { 921 0, // binding 922 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType 923 1, // descriptorCount 924 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 925 NULL // pImmutableSamplers 926 }, 927 928 // binding to an array of image descriptors 929 { 930 1, // binding 931 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, // descriptorType 932 12, // descriptorCount 933 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 934 NULL // pImmutableSamplers 935 }, 936 937 // binding to a single uniform buffer descriptor 938 { 939 0, // binding 940 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType 941 1, // descriptorCount 942 VK_SHADER_STAGE_FRAGMENT_BIT, // stageFlags 943 NULL // pImmutableSamplers 944 } 945}; 946 947const VkDescriptorSetLayoutCreateInfo myDescriptorSetLayoutCreateInfo[] = 948{ 949 // Create info for first descriptor set with two descriptor bindings 950 { 951 VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType 952 NULL, // pNext 953 0, // flags 954 2, // bindingCount 955 &myDescriptorSetLayoutBinding[0] // pBindings 956 }, 957 958 // Create info for second descriptor set with one descriptor binding 959 { 960 VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO, // sType 961 NULL, // pNext 962 0, // flags 963 1, // bindingCount 964 &myDescriptorSetLayoutBinding[2] // pBindings 965 } 966}; 967 968VkDescriptorSetLayout myDescriptorSetLayout[2]; 969 970// 971// Create first descriptor set layout 972// 973myResult = vkCreateDescriptorSetLayout( 974 myDevice, 975 &myDescriptorSetLayoutCreateInfo[0], 976 NULL, 977 &myDescriptorSetLayout[0]); 978 979// 980// Create second descriptor set layout 981// 982myResult = vkCreateDescriptorSetLayout( 983 myDevice, 984 &myDescriptorSetLayoutCreateInfo[1], 985 NULL, 986 &myDescriptorSetLayout[1]); 987--------------------------------------------------- 988 989[open,refpage='vkDestroyDescriptorSetLayout',desc='Destroy a descriptor set layout object',type='protos'] 990-- 991 992To destroy a descriptor set layout, call: 993 994include::../api/protos/vkDestroyDescriptorSetLayout.txt[] 995 996 * pname:device is the logical device that destroys the descriptor set 997 layout. 998 * pname:descriptorSetLayout is the descriptor set layout to destroy. 999 * pname:pAllocator controls host memory allocation as described in the 1000 <<memory-allocation, Memory Allocation>> chapter. 1001 1002.Valid Usage 1003**** 1004 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00284]] 1005 If sname:VkAllocationCallbacks were provided when 1006 pname:descriptorSetLayout was created, a compatible set of callbacks 1007 must: be provided here 1008 * [[VUID-vkDestroyDescriptorSetLayout-descriptorSetLayout-00285]] 1009 If no sname:VkAllocationCallbacks were provided when 1010 pname:descriptorSetLayout was created, pname:pAllocator must: be `NULL` 1011**** 1012 1013include::../validity/protos/vkDestroyDescriptorSetLayout.txt[] 1014-- 1015 1016 1017[[descriptorsets-pipelinelayout]] 1018=== Pipeline Layouts 1019 1020[open,refpage='VkPipelineLayout',desc='Opaque handle to a pipeline layout object',type='handles'] 1021-- 1022 1023Access to descriptor sets from a pipeline is accomplished through a 1024_pipeline layout_. 1025Zero or more descriptor set layouts and zero or more push constant ranges 1026are combined to form a pipeline layout object which describes the complete 1027set of resources that can: be accessed by a pipeline. 1028The pipeline layout represents a sequence of descriptor sets with each 1029having a specific layout. 1030This sequence of layouts is used to determine the interface between shader 1031stages and shader resources. 1032Each pipeline is created using a pipeline layout. 1033 1034Pipeline layout objects are represented by sname:VkPipelineLayout handles: 1035 1036include::../api/handles/VkPipelineLayout.txt[] 1037 1038-- 1039 1040[open,refpage='vkCreatePipelineLayout',desc='Creates a new pipeline layout object',type='protos'] 1041-- 1042 1043To create a pipeline layout, call: 1044 1045include::../api/protos/vkCreatePipelineLayout.txt[] 1046 1047 * pname:device is the logical device that creates the pipeline layout. 1048 * pname:pCreateInfo is a pointer to an instance of the 1049 slink:VkPipelineLayoutCreateInfo structure specifying the state of the 1050 pipeline layout object. 1051 * pname:pAllocator controls host memory allocation as described in the 1052 <<memory-allocation, Memory Allocation>> chapter. 1053 * pname:pPipelineLayout points to a slink:VkPipelineLayout handle in which 1054 the resulting pipeline layout object is returned. 1055 1056include::../validity/protos/vkCreatePipelineLayout.txt[] 1057-- 1058 1059[open,refpage='VkPipelineLayoutCreateInfo',desc='Structure specifying the parameters of a newly created pipeline layout object',type='structs'] 1060-- 1061 1062The slink:VkPipelineLayoutCreateInfo structure is defined as: 1063 1064include::../api/structs/VkPipelineLayoutCreateInfo.txt[] 1065 1066 * pname:sType is the type of this structure. 1067 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1068 * pname:flags is reserved for future use. 1069 * pname:setLayoutCount is the number of descriptor sets included in the 1070 pipeline layout. 1071 * pname:pSetLayouts is a pointer to an array of 1072 sname:VkDescriptorSetLayout objects. 1073 * pname:pushConstantRangeCount is the number of push constant ranges 1074 included in the pipeline layout. 1075 * pname:pPushConstantRanges is a pointer to an array of 1076 sname:VkPushConstantRange structures defining a set of push constant 1077 ranges for use in a single pipeline layout. 1078 In addition to descriptor set layouts, a pipeline layout also describes 1079 how many push constants can: be accessed by each stage of the pipeline. 1080+ 1081[NOTE] 1082.Note 1083==== 1084Push constants represent a high speed path to modify constant data in 1085pipelines that is expected to outperform memory-backed resource updates. 1086==== 1087 1088.Valid Usage 1089**** 1090 * [[VUID-VkPipelineLayoutCreateInfo-setLayoutCount-00286]] 1091 pname:setLayoutCount must: be less than or equal to 1092 sname:VkPhysicalDeviceLimits::pname:maxBoundDescriptorSets 1093ifndef::VK_EXT_descriptor_indexing[] 1094 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00287]] 1095 The total number of descriptors of the type 1096 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1097 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any shader 1098 stage across all elements of pname:pSetLayouts must: be less than or 1099 equal to 1100 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSamplers 1101 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00288]] 1102 The total number of descriptors of the type 1103 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1104 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any shader 1105 stage across all elements of pname:pSetLayouts must: be less than or 1106 equal to 1107 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorUniformBuffers 1108 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00289]] 1109 The total number of descriptors of the type 1110 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1111 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any shader 1112 stage across all elements of pname:pSetLayouts must: be less than or 1113 equal to 1114 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageBuffers 1115 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00290]] 1116 The total number of descriptors of the type 1117 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1118 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1119 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any shader 1120 stage across all elements of pname:pSetLayouts must: be less than or 1121 equal to 1122 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSampledImages 1123 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00291]] 1124 The total number of descriptors of the type 1125 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1126 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any shader 1127 stage across all elements of pname:pSetLayouts must: be less than or 1128 equal to 1129 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageImages 1130 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01676]] 1131 The total number of descriptors of the type 1132 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1133 stage across all elements of pname:pSetLayouts must: be less than or 1134 equal to 1135 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorInputAttachments 1136 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01677]] 1137 The total number of descriptors of the type 1138 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1139 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1140 shader stages and across all elements of pname:pSetLayouts must: be less 1141 than or equal to 1142 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSamplers 1143 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01678]] 1144 The total number of descriptors of the type 1145 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1146 stages and across all elements of pname:pSetLayouts must: be less than 1147 or equal to 1148 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffers 1149 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01679]] 1150 The total number of descriptors of the type 1151 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1152 shader stages and across all elements of pname:pSetLayouts must: be less 1153 than or equal to 1154 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffersDynamic 1155 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01680]] 1156 The total number of descriptors of the type 1157 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1158 stages and across all elements of pname:pSetLayouts must: be less than 1159 or equal to 1160 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffers 1161 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01681]] 1162 The total number of descriptors of the type 1163 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1164 shader stages and across all elements of pname:pSetLayouts must: be less 1165 than or equal to 1166 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffersDynamic 1167 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01682]] 1168 The total number of descriptors of the type 1169 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1170 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1171 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1172 shader stages and across all elements of pname:pSetLayouts must: be less 1173 than or equal to 1174 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSampledImages 1175 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01683]] 1176 The total number of descriptors of the type 1177 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1178 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1179 shader stages and across all elements of pname:pSetLayouts must: be less 1180 than or equal to 1181 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageImages 1182 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-01684]] 1183 The total number of descriptors of the type 1184 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1185 stages and across all elements of pname:pSetLayouts must: be less than 1186 or equal to 1187 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetInputAttachments 1188endif::VK_EXT_descriptor_indexing[] 1189ifdef::VK_EXT_descriptor_indexing[] 1190 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03016]] 1191 The total number of descriptors in descriptor set layouts created 1192 without the 1193 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1194 set with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1195 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1196 shader stage across all elements of pname:pSetLayouts must: be less than 1197 or equal to 1198 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSamplers 1199 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03017]] 1200 The total number of descriptors in descriptor set layouts created 1201 without the 1202 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1203 set with a pname:descriptorType of 1204 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1205 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any given 1206 shader stage across all elements of pname:pSetLayouts must: be less than 1207 or equal to 1208 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorUniformBuffers 1209 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03018]] 1210 The total number of descriptors in descriptor set layouts created 1211 without the 1212 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1213 set with a pname:descriptorType of 1214 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1215 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any given 1216 shader stage across all elements of pname:pSetLayouts must: be less than 1217 or equal to 1218 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageBuffers 1219 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03019]] 1220 The total number of descriptors in descriptor set layouts created 1221 without the 1222 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1223 set with a pname:descriptorType of 1224 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1225 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1226 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any given 1227 shader stage across all elements of pname:pSetLayouts must: be less than 1228 or equal to 1229 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorSampledImages 1230 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03020]] 1231 The total number of descriptors in descriptor set layouts created 1232 without the 1233 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1234 set with a pname:descriptorType of 1235 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1236 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any given 1237 shader stage across all elements of pname:pSetLayouts must: be less than 1238 or equal to 1239 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorStorageImages 1240 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03021]] 1241 The total number of descriptors in descriptor set layouts created 1242 without the 1243 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1244 set with a pname:descriptorType of 1245 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1246 stage across all elements of pname:pSetLayouts must: be less than or 1247 equal to 1248 sname:VkPhysicalDeviceLimits::pname:maxPerStageDescriptorInputAttachments 1249 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03022]] 1250 The total number of descriptors with a pname:descriptorType of 1251 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1252 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible to any given 1253 shader stage across all elements of pname:pSetLayouts must: be less than 1254 or equal to 1255 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindSamplers 1256 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03023]] 1257 The total number of descriptors with a pname:descriptorType of 1258 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER and 1259 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible to any given 1260 shader stage across all elements of pname:pSetLayouts must: be less than 1261 or equal to 1262 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindUniformBuffers 1263 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03024]] 1264 The total number of descriptors with a pname:descriptorType of 1265 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER and 1266 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible to any given 1267 shader stage across all elements of pname:pSetLayouts must: be less than 1268 or equal to 1269 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindStorageBuffers 1270 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03025]] 1271 The total number of descriptors with a pname:descriptorType of 1272 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1273 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1274 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible to any given 1275 shader stage across all elements of pname:pSetLayouts must: be less than 1276 or equal to 1277 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindSampledImages 1278 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03026]] 1279 The total number of descriptors with a pname:descriptorType of 1280 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1281 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible to any given 1282 shader stage across all elements of pname:pSetLayouts must: be less than 1283 or equal to 1284 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindStorageImages 1285 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03027]] 1286 The total number of descriptors with a pname:descriptorType of 1287 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible to any given shader 1288 stage across all elements of pname:pSetLayouts must: be less than or 1289 equal to 1290 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxPerStageDescriptorUpdateAfterBindInputAttachments 1291 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03028]] 1292 The total number of descriptors in descriptor set layouts created 1293 without the 1294 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1295 set with a pname:descriptorType of ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1296 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1297 shader stages and across all elements of pname:pSetLayouts must: be less 1298 than or equal to 1299 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSamplers 1300 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03029]] 1301 The total number of descriptors in descriptor set layouts created 1302 without the 1303 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1304 set with a pname:descriptorType of 1305 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1306 stages and across all elements of pname:pSetLayouts must: be less than 1307 or equal to 1308 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffers 1309 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03030]] 1310 The total number of descriptors in descriptor set layouts created 1311 without the 1312 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1313 set with a pname:descriptorType of 1314 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1315 shader stages and across all elements of pname:pSetLayouts must: be less 1316 than or equal to 1317 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetUniformBuffersDynamic 1318 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03031]] 1319 The total number of descriptors in descriptor set layouts created 1320 without the 1321 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1322 set with a pname:descriptorType of 1323 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1324 stages and across all elements of pname:pSetLayouts must: be less than 1325 or equal to 1326 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffers 1327 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03032]] 1328 The total number of descriptors in descriptor set layouts created 1329 without the 1330 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1331 set with a pname:descriptorType of 1332 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1333 shader stages and across all elements of pname:pSetLayouts must: be less 1334 than or equal to 1335 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageBuffersDynamic 1336 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03033]] 1337 The total number of descriptors in descriptor set layouts created 1338 without the 1339 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1340 set with a pname:descriptorType of 1341 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1342 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1343 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1344 shader stages and across all elements of pname:pSetLayouts must: be less 1345 than or equal to 1346 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetSampledImages 1347 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03034]] 1348 The total number of descriptors in descriptor set layouts created 1349 without the 1350 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1351 set with a pname:descriptorType of 1352 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1353 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1354 shader stages and across all elements of pname:pSetLayouts must: be less 1355 than or equal to 1356 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetStorageImages 1357 * [[VUID-VkPipelineLayoutCreateInfo-descriptorType-03035]] 1358 The total number of descriptors in descriptor set layouts created 1359 without the 1360 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 1361 set with a pname:descriptorType of 1362 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1363 stages and across all elements of pname:pSetLayouts must: be less than 1364 or equal to 1365 sname:VkPhysicalDeviceLimits::pname:maxDescriptorSetInputAttachments 1366 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03036]] 1367 The total number of descriptors of the type 1368 ename:VK_DESCRIPTOR_TYPE_SAMPLER and 1369 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER accessible across all 1370 shader stages and across all elements of pname:pSetLayouts must: be less 1371 than or equal to 1372 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindSamplers 1373 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03037]] 1374 The total number of descriptors of the type 1375 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER accessible across all shader 1376 stages and across all elements of pname:pSetLayouts must: be less than 1377 or equal to 1378 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindUniformBuffers 1379 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03038]] 1380 The total number of descriptors of the type 1381 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC accessible across all 1382 shader stages and across all elements of pname:pSetLayouts must: be less 1383 than or equal to 1384 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 1385 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03039]] 1386 The total number of descriptors of the type 1387 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER accessible across all shader 1388 stages and across all elements of pname:pSetLayouts must: be less than 1389 or equal to 1390 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindStorageBuffers 1391 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03040]] 1392 The total number of descriptors of the type 1393 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC accessible across all 1394 shader stages and across all elements of pname:pSetLayouts must: be less 1395 than or equal to 1396 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 1397 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03041]] 1398 The total number of descriptors of the type 1399 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 1400 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, and 1401 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER accessible across all 1402 shader stages and across all elements of pname:pSetLayouts must: be less 1403 than or equal to 1404 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindSampledImages 1405 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03042]] 1406 The total number of descriptors of the type 1407 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, and 1408 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER accessible across all 1409 shader stages and across all elements of pname:pSetLayouts must: be less 1410 than or equal to 1411 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindStorageImages 1412 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-03043]] 1413 The total number of descriptors of the type 1414 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT accessible across all shader 1415 stages and across all elements of pname:pSetLayouts must: be less than 1416 or equal to 1417 sname:VkPhysicalDeviceDescriptorIndexingPropertiesEXT::pname:maxDescriptorSetUpdateAfterBindInputAttachments 1418endif::VK_EXT_descriptor_indexing[] 1419 * [[VUID-VkPipelineLayoutCreateInfo-pPushConstantRanges-00292]] 1420 Any two elements of pname:pPushConstantRanges must: not include the same 1421 stage in pname:stageFlags 1422ifdef::VK_KHR_push_descriptor[] 1423 * [[VUID-VkPipelineLayoutCreateInfo-pSetLayouts-00293]] 1424 pname:pSetLayouts must: not contain more than one descriptor set layout 1425 that was created with 1426 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 1427endif::VK_KHR_push_descriptor[] 1428**** 1429 1430include::../validity/structs/VkPipelineLayoutCreateInfo.txt[] 1431-- 1432 1433[open,refpage='VkPipelineLayoutCreateFlags',desc='Reserved for future use',type='enums'] 1434-- 1435include::../api/flags/VkPipelineLayoutCreateFlags.txt[] 1436 1437sname:VkPipelineLayoutCreateFlags is a bitmask type for setting a mask, but 1438is currently reserved for future use. 1439-- 1440 1441[open,refpage='VkPushConstantRange',desc='Structure specifying a push constant range',type='structs'] 1442-- 1443 1444The sname:VkPushConstantRange structure is defined as: 1445 1446include::../api/structs/VkPushConstantRange.txt[] 1447 1448 * pname:stageFlags is a set of stage flags describing the shader stages 1449 that will access a range of push constants. 1450 If a particular stage is not included in the range, then accessing 1451 members of that range of push constants from the corresponding shader 1452 stage will result in undefined data being read. 1453 * pname:offset and pname:size are the start offset and size, respectively, 1454 consumed by the range. 1455 Both pname:offset and pname:size are in units of bytes and must: be a 1456 multiple of 4. 1457 The layout of the push constant variables is specified in the shader. 1458 1459.Valid Usage 1460**** 1461 * [[VUID-VkPushConstantRange-offset-00294]] 1462 pname:offset must: be less than 1463 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 1464 * [[VUID-VkPushConstantRange-offset-00295]] 1465 pname:offset must: be a multiple of `4` 1466 * [[VUID-VkPushConstantRange-size-00296]] 1467 pname:size must: be greater than `0` 1468 * [[VUID-VkPushConstantRange-size-00297]] 1469 pname:size must: be a multiple of `4` 1470 * [[VUID-VkPushConstantRange-size-00298]] 1471 pname:size must: be less than or equal to 1472 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 1473 pname:offset 1474**** 1475 1476include::../validity/structs/VkPushConstantRange.txt[] 1477-- 1478 1479Once created, pipeline layouts are used as part of pipeline creation (see 1480<<pipelines, Pipelines>>), as part of binding descriptor sets (see 1481<<descriptorsets-binding, Descriptor Set Binding>>), and as part of setting 1482push constants (see <<descriptorsets-push-constants, Push Constant 1483Updates>>). 1484Pipeline creation accepts a pipeline layout as input, and the layout may: be 1485used to map (set, binding, arrayElement) tuples to implementation resources 1486or memory locations within a descriptor set. 1487The assignment of implementation resources depends only on the bindings 1488defined in the descriptor sets that comprise the pipeline layout, and not on 1489any shader source. 1490 1491[[descriptorsets-pipelinelayout-consistency]] 1492All resource variables <<shaders-staticuse,statically used>> in all shaders 1493in a pipeline must: be declared with a (set,binding,arrayElement) that 1494exists in the corresponding descriptor set layout and is of an appropriate 1495descriptor type and includes the set of shader stages it is used by in 1496pname:stageFlags. 1497The pipeline layout can: include entries that are not used by a particular 1498pipeline, or that are dead-code eliminated from any of the shaders. 1499The pipeline layout allows the application to provide a consistent set of 1500bindings across multiple pipeline compiles, which enables those pipelines to 1501be compiled in a way that the implementation may: cheaply switch pipelines 1502without reprogramming the bindings. 1503 1504Similarly, the push constant block declared in each shader (if present) 1505must: only place variables at offsets that are each included in a push 1506constant range with pname:stageFlags including the bit corresponding to the 1507shader stage that uses it. 1508The pipeline layout can: include ranges or portions of ranges that are not 1509used by a particular pipeline, or for which the variables have been 1510dead-code eliminated from any of the shaders. 1511 1512There is a limit on the total number of resources of each type that can: be 1513included in bindings in all descriptor set layouts in a pipeline layout as 1514shown in <<descriptorsets-pipelinelayout-limits,Pipeline Layout Resource 1515Limits>>. 1516The "`Total Resources Available`" column gives the limit on the number of 1517each type of resource that can: be included in bindings in all descriptor 1518sets in the pipeline layout. 1519Some resource types count against multiple limits. 1520Additionally, there are limits on the total number of each type of resource 1521that can: be used in any pipeline stage as described in 1522<<interfaces-resources-limits,Shader Resource Limits>>. 1523 1524[[descriptorsets-pipelinelayout-limits]] 1525.Pipeline Layout Resource Limits 1526[width="80%",cols="<37,<22",options="header"] 1527|==== 1528| Total Resources Available | Resource Types 1529.2+<.^| pname:maxDescriptorSetSamplers 1530ifdef::VK_EXT_descriptor_indexing[] 1531or pname:maxDescriptorSetUpdateAfterBindSamplers 1532endif::VK_EXT_descriptor_indexing[] 1533 | sampler | combined image sampler 1534.3+<.^| pname:maxDescriptorSetSampledImages 1535ifdef::VK_EXT_descriptor_indexing[] 1536or pname:maxDescriptorSetUpdateAfterBindSampledImages 1537endif::VK_EXT_descriptor_indexing[] 1538 | sampled image | combined image sampler | uniform texel buffer 1539.2+<.^| pname:maxDescriptorSetStorageImages 1540ifdef::VK_EXT_descriptor_indexing[] 1541or pname:maxDescriptorSetUpdateAfterBindStorageImages 1542endif::VK_EXT_descriptor_indexing[] 1543 | storage image | storage texel buffer 1544.2+<.^| pname:maxDescriptorSetUniformBuffers 1545ifdef::VK_EXT_descriptor_indexing[] 1546or pname:maxDescriptorSetUpdateAfterBindUniformBuffers 1547endif::VK_EXT_descriptor_indexing[] 1548 | uniform buffer | uniform buffer dynamic 1549| pname:maxDescriptorSetUniformBuffersDynamic 1550ifdef::VK_EXT_descriptor_indexing[] 1551or pname:maxDescriptorSetUpdateAfterBindUniformBuffersDynamic 1552endif::VK_EXT_descriptor_indexing[] 1553 | uniform buffer dynamic 1554.2+<.^| pname:maxDescriptorSetStorageBuffers 1555ifdef::VK_EXT_descriptor_indexing[] 1556or pname:maxDescriptorSetUpdateAfterBindStorageBuffers 1557endif::VK_EXT_descriptor_indexing[] 1558 | storage buffer | storage buffer dynamic 1559| pname:maxDescriptorSetStorageBuffersDynamic 1560ifdef::VK_EXT_descriptor_indexing[] 1561or pname:maxDescriptorSetUpdateAfterBindStorageBuffersDynamic 1562endif::VK_EXT_descriptor_indexing[] 1563 | storage buffer dynamic 1564| pname:maxDescriptorSetInputAttachments 1565ifdef::VK_EXT_descriptor_indexing[] 1566or pname:maxDescriptorSetUpdateAfterBindInputAttachments 1567endif::VK_EXT_descriptor_indexing[] 1568 | input attachment 1569|==== 1570 1571 1572[open,refpage='vkDestroyPipelineLayout',desc='Destroy a pipeline layout object',type='protos'] 1573-- 1574 1575To destroy a pipeline layout, call: 1576 1577include::../api/protos/vkDestroyPipelineLayout.txt[] 1578 1579 * pname:device is the logical device that destroys the pipeline layout. 1580 * pname:pipelineLayout is the pipeline layout to destroy. 1581 * pname:pAllocator controls host memory allocation as described in the 1582 <<memory-allocation, Memory Allocation>> chapter. 1583 1584.Valid Usage 1585**** 1586 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00299]] 1587 If sname:VkAllocationCallbacks were provided when pname:pipelineLayout 1588 was created, a compatible set of callbacks must: be provided here 1589 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-00300]] 1590 If no sname:VkAllocationCallbacks were provided when 1591 pname:pipelineLayout was created, pname:pAllocator must: be `NULL` 1592 * [[VUID-vkDestroyPipelineLayout-pipelineLayout-02004]] 1593 pname:pipelineLayout must: not have been passed to any vkCmd* command 1594 for any command buffers that are still in the 1595 <<commandbuffers-lifecycle, recording state>> when 1596 fname:vkDestroyPipelineLayout is called 1597**** 1598 1599include::../validity/protos/vkDestroyPipelineLayout.txt[] 1600-- 1601 1602 1603[[descriptorsets-compatibility]] 1604==== Pipeline Layout Compatibility 1605 1606Two pipeline layouts are defined to be "`compatible for 1607<<descriptorsets-push-constants, push constants>>`" if they were created 1608with identical push constant ranges. 1609Two pipeline layouts are defined to be "`compatible for set N`" if they were 1610created with _identically defined_ descriptor set layouts for sets zero 1611through N, and if they were created with identical push constant ranges. 1612 1613When binding a descriptor set (see <<descriptorsets-binding, Descriptor Set 1614Binding>>) to set number N, if the previously bound descriptor sets for sets 1615zero through N-1 were all bound using compatible pipeline layouts, then 1616performing this binding does not disturb any of the lower numbered sets. 1617If, additionally, the previous bound descriptor set for set N was bound 1618using a pipeline layout compatible for set N, then the bindings in sets 1619numbered greater than N are also not disturbed. 1620 1621Similarly, when binding a pipeline, the pipeline can: correctly access any 1622previously bound descriptor sets which were bound with compatible pipeline 1623layouts, as long as all lower numbered sets were also bound with compatible 1624layouts. 1625 1626Layout compatibility means that descriptor sets can: be bound to a command 1627buffer for use by any pipeline created with a compatible pipeline layout, 1628and without having bound a particular pipeline first. 1629It also means that descriptor sets can: remain valid across a pipeline 1630change, and the same resources will be accessible to the newly bound 1631pipeline. 1632 1633ifdef::implementation-guide[] 1634.Implementor's Note 1635**** 1636A consequence of layout compatibility is that when the implementation 1637compiles a pipeline layout and maps pipeline resources to implementation 1638resources, the mechanism for set N should: only be a function of sets 1639[0..N]. 1640**** 1641endif::implementation-guide[] 1642 1643 1644[NOTE] 1645.Note 1646==== 1647Place the least frequently changing descriptor sets near the start of the 1648pipeline layout, and place the descriptor sets representing the most 1649frequently changing resources near the end. 1650When pipelines are switched, only the descriptor set bindings that have been 1651invalidated will need to be updated and the remainder of the descriptor set 1652bindings will remain in place. 1653==== 1654 1655The maximum number of descriptor sets that can: be bound to a pipeline 1656layout is queried from physical device properties (see 1657pname:maxBoundDescriptorSets in <<features-limits, Limits>>). 1658 1659.API example 1660[source,c++] 1661--------------------------------------------------- 1662const VkDescriptorSetLayout layouts[] = { layout1, layout2 }; 1663 1664const VkPushConstantRange ranges[] = 1665{ 1666 { 1667 VK_PIPELINE_STAGE_VERTEX_SHADER_BIT, // stageFlags 1668 0, // offset 1669 4 // size 1670 }, 1671 1672 { 1673 VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, // stageFlags 1674 4, // offset 1675 4 // size 1676 }, 1677}; 1678 1679const VkPipelineLayoutCreateInfo createInfo = 1680{ 1681 VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO, // sType 1682 NULL, // pNext 1683 0, // flags 1684 2, // setLayoutCount 1685 layouts, // pSetLayouts 1686 2, // pushConstantRangeCount 1687 ranges // pPushConstantRanges 1688}; 1689 1690VkPipelineLayout myPipelineLayout; 1691myResult = vkCreatePipelineLayout( 1692 myDevice, 1693 &createInfo, 1694 NULL, 1695 &myPipelineLayout); 1696--------------------------------------------------- 1697 1698 1699[[descriptorsets-allocation]] 1700=== Allocation of Descriptor Sets 1701 1702[open,refpage='VkDescriptorPool',desc='Opaque handle to a descriptor pool object',type='handles'] 1703-- 1704 1705A _descriptor pool_ maintains a pool of descriptors, from which descriptor 1706sets are allocated. 1707Descriptor pools are externally synchronized, meaning that the application 1708must: not allocate and/or free descriptor sets from the same pool in 1709multiple threads simultaneously. 1710 1711Descriptor pools are represented by sname:VkDescriptorPool handles: 1712 1713include::../api/handles/VkDescriptorPool.txt[] 1714 1715-- 1716 1717[open,refpage='vkCreateDescriptorPool',desc='Creates a descriptor pool object',type='protos'] 1718-- 1719 1720To create a descriptor pool object, call: 1721 1722include::../api/protos/vkCreateDescriptorPool.txt[] 1723 1724 * pname:device is the logical device that creates the descriptor pool. 1725 * pname:pCreateInfo is a pointer to an instance of the 1726 slink:VkDescriptorPoolCreateInfo structure specifying the state of the 1727 descriptor pool object. 1728 * pname:pAllocator controls host memory allocation as described in the 1729 <<memory-allocation, Memory Allocation>> chapter. 1730 * pname:pDescriptorPool points to a slink:VkDescriptorPool handle in which 1731 the resulting descriptor pool object is returned. 1732 1733pname:pAllocator controls host memory allocation as described in the 1734<<memory-allocation, Memory Allocation>> chapter. 1735 1736The created descriptor pool is returned in pname:pDescriptorPool. 1737 1738include::../validity/protos/vkCreateDescriptorPool.txt[] 1739-- 1740 1741[open,refpage='VkDescriptorPoolCreateInfo',desc='Structure specifying parameters of a newly created descriptor pool',type='structs'] 1742-- 1743 1744Additional information about the pool is passed in an instance of the 1745sname:VkDescriptorPoolCreateInfo structure: 1746 1747include::../api/structs/VkDescriptorPoolCreateInfo.txt[] 1748 1749 * pname:sType is the type of this structure. 1750 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1751 * pname:flags is a bitmask of elink:VkDescriptorPoolCreateFlagBits 1752 specifying certain supported operations on the pool. 1753 * pname:maxSets is the maximum number of descriptor sets that can: be 1754 allocated from the pool. 1755 * pname:poolSizeCount is the number of elements in pname:pPoolSizes. 1756 * pname:pPoolSizes is a pointer to an array of slink:VkDescriptorPoolSize 1757 structures, each containing a descriptor type and number of descriptors 1758 of that type to be allocated in the pool. 1759 1760If multiple sname:VkDescriptorPoolSize structures appear in the 1761pname:pPoolSizes array then the pool will be created with enough storage for 1762the total number of descriptors of each type. 1763 1764Fragmentation of a descriptor pool is possible and may: lead to descriptor 1765set allocation failures. 1766A failure due to fragmentation is defined as failing a descriptor set 1767allocation despite the sum of all outstanding descriptor set allocations 1768from the pool plus the requested allocation requiring no more than the total 1769number of descriptors requested at pool creation. 1770Implementations provide certain guarantees of when fragmentation must: not 1771cause allocation failure, as described below. 1772 1773If a descriptor pool has not had any descriptor sets freed since it was 1774created or most recently reset then fragmentation must: not cause an 1775allocation failure (note that this is always the case for a pool created 1776without the ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT bit 1777set). 1778Additionally, if all sets allocated from the pool since it was created or 1779most recently reset use the same number of descriptors (of each type) and 1780the requested allocation also uses that same number of descriptors (of each 1781type), then fragmentation must: not cause an allocation failure. 1782 1783If an allocation failure occurs due to fragmentation, an application can: 1784create an additional descriptor pool to perform further descriptor set 1785allocations. 1786 1787ifdef::VK_EXT_descriptor_indexing[] 1788If pname:flags has the 1789ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT bit set, 1790descriptor pool creation may: fail with the error 1791ename:VK_ERROR_FRAGMENTATION_EXT if the total number of descriptors across 1792all pools (including this one) created with this bit set exceeds 1793pname:maxUpdateAfterBindDescriptorsInAllPools, or if fragmentation of the 1794underlying hardware resources occurs. 1795endif::VK_EXT_descriptor_indexing[] 1796 1797.Valid Usage 1798**** 1799 * [[VUID-VkDescriptorPoolCreateInfo-maxSets-00301]] 1800 pname:maxSets must: be greater than `0` 1801**** 1802 1803include::../validity/structs/VkDescriptorPoolCreateInfo.txt[] 1804-- 1805 1806[open,refpage='VkDescriptorPoolCreateFlagBits',desc='Bitmask specifying certain supported operations on a descriptor pool',type='enums'] 1807-- 1808 1809Bits which can: be set in slink:VkDescriptorPoolCreateInfo::pname:flags to 1810enable operations on a descriptor pool are: 1811 1812include::../api/enums/VkDescriptorPoolCreateFlagBits.txt[] 1813 1814 * ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT specifies that 1815 descriptor sets can: return their individual allocations to the pool, 1816 i.e. all of flink:vkAllocateDescriptorSets, flink:vkFreeDescriptorSets, 1817 and flink:vkResetDescriptorPool are allowed. 1818 Otherwise, descriptor sets allocated from the pool must: not be 1819 individually freed back to the pool, i.e. only 1820 flink:vkAllocateDescriptorSets and flink:vkResetDescriptorPool are 1821 allowed. 1822ifdef::VK_EXT_descriptor_indexing[] 1823 * ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT specifies that 1824 descriptor sets allocated from this pool can: include bindings with the 1825 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set. 1826 It is valid to allocate descriptor sets that have bindings that do not 1827 set the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit from a 1828 pool that has ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT 1829 set. 1830endif::VK_EXT_descriptor_indexing[] 1831 1832-- 1833 1834[open,refpage='VkDescriptorPoolCreateFlags',desc='Bitmask of VkDescriptorPoolCreateFlagBits',type='enums'] 1835-- 1836include::../api/flags/VkDescriptorPoolCreateFlags.txt[] 1837 1838sname:VkDescriptorPoolCreateFlags is a bitmask type for setting a mask of 1839zero or more slink:VkDescriptorPoolCreateFlagBits. 1840-- 1841 1842[open,refpage='VkDescriptorPoolSize',desc='Structure specifying descriptor pool size',type='structs'] 1843-- 1844 1845The sname:VkDescriptorPoolSize structure is defined as: 1846 1847include::../api/structs/VkDescriptorPoolSize.txt[] 1848 1849 * pname:type is the type of descriptor. 1850 * pname:descriptorCount is the number of descriptors of that type to 1851 allocate. 1852 1853.Valid Usage 1854**** 1855 * [[VUID-VkDescriptorPoolSize-descriptorCount-00302]] 1856 pname:descriptorCount must: be greater than `0` 1857**** 1858 1859include::../validity/structs/VkDescriptorPoolSize.txt[] 1860-- 1861 1862[open,refpage='vkDestroyDescriptorPool',desc='Destroy a descriptor pool object',type='protos'] 1863-- 1864 1865To destroy a descriptor pool, call: 1866 1867include::../api/protos/vkDestroyDescriptorPool.txt[] 1868 1869 * pname:device is the logical device that destroys the descriptor pool. 1870 * pname:descriptorPool is the descriptor pool to destroy. 1871 * pname:pAllocator controls host memory allocation as described in the 1872 <<memory-allocation, Memory Allocation>> chapter. 1873 1874When a pool is destroyed, all descriptor sets allocated from the pool are 1875implicitly freed and become invalid. 1876Descriptor sets allocated from a given pool do not need to be freed before 1877destroying that descriptor pool. 1878 1879.Valid Usage 1880**** 1881 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00303]] 1882 All submitted commands that refer to pname:descriptorPool (via any 1883 allocated descriptor sets) must: have completed execution 1884 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00304]] 1885 If sname:VkAllocationCallbacks were provided when pname:descriptorPool 1886 was created, a compatible set of callbacks must: be provided here 1887 * [[VUID-vkDestroyDescriptorPool-descriptorPool-00305]] 1888 If no sname:VkAllocationCallbacks were provided when 1889 pname:descriptorPool was created, pname:pAllocator must: be `NULL` 1890**** 1891 1892include::../validity/protos/vkDestroyDescriptorPool.txt[] 1893-- 1894 1895[open,refpage='VkDescriptorSet',desc='Opaque handle to a descriptor set object',type='handles'] 1896-- 1897 1898Descriptor sets are allocated from descriptor pool objects, and are 1899represented by sname:VkDescriptorSet handles: 1900 1901include::../api/handles/VkDescriptorSet.txt[] 1902 1903-- 1904 1905[open,refpage='vkAllocateDescriptorSets',desc='Allocate one or more descriptor sets',type='protos'] 1906-- 1907 1908To allocate descriptor sets from a descriptor pool, call: 1909 1910include::../api/protos/vkAllocateDescriptorSets.txt[] 1911 1912 * pname:device is the logical device that owns the descriptor pool. 1913 * pname:pAllocateInfo is a pointer to an instance of the 1914 slink:VkDescriptorSetAllocateInfo structure describing parameters of the 1915 allocation. 1916 * pname:pDescriptorSets is a pointer to an array of slink:VkDescriptorSet 1917 handles in which the resulting descriptor set objects are returned. 1918 1919The allocated descriptor sets are returned in pname:pDescriptorSets. 1920 1921When a descriptor set is allocated, the initial state is largely 1922uninitialized and all descriptors are undefined. 1923However, the descriptor set can: be bound in a command buffer without 1924causing errors or exceptions. 1925ifdef::VK_EXT_descriptor_indexing[] 1926For descriptor set bindings created with the 1927ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT bit set, all descriptors 1928in that binding that are dynamically used must: have been populated before 1929the descriptor set is <<descriptorsets-binding,consumed>>. 1930For descriptor set bindings created without the 1931ename:VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT bit set, all descriptors 1932in that binding that are statically used must: have been populated before 1933the descriptor set is <<descriptorsets-binding,consumed>>. 1934endif::VK_EXT_descriptor_indexing[] 1935ifndef::VK_EXT_descriptor_indexing[] 1936All descriptors that are statically used must: have been populated before 1937the descriptor set is consumed. 1938endif::VK_EXT_descriptor_indexing[] 1939Entries that are not used by a pipeline can: have uninitialized descriptors 1940or descriptors of resources that have been destroyed, and executing a draw 1941or dispatch with such a descriptor set bound does not cause undefined 1942behavior. 1943This means applications need not populate unused entries with dummy 1944descriptors. 1945 1946ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1947If a call to fname:vkAllocateDescriptorSets would cause the total number of 1948descriptor sets allocated from the pool to exceed the value of 1949slink:VkDescriptorPoolCreateInfo::pname:maxSets used to create 1950pname:pAllocateInfo->pname:descriptorPool, then the allocation may: fail due 1951to lack of space in the descriptor pool. 1952Similarly, the allocation may: fail due to lack of space if the call to 1953fname:vkAllocateDescriptorSets would cause the number of any given 1954descriptor type to exceed the sum of all the pname:descriptorCount members 1955of each element of slink:VkDescriptorPoolCreateInfo::pname:pPoolSizes with a 1956pname:member equal to that type. 1957If the allocation fails due to no more space in the descriptor pool, and not 1958because of system or device memory exhaustion, then 1959ename:VK_ERROR_OUT_OF_POOL_MEMORY must: be returned. 1960endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1961 1962ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1963If an allocation fails due to fragmentation, an indeterminate error is 1964returned with an unspecified error code. 1965Any returned error other than 1966ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1967ename:VK_ERROR_OUT_OF_POOL_MEMORY or 1968endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1969ename:VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: 1970applications should: assume that the allocation failed due to fragmentation, 1971and create a new descriptor pool. 1972endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 1973 1974ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1975fname:vkAllocateDescriptorSets can: be used to create multiple descriptor 1976sets. 1977If the creation of any of those descriptor sets fails, then the 1978implementation must: destroy all successfully created descriptor set objects 1979from this command, set all entries of the pname:pDescriptorSets array to 1980dlink:VK_NULL_HANDLE and return the error. 1981endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1982 1983ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] 1984[NOTE] 1985.Note 1986==== 1987Applications should: check for a negative return value when allocating new 1988descriptor sets, assume that any error 1989ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 1990other than ename:VK_ERROR_OUT_OF_POOL_MEMORY 1991endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 1992effectively means ename:VK_ERROR_FRAGMENTED_POOL, and try to create a new 1993descriptor pool. 1994If ename:VK_ERROR_FRAGMENTED_POOL is the actual return value, it adds 1995certainty to that decision. 1996 1997The reason for this is that ename:VK_ERROR_FRAGMENTED_POOL was only added in 1998a later revision of the 1.0 specification, and so drivers may: return other 1999errors if they were written against earlier revisions. 2000To ensure full compatibility with earlier patch revisions, these other 2001errors are allowed. 2002==== 2003endif::VK_VERSION_1_1,VK_KHR_maintenance2[] 2004 2005include::../validity/protos/vkAllocateDescriptorSets.txt[] 2006-- 2007 2008[open,refpage='VkDescriptorSetAllocateInfo',desc='Structure specifying the allocation parameters for descriptor sets',type='structs'] 2009-- 2010 2011The sname:VkDescriptorSetAllocateInfo structure is defined as: 2012 2013include::../api/structs/VkDescriptorSetAllocateInfo.txt[] 2014 2015 * pname:sType is the type of this structure. 2016 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2017 * pname:descriptorPool is the pool which the sets will be allocated from. 2018 * pname:descriptorSetCount determines the number of descriptor sets to be 2019 allocated from the pool. 2020 * pname:pSetLayouts is an array of descriptor set layouts, with each 2021 member specifying how the corresponding descriptor set is allocated. 2022 2023.Valid Usage 2024**** 2025ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2026 * [[VUID-VkDescriptorSetAllocateInfo-descriptorSetCount-00306]] 2027 pname:descriptorSetCount must: not be greater than the number of sets 2028 that are currently available for allocation in pname:descriptorPool 2029 * [[VUID-VkDescriptorSetAllocateInfo-descriptorPool-00307]] 2030 pname:descriptorPool must: have enough free descriptor capacity 2031 remaining to allocate the descriptor sets of the specified layouts 2032endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2033ifdef::VK_KHR_push_descriptor[] 2034 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-00308]] 2035 Each element of pname:pSetLayouts must: not have been created with 2036 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set 2037endif::VK_KHR_push_descriptor[] 2038ifdef::VK_EXT_descriptor_indexing[] 2039 * [[VUID-VkDescriptorSetAllocateInfo-pSetLayouts-03044]] 2040 If any element of pname:pSetLayouts was created with the 2041 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit 2042 set, pname:descriptorPool must: have been created with the 2043 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set 2044endif::VK_EXT_descriptor_indexing[] 2045**** 2046 2047include::../validity/structs/VkDescriptorSetAllocateInfo.txt[] 2048-- 2049 2050ifdef::VK_EXT_descriptor_indexing[] 2051[open,refpage='VkDescriptorSetVariableDescriptorCountAllocateInfoEXT',desc='Structure specifying additional allocation parameters for descriptor sets',type='structs'] 2052-- 2053 2054If the pname:pNext chain of a slink:VkDescriptorSetAllocateInfo structure 2055includes a sname:VkDescriptorSetVariableDescriptorCountAllocateInfoEXT 2056structure, then that structure includes an array of descriptor counts for 2057variable descriptor count bindings, one for each descriptor set being 2058allocated. 2059 2060The sname:VkDescriptorSetVariableDescriptorCountAllocateInfoEXT structure is 2061defined as: 2062 2063include::../api/structs/VkDescriptorSetVariableDescriptorCountAllocateInfoEXT.txt[] 2064 2065 * pname:sType is the type of this structure. 2066 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2067 * pname:descriptorSetCount is zero or the number of elements in 2068 pname:pDescriptorCounts. 2069 * pname:pDescriptorCounts is an array of descriptor counts, with each 2070 member specifying the number of descriptors in a variable descriptor 2071 count binding in the corresponding descriptor set being allocated. 2072 2073If pname:descriptorSetCount is zero or this structure is not included in the 2074pname:pNext chain, then the variable lengths are considered to be zero. 2075Otherwise, pname:pDescriptorCounts[i] is the number of descriptors in the 2076variable count descriptor binding in the corresponding descriptor set 2077layout. 2078If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] does not include 2079a variable count descriptor binding, then pname:pDescriptorCounts[i] is 2080ignored. 2081 2082.Valid Usage 2083**** 2084 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfoEXT-descriptorSetCount-03045]] 2085 If pname:descriptorSetCount is not zero, pname:descriptorSetCount must: 2086 equal slink:VkDescriptorSetAllocateInfo::pname:descriptorSetCount 2087 * [[VUID-VkDescriptorSetVariableDescriptorCountAllocateInfoEXT-pSetLayouts-03046]] 2088 If slink:VkDescriptorSetAllocateInfo::pname:pSetLayouts[i] has a 2089 variable descriptor count binding, then pname:pDescriptorCounts[i] must: 2090 be less than or equal to the descriptor count specified for that binding 2091 when the descriptor set layout was created. 2092**** 2093 2094include::../validity/structs/VkDescriptorSetVariableDescriptorCountAllocateInfoEXT.txt[] 2095-- 2096endif::VK_EXT_descriptor_indexing[] 2097 2098[open,refpage='vkFreeDescriptorSets',desc='Free one or more descriptor sets',type='protos'] 2099-- 2100 2101To free allocated descriptor sets, call: 2102 2103include::../api/protos/vkFreeDescriptorSets.txt[] 2104 2105 * pname:device is the logical device that owns the descriptor pool. 2106 * pname:descriptorPool is the descriptor pool from which the descriptor 2107 sets were allocated. 2108 * pname:descriptorSetCount is the number of elements in the 2109 pname:pDescriptorSets array. 2110 * pname:pDescriptorSets is an array of handles to slink:VkDescriptorSet 2111 objects. 2112 2113After a successful call to fname:vkFreeDescriptorSets, all descriptor sets 2114in pname:pDescriptorSets are invalid. 2115 2116.Valid Usage 2117**** 2118 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00309]] 2119 All submitted commands that refer to any element of 2120 pname:pDescriptorSets must: have completed execution 2121 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00310]] 2122 pname:pDescriptorSets must: be a valid pointer to an array of 2123 pname:descriptorSetCount sname:VkDescriptorSet handles, each element of 2124 which must: either be a valid handle or dlink:VK_NULL_HANDLE 2125 * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00311]] 2126 Each valid handle in pname:pDescriptorSets must: have been allocated 2127 from pname:descriptorPool 2128 * [[VUID-vkFreeDescriptorSets-descriptorPool-00312]] 2129 pname:descriptorPool must: have been created with the 2130 ename:VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT flag 2131**** 2132 2133include::../validity/protos/vkFreeDescriptorSets.txt[] 2134-- 2135 2136[open,refpage='vkResetDescriptorPool',desc='Resets a descriptor pool object',type='protos'] 2137-- 2138 2139To return all descriptor sets allocated from a given pool to the pool, 2140rather than freeing individual descriptor sets, call: 2141 2142include::../api/protos/vkResetDescriptorPool.txt[] 2143 2144 * pname:device is the logical device that owns the descriptor pool. 2145 * pname:descriptorPool is the descriptor pool to be reset. 2146 * pname:flags is reserved for future use. 2147 2148Resetting a descriptor pool recycles all of the resources from all of the 2149descriptor sets allocated from the descriptor pool back to the descriptor 2150pool, and the descriptor sets are implicitly freed. 2151 2152.Valid Usage 2153**** 2154 * [[VUID-vkResetDescriptorPool-descriptorPool-00313]] 2155 All uses of pname:descriptorPool (via any allocated descriptor sets) 2156 must: have completed execution 2157**** 2158 2159include::../validity/protos/vkResetDescriptorPool.txt[] 2160-- 2161 2162[open,refpage='VkDescriptorPoolResetFlags',desc='Reserved for future use',type='enums'] 2163-- 2164include::../api/flags/VkDescriptorPoolResetFlags.txt[] 2165 2166sname:VkDescriptorPoolResetFlags is a bitmask type for setting a mask, but 2167is currently reserved for future use. 2168-- 2169 2170 2171[[descriptorsets-updates]] 2172=== Descriptor Set Updates 2173 2174[open,refpage='vkUpdateDescriptorSets',desc='Update the contents of a descriptor set object',type='protos'] 2175-- 2176 2177Once allocated, descriptor sets can: be updated with a combination of write 2178and copy operations. 2179To update descriptor sets, call: 2180 2181include::../api/protos/vkUpdateDescriptorSets.txt[] 2182 2183 * pname:device is the logical device that updates the descriptor sets. 2184 * pname:descriptorWriteCount is the number of elements in the 2185 pname:pDescriptorWrites array. 2186 * pname:pDescriptorWrites is a pointer to an array of 2187 slink:VkWriteDescriptorSet structures describing the descriptor sets to 2188 write to. 2189 * pname:descriptorCopyCount is the number of elements in the 2190 pname:pDescriptorCopies array. 2191 * pname:pDescriptorCopies is a pointer to an array of 2192 slink:VkCopyDescriptorSet structures describing the descriptor sets to 2193 copy between. 2194 2195The operations described by pname:pDescriptorWrites are performed first, 2196followed by the operations described by pname:pDescriptorCopies. 2197Within each array, the operations are performed in the order they appear in 2198the array. 2199 2200Each element in the pname:pDescriptorWrites array describes an operation 2201updating the descriptor set using descriptors for resources specified in the 2202structure. 2203 2204Each element in the pname:pDescriptorCopies array is a 2205slink:VkCopyDescriptorSet structure describing an operation copying 2206descriptors between sets. 2207 2208If the pname:dstSet member of any element of pname:pDescriptorWrites or 2209pname:pDescriptorCopies is bound, accessed, or modified by any command that 2210was recorded to a command buffer which is currently in the 2211<<commandbuffers-lifecycle, recording or executable state>>, 2212ifdef::VK_EXT_descriptor_indexing[] 2213and any of the descriptor bindings that are updated were not created with 2214the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT or 2215ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT bits set, 2216endif::VK_EXT_descriptor_indexing[] 2217that command buffer becomes <<commandbuffers-lifecycle, invalid>>. 2218 2219.Valid Usage 2220**** 2221ifndef::VK_EXT_descriptor_indexing[] 2222 * [[VUID-vkUpdateDescriptorSets-dstSet-00314]] 2223 The pname:dstSet member of each element of pname:pDescriptorWrites or 2224 pname:pDescriptorCopies must: not be used by any command that was 2225 recorded to a command buffer which is in the <<commandbuffers-lifecycle, 2226 pending state>>. 2227endif::VK_EXT_descriptor_indexing[] 2228ifdef::VK_EXT_descriptor_indexing[] 2229 * [[VUID-vkUpdateDescriptorSets-None-03047]] 2230 Descriptor bindings updated by this command which were created without 2231 the ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT or 2232 ename:VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT bits set 2233 must: not be used by any command that was recorded to a command buffer 2234 which is in the <<commandbuffers-lifecycle,pending state>>. 2235endif::VK_EXT_descriptor_indexing[] 2236**** 2237 2238include::../validity/protos/vkUpdateDescriptorSets.txt[] 2239-- 2240 2241[open,refpage='VkWriteDescriptorSet',desc='Structure specifying the parameters of a descriptor set write operation',type='structs'] 2242-- 2243 2244The sname:VkWriteDescriptorSet structure is defined as: 2245 2246include::../api/structs/VkWriteDescriptorSet.txt[] 2247 2248 * pname:sType is the type of this structure. 2249 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2250 * pname:dstSet is the destination descriptor set to update. 2251 * pname:dstBinding is the descriptor binding within that set. 2252 * pname:dstArrayElement is the starting element in that array. 2253 * pname:descriptorCount is the number of descriptors to update (the number 2254 of elements in pname:pImageInfo, pname:pBufferInfo, or 2255 pname:pTexelBufferView). 2256 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 2257 each descriptor in pname:pImageInfo, pname:pBufferInfo, or 2258 pname:pTexelBufferView, as described below. 2259 It must: be the same type as that specified in 2260 sname:VkDescriptorSetLayoutBinding for pname:dstSet at pname:dstBinding. 2261 The type of the descriptor also controls which array the descriptors are 2262 taken from. 2263 * pname:pImageInfo points to an array of slink:VkDescriptorImageInfo 2264 structures or is ignored, as described below. 2265 * pname:pBufferInfo points to an array of slink:VkDescriptorBufferInfo 2266 structures or is ignored, as described below. 2267 * pname:pTexelBufferView points to an array of slink:VkBufferView handles 2268 as described in the <<resources-buffer-views,Buffer Views>> section or 2269 is ignored, as described below. 2270 2271Only one of pname:pImageInfo, pname:pBufferInfo, or pname:pTexelBufferView 2272members is used according to the descriptor type specified in the 2273pname:descriptorType member of the containing sname:VkWriteDescriptorSet 2274structure, as specified below. 2275 2276[[descriptorsets-updates-consecutive, consecutive binding updates]] 2277If the pname:dstBinding has fewer than pname:descriptorCount array elements 2278remaining starting from pname:dstArrayElement, then the remainder will be 2279used to update the subsequent binding - [eq]#pname:dstBinding+1# starting at 2280array element zero. 2281If a binding has a pname:descriptorCount of zero, it is skipped. 2282This behavior applies recursively, with the update affecting consecutive 2283bindings as needed to update all pname:descriptorCount descriptors. 2284 2285.Valid Usage 2286**** 2287 * [[VUID-VkWriteDescriptorSet-dstBinding-00315]] 2288 pname:dstBinding must: be less than or equal to the maximum value of 2289 pname:binding of all slink:VkDescriptorSetLayoutBinding structures 2290 specified when pname:dstSet's descriptor set layout was created 2291 * [[VUID-VkWriteDescriptorSet-dstBinding-00316]] 2292 pname:dstBinding must: be a binding with a non-zero 2293 pname:descriptorCount 2294 * [[VUID-VkWriteDescriptorSet-descriptorCount-00317]] 2295 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 2296 structure, except those with a pname:descriptorCount of zero, must: have 2297 identical pname:descriptorType and pname:stageFlags. 2298 * [[VUID-VkWriteDescriptorSet-descriptorCount-00318]] 2299 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 2300 structure, except those with a pname:descriptorCount of zero, must: all 2301 either use immutable samplers or must: all not use immutable samplers. 2302 * [[VUID-VkWriteDescriptorSet-descriptorType-00319]] 2303 pname:descriptorType must: match the type of pname:dstBinding within 2304 pname:dstSet 2305 * [[VUID-VkWriteDescriptorSet-dstSet-00320]] 2306 pname:dstSet must: be a valid slink:VkDescriptorSet handle 2307 * [[VUID-VkWriteDescriptorSet-dstArrayElement-00321]] 2308 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 2309 than or equal to the number of array elements in the descriptor set 2310 binding specified by pname:dstBinding, and all applicable consecutive 2311 bindings, as described by <<descriptorsets-updates-consecutive>> 2312 * [[VUID-VkWriteDescriptorSet-descriptorType-00322]] 2313 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER, 2314 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 2315 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2316 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 2317 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, pname:pImageInfo must: be a 2318 valid pointer to an array of pname:descriptorCount valid 2319 sname:VkDescriptorImageInfo structures 2320 * [[VUID-VkWriteDescriptorSet-descriptorType-00323]] 2321 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER 2322 or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, pname:pTexelBufferView 2323 must: be a valid pointer to an array of pname:descriptorCount valid 2324 sname:VkBufferView handles 2325 * [[VUID-VkWriteDescriptorSet-descriptorType-00324]] 2326 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 2327 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 2328 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 2329 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, pname:pBufferInfo must: 2330 be a valid pointer to an array of pname:descriptorCount valid 2331 sname:VkDescriptorBufferInfo structures 2332 * [[VUID-VkWriteDescriptorSet-descriptorType-00325]] 2333 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or 2334 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 2335 not allocated with a layout that included immutable samplers for 2336 pname:dstBinding with pname:descriptorType, the pname:sampler member of 2337 each element of pname:pImageInfo must: be a valid sname:VkSampler object 2338 * [[VUID-VkWriteDescriptorSet-descriptorType-00326]] 2339 If pname:descriptorType is 2340 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 2341 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2342 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 2343 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView and 2344 pname:imageLayout members of each element of pname:pImageInfo must: be a 2345 valid sname:VkImageView and elink:VkImageLayout, respectively 2346ifdef::VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2347 * [[VUID-VkWriteDescriptorSet-descriptorType-01946]] 2348 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, then 2349 the pname:imageView member of each pname:pImageInfo element must: have 2350 been created without a sname:VkSamplerYcbcrConversionInfo structure in 2351 its pname:pNext chain 2352 * [[VUID-VkWriteDescriptorSet-descriptorType-01947]] 2353 If pname:descriptorType is 2354 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and if any element of 2355 pname:pImageInfo has a pname:imageView member that was created with a 2356 sname:VkSamplerYcbcrConversionInfo structure in its pname:pNext chain, 2357 then pname:dstSet must: have been allocated with a layout that included 2358 immutable samplers for pname:dstBinding 2359 * [[VUID-VkWriteDescriptorSet-descriptorType-01948]] 2360 If pname:descriptorType is 2361 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:dstSet was 2362 allocated with a layout that included immutable samplers for 2363 pname:dstBinding, then the pname:imageView member of each element of 2364 pname:pImageInfo which corresponds to an immutable sampler that enables 2365 <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> must: have 2366 been created with a sname:VkSamplerYcbcrConversionInfo structure in its 2367 pname:pNext chain with an _identically defined_ 2368 sname:VkSamplerYcbcrConversionInfo to the corresponding immutable 2369 sampler 2370endif::VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] 2371 * [[VUID-VkWriteDescriptorSet-descriptorType-01402]] 2372 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, for 2373 each descriptor that will be accessed via load or store operations the 2374 pname:imageLayout member for corresponding elements of pname:pImageInfo 2375 must: be ename:VK_IMAGE_LAYOUT_GENERAL 2376 * [[VUID-VkWriteDescriptorSet-descriptorType-00327]] 2377 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 2378 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:offset member 2379 of each element of pname:pBufferInfo must: be a multiple of 2380 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 2381 * [[VUID-VkWriteDescriptorSet-descriptorType-00328]] 2382 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 2383 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:offset member 2384 of each element of pname:pBufferInfo must: be a multiple of 2385 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 2386 * [[VUID-VkWriteDescriptorSet-descriptorType-00329]] 2387 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 2388 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, 2389 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, or 2390 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, and the pname:buffer 2391 member of any element of pname:pBufferInfo is the handle of a non-sparse 2392 buffer, then that buffer must: be bound completely and contiguously to a 2393 single sname:VkDeviceMemory object 2394 * [[VUID-VkWriteDescriptorSet-descriptorType-00330]] 2395 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 2396 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:buffer member 2397 of each element of pname:pBufferInfo must: have been created with 2398 ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT set 2399 * [[VUID-VkWriteDescriptorSet-descriptorType-00331]] 2400 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 2401 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:buffer member 2402 of each element of pname:pBufferInfo must: have been created with 2403 ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT set 2404 * [[VUID-VkWriteDescriptorSet-descriptorType-00332]] 2405 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or 2406 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the pname:range member 2407 of each element of pname:pBufferInfo, or the effective range if 2408 pname:range is ename:VK_WHOLE_SIZE, must: be less than or equal to 2409 sname:VkPhysicalDeviceLimits::pname:maxUniformBufferRange 2410 * [[VUID-VkWriteDescriptorSet-descriptorType-00333]] 2411 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or 2412 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:range member 2413 of each element of pname:pBufferInfo, or the effective range if 2414 pname:range is ename:VK_WHOLE_SIZE, must: be less than or equal to 2415 sname:VkPhysicalDeviceLimits::pname:maxStorageBufferRange 2416 * [[VUID-VkWriteDescriptorSet-descriptorType-00334]] 2417 If pname:descriptorType is 2418 ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, the sname:VkBuffer that 2419 each element of pname:pTexelBufferView was created from must: have been 2420 created with ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT set 2421 * [[VUID-VkWriteDescriptorSet-descriptorType-00335]] 2422 If pname:descriptorType is 2423 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the sname:VkBuffer that 2424 each element of pname:pTexelBufferView was created from must: have been 2425 created with ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT set 2426 * [[VUID-VkWriteDescriptorSet-descriptorType-00336]] 2427 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE or 2428 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the pname:imageView member of 2429 each element of pname:pImageInfo must: have been created with the 2430 identity swizzle 2431 * [[VUID-VkWriteDescriptorSet-descriptorType-00337]] 2432 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 2433 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageView 2434 member of each element of pname:pImageInfo must: have been created with 2435 ename:VK_IMAGE_USAGE_SAMPLED_BIT set 2436 * [[VUID-VkWriteDescriptorSet-descriptorType-01403]] 2437 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or 2438 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the pname:imageLayout 2439 member of each element of pname:pImageInfo must: be 2440 ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 2441 ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or 2442 ename:VK_IMAGE_LAYOUT_GENERAL 2443 * [[VUID-VkWriteDescriptorSet-descriptorType-00338]] 2444 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, 2445 the pname:imageView member of each element of pname:pImageInfo must: 2446 have been created with ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set 2447 * [[VUID-VkWriteDescriptorSet-descriptorType-00339]] 2448 If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the 2449 pname:imageView member of each element of pname:pImageInfo must: have 2450 been created with ename:VK_IMAGE_USAGE_STORAGE_BIT set 2451ifdef::VK_EXT_descriptor_indexing[] 2452 * [[VUID-VkWriteDescriptorSet-descriptorCount-03048]] 2453 All consecutive bindings updated via a single sname:VkWriteDescriptorSet 2454 structure, except those with a pname:descriptorCount of zero, must: have 2455 identical elink:VkDescriptorBindingFlagBitsEXT. 2456endif::VK_EXT_descriptor_indexing[] 2457**** 2458 2459include::../validity/structs/VkWriteDescriptorSet.txt[] 2460-- 2461 2462[open,refpage='VkDescriptorType',desc='Specifies the type of a descriptor in a descriptor set',type='enums'] 2463-- 2464 2465The type of descriptors in a descriptor set is specified by 2466slink:VkWriteDescriptorSet::pname:descriptorType, which must: be one of the 2467values: 2468 2469include::../api/enums/VkDescriptorType.txt[] 2470 2471 * ename:VK_DESCRIPTOR_TYPE_SAMPLER specifies a <<descriptorsets-sampler, 2472 sampler descriptor>>. 2473 * ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER specifies a 2474 <<descriptorsets-combinedimagesampler, combined image sampler 2475 descriptor>>. 2476 * ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE specifies a 2477 <<descriptorsets-sampledimage, sampled image descriptor>>. 2478 * ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE specifies a 2479 <<descriptorsets-storageimage, storage image descriptor>>. 2480 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER specifies a 2481 <<descriptorsets-uniformtexelbuffer, uniform texel buffer descriptor>>. 2482 * ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER specifies a 2483 <<descriptorsets-storagetexelbuffer, storage texel buffer descriptor>>. 2484 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER specifies a 2485 <<descriptorsets-uniformbuffer, uniform buffer descriptor>>. 2486 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER specifies a 2487 <<descriptorsets-storagebuffer, storage buffer descriptor>>. 2488 * ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC specifies a 2489 <<descriptorsets-uniformbufferdynamic, dynamic uniform buffer 2490 descriptor>>. 2491 * ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC specifies a 2492 <<descriptorsets-storagebufferdynamic, dynamic storage buffer 2493 descriptor>>. 2494 * ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT specifies a 2495 <<descriptorsets-inputattachment, input attachment descriptor>>. 2496 2497When a descriptor set is updated via elements of slink:VkWriteDescriptorSet, 2498members of pname:pImageInfo, pname:pBufferInfo and pname:pTexelBufferView 2499are only accessed by the implementation when they correspond to descriptor 2500type being defined - otherwise they are ignored. 2501The members accessed are as follows for each descriptor type: 2502 2503 * For ename:VK_DESCRIPTOR_TYPE_SAMPLER, only the pname:sample member of 2504 each element of slink:VkWriteDescriptorSet::pname:pImageInfo is 2505 accessed. 2506 * For ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2507 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or 2508 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only the pname:imageView and 2509 pname:imageLayout members of each element of 2510 slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 2511 * For ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each 2512 element of slink:VkWriteDescriptorSet::pname:pImageInfo are accessed. 2513 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 2514 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, 2515 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or 2516 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each 2517 element of slink:VkWriteDescriptorSet::pname:pBufferInfo are accessed. 2518 * For ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or 2519 ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of 2520 slink:VkWriteDescriptorSet::pname:pTexelBufferView is accessed. 2521-- 2522 2523[open,refpage='VkDescriptorBufferInfo',desc='Structure specifying descriptor buffer info',type='structs'] 2524-- 2525 2526The sname:VkDescriptorBufferInfo structure is defined as: 2527 2528include::../api/structs/VkDescriptorBufferInfo.txt[] 2529 2530 * pname:buffer is the buffer resource. 2531 * pname:offset is the offset in bytes from the start of pname:buffer. 2532 Access to buffer memory via this descriptor uses addressing that is 2533 relative to this starting offset. 2534 * pname:range is the size in bytes that is used for this descriptor 2535 update, or ename:VK_WHOLE_SIZE to use the range from pname:offset to the 2536 end of the buffer. 2537 2538[NOTE] 2539.Note 2540==== 2541When setting pname:range to ename:VK_WHOLE_SIZE, the effective range must: 2542not be larger than the maximum range for the descriptor type 2543(<<features-limits-maxUniformBufferRange, maxUniformBufferRange>> or 2544<<features-limits-maxStorageBufferRange, maxStorageBufferRange>>). 2545This means that ename:VK_WHOLE_SIZE is not typically useful in the common 2546case where uniform buffer descriptors are suballocated from a buffer that is 2547much larger than pname:maxUniformBufferRange. 2548==== 2549 2550For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and 2551ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, 2552pname:offset is the base offset from which the dynamic offset is applied and 2553pname:range is the static size used for all dynamic offsets. 2554 2555.Valid Usage 2556**** 2557 * [[VUID-VkDescriptorBufferInfo-offset-00340]] 2558 pname:offset must: be less than the size of pname:buffer 2559 * [[VUID-VkDescriptorBufferInfo-range-00341]] 2560 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 2561 greater than `0` 2562 * [[VUID-VkDescriptorBufferInfo-range-00342]] 2563 If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be 2564 less than or equal to the size of pname:buffer minus pname:offset 2565**** 2566 2567include::../validity/structs/VkDescriptorBufferInfo.txt[] 2568-- 2569 2570[open,refpage='VkDescriptorImageInfo',desc='Structure specifying descriptor image info',type='structs'] 2571-- 2572 2573The sname:VkDescriptorImageInfo structure is defined as: 2574 2575include::../api/structs/VkDescriptorImageInfo.txt[] 2576 2577 * pname:sampler is a sampler handle, and is used in descriptor updates for 2578 types ename:VK_DESCRIPTOR_TYPE_SAMPLER and 2579 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER if the binding being 2580 updated does not use immutable samplers. 2581 * pname:imageView is an image view handle, and is used in descriptor 2582 updates for types ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2583 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 2584 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 2585 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 2586 * pname:imageLayout is the layout that the image subresources accessible 2587 from pname:imageView will be in at the time this descriptor is accessed. 2588 pname:imageLayout is used in descriptor updates for types 2589 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, 2590 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, 2591 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 2592 ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. 2593 2594Members of sname:VkDescriptorImageInfo that are not used in an update (as 2595described above) are ignored. 2596 2597.Valid Usage 2598**** 2599ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] 2600 * [[VUID-VkDescriptorImageInfo-imageView-00343]] 2601 pname:imageView must: not be 2D or 2D array image view created from a 3D 2602 image 2603endif::VK_VERSION_1_1,VK_KHR_maintenance1[] 2604 * [[VUID-VkDescriptorImageInfo-imageView-01976]] 2605 If pname:imageView is created from a depth/stencil image, the 2606 pname:aspectMask used to create the pname:imageView must: include either 2607 ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT but 2608 not both. 2609 * [[VUID-VkDescriptorImageInfo-imageLayout-00344]] 2610 pname:imageLayout must: match the actual elink:VkImageLayout of each 2611 subresource accessible from pname:imageView at the time this descriptor 2612 is accessed as defined by the <<resources-image-layouts-matching-rule, 2613 image layout matching rules>> 2614ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2615 * [[VUID-VkDescriptorImageInfo-sampler-01564]] 2616 If pname:sampler is used and the elink:VkFormat of the image is a 2617 <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar 2618 format>>, the image must: have been created with 2619 ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the pname:aspectMask of 2620 the pname:imageView must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, 2621 ename:VK_IMAGE_ASPECT_PLANE_1_BIT or (for three-plane formats only) 2622 ename:VK_IMAGE_ASPECT_PLANE_2_BIT 2623endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 2624**** 2625 2626 2627include::../validity/structs/VkDescriptorImageInfo.txt[] 2628-- 2629 2630[open,refpage='VkCopyDescriptorSet',desc='Structure specifying a copy descriptor set operation',type='structs'] 2631-- 2632 2633The sname:VkCopyDescriptorSet structure is defined as: 2634 2635include::../api/structs/VkCopyDescriptorSet.txt[] 2636 2637 * pname:sType is the type of this structure. 2638 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2639 * pname:srcSet, pname:srcBinding, and pname:srcArrayElement are the source 2640 set, binding, and array element, respectively. 2641 * pname:dstSet, pname:dstBinding, and pname:dstArrayElement are the 2642 destination set, binding, and array element, respectively. 2643 * pname:descriptorCount is the number of descriptors to copy from the 2644 source to destination. 2645 If pname:descriptorCount is greater than the number of remaining array 2646 elements in the source or destination binding, those affect consecutive 2647 bindings in a manner similar to slink:VkWriteDescriptorSet above. 2648 2649.Valid Usage 2650**** 2651 * [[VUID-VkCopyDescriptorSet-srcBinding-00345]] 2652 pname:srcBinding must: be a valid binding within pname:srcSet 2653 * [[VUID-VkCopyDescriptorSet-srcArrayElement-00346]] 2654 The sum of pname:srcArrayElement and pname:descriptorCount must: be less 2655 than or equal to the number of array elements in the descriptor set 2656 binding specified by pname:srcBinding, and all applicable consecutive 2657 bindings, as described by <<descriptorsets-updates-consecutive>> 2658 * [[VUID-VkCopyDescriptorSet-dstBinding-00347]] 2659 pname:dstBinding must: be a valid binding within pname:dstSet 2660 * [[VUID-VkCopyDescriptorSet-dstArrayElement-00348]] 2661 The sum of pname:dstArrayElement and pname:descriptorCount must: be less 2662 than or equal to the number of array elements in the descriptor set 2663 binding specified by pname:dstBinding, and all applicable consecutive 2664 bindings, as described by <<descriptorsets-updates-consecutive>> 2665 * [[VUID-VkCopyDescriptorSet-srcSet-00349]] 2666 If pname:srcSet is equal to pname:dstSet, then the source and 2667 destination ranges of descriptors must: not overlap, where the ranges 2668 may: include array elements from consecutive bindings as described by 2669 <<descriptorsets-updates-consecutive>> 2670ifdef::VK_EXT_descriptor_indexing[] 2671 * [[VUID-VkCopyDescriptorSet-srcSet-01918]] 2672 If pname:srcSet's layout was created with the 2673 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 2674 flag set, then pname:dstSet's layout must: also have been created with 2675 the ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 2676 flag set 2677 * [[VUID-VkCopyDescriptorSet-srcSet-01919]] 2678 If pname:srcSet's layout was created without the 2679 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 2680 flag set, then pname:dstSet's layout must: also have been created 2681 without the 2682 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT 2683 flag set 2684 * [[VUID-VkCopyDescriptorSet-srcSet-01920]] 2685 If the descriptor pool from which pname:srcSet was allocated was created 2686 with the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag 2687 set, then the descriptor pool from which pname:dstSet was allocated 2688 must: also have been created with the 2689 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set 2690 * [[VUID-VkCopyDescriptorSet-srcSet-01921]] 2691 If the descriptor pool from which pname:srcSet was allocated was created 2692 without the ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT 2693 flag set, then the descriptor pool from which pname:dstSet was allocated 2694 must: also have been created without the 2695 ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set 2696endif::VK_EXT_descriptor_indexing[] 2697**** 2698 2699include::../validity/structs/VkCopyDescriptorSet.txt[] 2700-- 2701 2702 2703ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 2704[[descriptorsets-updates-with-template]] 2705=== Descriptor Update Templates 2706 2707[open,refpage='VkDescriptorUpdateTemplate',desc='Opaque handle to a descriptor update template',type='handles'] 2708-- 2709 2710A descriptor update template specifies a mapping from descriptor update 2711information in host memory to descriptors in a descriptor set. 2712It is designed to avoid passing redundant information to the driver when 2713frequently updating the same set of descriptors in descriptor sets. 2714 2715Descriptor update template objects are represented by 2716sname:VkDescriptorUpdateTemplate handles: 2717 2718include::../api/handles/VkDescriptorUpdateTemplate.txt[] 2719 2720ifdef::VK_KHR_descriptor_update_template[] 2721or the equivalent 2722 2723include::../api/handles/VkDescriptorUpdateTemplateKHR.txt[] 2724endif::VK_KHR_descriptor_update_template[] 2725 2726-- 2727 2728=== Descriptor Set Updates with Templates 2729 2730[open,refpage='vkCreateDescriptorUpdateTemplate',desc='Create a new descriptor update template',type='protos'] 2731-- 2732 2733Updating a large sname:VkDescriptorSet array can: be an expensive operation 2734since an application must: specify one slink:VkWriteDescriptorSet structure 2735for each descriptor or descriptor array to update, each of which 2736re-specifies the same state when updating the same descriptor in multiple 2737descriptor sets. 2738For cases when an application wishes to update the same set of descriptors 2739in multiple descriptor sets allocated using the same 2740sname:VkDescriptorSetLayout, flink:vkUpdateDescriptorSetWithTemplate can: be 2741used as a replacement for flink:vkUpdateDescriptorSets. 2742 2743sname:VkDescriptorUpdateTemplate allows implementations to convert a set of 2744descriptor update operations on a single descriptor set to an internal 2745format that, in conjunction with flink:vkUpdateDescriptorSetWithTemplate 2746ifdef::VK_KHR_push_descriptor[] 2747or flink:vkCmdPushDescriptorSetWithTemplateKHR 2748endif::VK_KHR_push_descriptor[] 2749, can: be more efficient compared to calling flink:vkUpdateDescriptorSets 2750ifdef::VK_KHR_push_descriptor[] 2751or flink:vkCmdPushDescriptorSetKHR 2752endif::VK_KHR_push_descriptor[] 2753. 2754The descriptors themselves are not specified in the 2755sname:VkDescriptorUpdateTemplate, rather, offsets into an application 2756provided pointer to host memory are specified, which are combined with a 2757pointer passed to flink:vkUpdateDescriptorSetWithTemplate 2758ifdef::VK_KHR_push_descriptor[] 2759or flink:vkCmdPushDescriptorSetWithTemplateKHR 2760endif::VK_KHR_push_descriptor[] 2761. 2762This allows large batches of updates to be executed without having to 2763convert application data structures into a strictly-defined Vulkan data 2764structure. 2765 2766To create a descriptor update template, call: 2767 2768ifdef::VK_VERSION_1_1[] 2769include::../api/protos/vkCreateDescriptorUpdateTemplate.txt[] 2770endif::VK_VERSION_1_1[] 2771 2772ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 2773 2774ifdef::VK_KHR_descriptor_update_template[] 2775include::../api/protos/vkCreateDescriptorUpdateTemplateKHR.txt[] 2776endif::VK_KHR_descriptor_update_template[] 2777 2778 * pname:device is the logical device that creates the descriptor update 2779 template. 2780 * pname:pCreateInfo is a pointer to an instance of the 2781 slink:VkDescriptorUpdateTemplateCreateInfo structure specifying the set 2782 of descriptors to update with a single call to 2783ifdef::VK_KHR_push_descriptor[] 2784 flink:vkCmdPushDescriptorSetWithTemplateKHR or 2785endif::VK_KHR_push_descriptor[] 2786 flink:vkUpdateDescriptorSetWithTemplate. 2787 * pname:pAllocator controls host memory allocation as described in the 2788 <<memory-allocation, Memory Allocation>> chapter. 2789 * pname:pDescriptorUpdateTemplate points to a 2790 sname:VkDescriptorUpdateTemplate handle in which the resulting 2791 descriptor update template object is returned. 2792 2793include::../validity/protos/vkCreateDescriptorUpdateTemplate.txt[] 2794 2795-- 2796 2797[open,refpage='VkDescriptorUpdateTemplateCreateInfo',desc='Structure specifying parameters of a newly created descriptor update template',type='structs'] 2798-- 2799 2800The slink:VkDescriptorUpdateTemplateCreateInfo structure is defined as: 2801include::../api/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 2802 2803ifdef::VK_KHR_descriptor_update_template[] 2804or the equivalent 2805 2806include::../api/structs/VkDescriptorUpdateTemplateCreateInfoKHR.txt[] 2807endif::VK_KHR_descriptor_update_template[] 2808 2809 * pname:sType is the type of this structure. 2810 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 2811 * pname:flags is reserved for future use. 2812 * pname:descriptorUpdateEntryCount is the number of elements in the 2813 pname:pDescriptorUpdateEntries array. 2814 * pname:pDescriptorUpdateEntries is a pointer to an array of 2815 slink:VkDescriptorUpdateTemplateEntry structures describing the 2816 descriptors to be updated by the descriptor update template. 2817 * pname:templateType Specifies the type of the descriptor update template. 2818 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET it 2819 can: only be used to update descriptor sets with a fixed 2820 pname:descriptorSetLayout. 2821ifdef::VK_KHR_push_descriptor[] 2822 If set to ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 2823 it can: only be used to push descriptor sets using the provided 2824 pname:pipelineBindPoint, pname:pipelineLayout, and pname:set number. 2825endif::VK_KHR_push_descriptor[] 2826 * pname:descriptorSetLayout is the descriptor set layout the parameter 2827 update template will be used with. 2828 All descriptor sets which are going to be updated through the newly 2829 created descriptor update template must: be created with this layout. 2830 pname:descriptorSetLayout is the descriptor set layout used to build the 2831 descriptor update template. 2832 All descriptor sets which are going to be updated through the newly 2833 created descriptor update template must: be created with a layout that 2834 matches (is the same as, or defined identically to) this layout. 2835 This parameter is ignored if pname:templateType is not 2836 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET. 2837ifdef::VK_KHR_push_descriptor[] 2838 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating 2839 whether the descriptors will be used by graphics pipelines or compute 2840 pipelines. 2841 This parameter is ignored if pname:templateType is not 2842 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 2843 * pname:pipelineLayout is a slink:VkPipelineLayout object used to program 2844 the bindings. 2845 This parameter is ignored if pname:templateType is not 2846 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 2847 * pname:set is the set number of the descriptor set in the pipeline layout 2848 that will be updated. 2849 This parameter is ignored if pname:templateType is not 2850 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR 2851endif::VK_KHR_push_descriptor[] 2852ifndef::VK_KHR_push_descriptor[] 2853 * pname:pipelineBindPoint is reserved for future use and is ignored 2854 * pname:pipelineLayout is reserved for future use and is ignored 2855 * pname:set is reserved for future use and is ignored 2856endif::VK_KHR_push_descriptor[] 2857 2858.Valid Usage 2859**** 2860 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00350]] 2861 If pname:templateType is 2862 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, 2863 pname:descriptorSetLayout must: be a valid sname:VkDescriptorSetLayout 2864 handle 2865ifdef::VK_KHR_push_descriptor[] 2866 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00351]] 2867 If pname:templateType is 2868 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 2869 pname:pipelineBindPoint must: be a valid elink:VkPipelineBindPoint value 2870 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00352]] 2871 If pname:templateType is 2872 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, 2873 pname:pipelineLayout must: be a valid sname:VkPipelineLayout handle 2874 * [[VUID-VkDescriptorUpdateTemplateCreateInfo-templateType-00353]] 2875 If pname:templateType is 2876 ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, pname:set 2877 must: be the unique set number in the pipeline layout that uses a 2878 descriptor set layout that was created with 2879 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 2880endif::VK_KHR_push_descriptor[] 2881**** 2882 2883 2884include::../validity/structs/VkDescriptorUpdateTemplateCreateInfo.txt[] 2885 2886-- 2887 2888[open,refpage='VkDescriptorUpdateTemplateCreateFlags',desc='Reserved for future use',type='enums'] 2889-- 2890include::../api/flags/VkDescriptorUpdateTemplateCreateFlags.txt[] 2891 2892ifdef::VK_KHR_descriptor_update_template[] 2893or the equivalent 2894 2895include::../api/flags/VkDescriptorUpdateTemplateCreateFlagsKHR.txt[] 2896endif::VK_KHR_descriptor_update_template[] 2897 2898sname:VkDescriptorUpdateTemplateCreateFlags is a bitmask type for setting a 2899mask, but is currently reserved for future use. 2900-- 2901 2902[open,refpage='VkDescriptorUpdateTemplateType',desc='Indicates the valid usage of the descriptor update template',type='enums'] 2903-- 2904The descriptor update template type is determined by the 2905slink:VkDescriptorUpdateTemplateCreateInfo::pname:templateType property, 2906which takes the following values: 2907 2908include::../api/enums/VkDescriptorUpdateTemplateType.txt[] 2909 2910ifdef::VK_KHR_descriptor_update_template[] 2911or the equivalent 2912 2913include::../api/enums/VkDescriptorUpdateTemplateTypeKHR.txt[] 2914endif::VK_KHR_descriptor_update_template[] 2915 2916 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET specifies that 2917 the descriptor update template will be used for descriptor set updates 2918 only. 2919ifdef::VK_KHR_push_descriptor[] 2920 * ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR specifies 2921 that the descriptor update template will be used for push descriptor 2922 updates only. 2923endif::VK_KHR_push_descriptor[] 2924 2925-- 2926 2927 2928[open,refpage='VkDescriptorUpdateTemplateEntry',desc='Describes a single descriptor update of the descriptor update template',type='structs'] 2929-- 2930 2931The sname:VkDescriptorUpdateTemplateEntry structure is defined as: 2932include::../api/structs/VkDescriptorUpdateTemplateEntry.txt[] 2933 2934ifdef::VK_KHR_descriptor_update_template[] 2935or the equivalent 2936 2937include::../api/structs/VkDescriptorUpdateTemplateEntryKHR.txt[] 2938endif::VK_KHR_descriptor_update_template[] 2939 2940 * pname:dstBinding is the descriptor binding to update when using this 2941 descriptor update template. 2942 * pname:dstArrayElement is the starting element in the array belonging to 2943 pname:dstBinding. 2944 * pname:descriptorCount is the number of descriptors to update. 2945 If pname:descriptorCount is greater than the number of remaining array 2946 elements in the destination binding, those affect consecutive bindings 2947 in a manner similar to slink:VkWriteDescriptorSet above. 2948 * pname:descriptorType is a elink:VkDescriptorType specifying the type of 2949 the descriptor. 2950 * pname:offset is the offset in bytes of the first binding in the raw data 2951 structure. 2952 * pname:stride is the stride in bytes between two consecutive array 2953 elements of the descriptor update informations in the raw data 2954 structure. 2955 The actual pointer ptr for each array element j of update entry i is 2956 computed using the following formula: 2957+ 2958[source,c++] 2959--------------------------------------------------- 2960 const char *ptr = (const char *)pData + pDescriptorUpdateEntries[i].offset + j * pDescriptorUpdateEntries[i].stride 2961--------------------------------------------------- 2962+ 2963The stride is useful in case the bindings are stored in structs along with 2964other data. 2965 2966.Valid Usage 2967**** 2968 * [[VUID-VkDescriptorUpdateTemplateEntry-dstBinding-00354]] 2969 pname:dstBinding must: be a valid binding in the descriptor set layout 2970 implicitly specified when using a descriptor update template to update 2971 descriptors. 2972 * [[VUID-VkDescriptorUpdateTemplateEntry-dstArrayElement-00355]] 2973 pname:dstArrayElement and pname:descriptorCount must: be less than or 2974 equal to the number of array elements in the descriptor set binding 2975 implicitly specified when using a descriptor update template to update 2976 descriptors, and all applicable consecutive bindings, as described by 2977 <<descriptorsets-updates-consecutive>> 2978**** 2979 2980include::../validity/structs/VkDescriptorUpdateTemplateEntry.txt[] 2981 2982-- 2983 2984[open,refpage='vkDestroyDescriptorUpdateTemplate',desc='Destroy a descriptor update template object',type='protos'] 2985-- 2986 2987To destroy a descriptor update template, call: 2988 2989ifdef::VK_VERSION_1_1[] 2990include::../api/protos/vkDestroyDescriptorUpdateTemplate.txt[] 2991endif::VK_VERSION_1_1[] 2992 2993ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 2994 2995ifdef::VK_KHR_descriptor_update_template[] 2996include::../api/protos/vkDestroyDescriptorUpdateTemplateKHR.txt[] 2997endif::VK_KHR_descriptor_update_template[] 2998 2999 * pname:device is the logical device that has been used to create the 3000 descriptor update template 3001 * pname:descriptorUpdateTemplate is the descriptor update template to 3002 destroy. 3003 * pname:pAllocator controls host memory allocation as described in the 3004 <<memory-allocation, Memory Allocation>> chapter. 3005 3006.Valid Usage 3007**** 3008 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00356]] 3009 If sname:VkAllocationCallbacks were provided when 3010 pname:descriptorSetLayout was created, a compatible set of callbacks 3011 must: be provided here 3012 * [[VUID-vkDestroyDescriptorUpdateTemplate-descriptorSetLayout-00357]] 3013 If no sname:VkAllocationCallbacks were provided when 3014 pname:descriptorSetLayout was created, pname:pAllocator must: be `NULL` 3015**** 3016 3017include::../validity/protos/vkDestroyDescriptorUpdateTemplate.txt[] 3018 3019-- 3020 3021[open,refpage='vkUpdateDescriptorSetWithTemplate',desc='Update the contents of a descriptor set object using an update template',type='protos'] 3022-- 3023 3024Once a sname:VkDescriptorUpdateTemplate has been created, descriptor sets 3025can: be updated by calling: 3026 3027ifdef::VK_VERSION_1_1[] 3028include::../api/protos/vkUpdateDescriptorSetWithTemplate.txt[] 3029endif::VK_VERSION_1_1[] 3030 3031ifdef::VK_VERSION_1_1+VK_KHR_descriptor_update_template[or the equivalent command] 3032 3033ifdef::VK_KHR_descriptor_update_template[] 3034include::../api/protos/vkUpdateDescriptorSetWithTemplateKHR.txt[] 3035endif::VK_KHR_descriptor_update_template[] 3036 3037 * pname:device is the logical device that updates the descriptor sets. 3038 * pname:descriptorSet is the descriptor set to update 3039 * pname:descriptorUpdateTemplate is the slink:VkDescriptorUpdateTemplate 3040 which specifies the update mapping between pname:pData and the 3041 descriptor set to update. 3042 * pname:pData is a pointer to memory which contains one or more structures 3043 of slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or 3044 slink:VkBufferView used to write the descriptors. 3045 3046.Valid Usage 3047**** 3048 * [[VUID-vkUpdateDescriptorSetWithTemplate-pData-01685]] 3049 pname:pData must: be a valid pointer to a memory that contains one or 3050 more valid instances of slink:VkDescriptorImageInfo, 3051 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 3052 by pname:descriptorUpdateTemplate when it was created with 3053 flink:vkCreateDescriptorUpdateTemplate 3054**** 3055 3056include::../validity/protos/vkUpdateDescriptorSetWithTemplate.txt[] 3057 3058.API example 3059[source,c++] 3060--------------------------------------------------- 3061 3062struct AppBufferView { 3063 VkBufferView bufferView; 3064 uint32_t applicationRelatedInformation; 3065}; 3066 3067struct AppDataStructure 3068{ 3069 VkDescriptorImageInfo imageInfo; // a single image info 3070 VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array 3071 AppBufferView bufferView[2]; // An application defined structure containing a bufferView 3072 // ... some more application related data 3073}; 3074 3075const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 3076{ 3077 // binding to a single image descriptor 3078 { 3079 0, // binding 3080 0, // dstArrayElement 3081 1, // descriptorCount 3082 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 3083 offsetof(AppDataStructure, imageInfo), // offset 3084 0 // stride is not required if descriptorCount is 1. 3085 }, 3086 3087 // binding to an array of buffer descriptors 3088 { 3089 0, // binding 3090 0, // dstArrayElement 3091 3, // descriptorCount 3092 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, // descriptorType 3093 offsetof(AppDataStructure, bufferInfoArray), // offset 3094 sizeof(VkDescriptorBufferInfo) // stride, descriptor buffer infos are compact 3095 }, 3096 3097 // binding to an array of buffer views 3098 { 3099 0, // binding 3100 3, // dstArrayElement 3101 1, // descriptorCount 3102 VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, // descriptorType 3103 offsetof(AppDataStructure, bufferView), // offset 3104 sizeof(AppBufferView) // stride, bufferViews do not have to be compact 3105 }, 3106}; 3107 3108// create a descriptor update template for descriptor set updates 3109const VkDescriptorUpdateTemplateCreateInfo createInfo = 3110{ 3111 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 3112 NULL, // pNext 3113 0, // flags 3114 3, // descriptorUpdateEntryCount 3115 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 3116 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET, // templateType 3117 myLayout, // descriptorSetLayout 3118 0, // pipelineBindPoint, ignored by given templateType 3119 0, // pipelineLayout, ignored by given templateType 3120 0, // set, ignored by given templateType 3121}; 3122 3123VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 3124myResult = vkCreateDescriptorUpdateTemplate( 3125 myDevice, 3126 &createInfo, 3127 NULL, 3128 &myDescriptorUpdateTemplate); 3129} 3130 3131 3132AppDataStructure appData; 3133 3134// fill appData here or cache it in your engine 3135vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData); 3136--------------------------------------------------- 3137 3138-- 3139 3140endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 3141 3142 3143[[descriptorsets-binding]] 3144=== Descriptor Set Binding 3145 3146[open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] 3147-- 3148 3149To bind one or more descriptor sets to a command buffer, call: 3150 3151include::../api/protos/vkCmdBindDescriptorSets.txt[] 3152 3153 * pname:commandBuffer is the command buffer that the descriptor sets will 3154 be bound to. 3155 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating 3156 whether the descriptors will be used by graphics pipelines or compute 3157 pipelines. 3158 There is a separate set of bind points for each of graphics and compute, 3159 so binding one does not disturb the other. 3160 * pname:layout is a slink:VkPipelineLayout object used to program the 3161 bindings. 3162 * pname:firstSet is the set number of the first descriptor set to be 3163 bound. 3164 * pname:descriptorSetCount is the number of elements in the 3165 pname:pDescriptorSets array. 3166 * pname:pDescriptorSets is an array of handles to slink:VkDescriptorSet 3167 objects describing the descriptor sets to write to. 3168 * pname:dynamicOffsetCount is the number of dynamic offsets in the 3169 pname:pDynamicOffsets array. 3170 * pname:pDynamicOffsets is a pointer to an array of code:uint32_t values 3171 specifying dynamic offsets. 3172 3173fname:vkCmdBindDescriptorSets causes the sets numbered [pname:firstSet.. 3174pname:firstSet+pname:descriptorSetCount-1] to use the bindings stored in 3175pname:pDescriptorSets[0..pname:descriptorSetCount-1] for subsequent 3176rendering commands (either compute or graphics, according to the 3177pname:pipelineBindPoint). 3178Any bindings that were previously applied via these sets are no longer 3179valid. 3180 3181Once bound, a descriptor set affects rendering of subsequent graphics or 3182compute commands in the command buffer until a different set is bound to the 3183same set number, or else until the set is disturbed as described in 3184<<descriptorsets-compatibility, Pipeline Layout Compatibility>>. 3185 3186A compatible descriptor set must: be bound for all set numbers that any 3187shaders in a pipeline access, at the time that a draw or dispatch command is 3188recorded to execute using that pipeline. 3189However, if none of the shaders in a pipeline statically use any bindings 3190with a particular set number, then no descriptor set need be bound for that 3191set number, even if the pipeline layout includes a non-trivial descriptor 3192set layout for that set number. 3193 3194[[descriptorsets-binding-dynamicoffsets]] 3195If any of the sets being bound include dynamic uniform or storage buffers, 3196then pname:pDynamicOffsets includes one element for each array element in 3197each dynamic descriptor type binding in each set. 3198Values are taken from pname:pDynamicOffsets in an order such that all 3199entries for set N come before set N+1; within a set, entries are ordered by 3200the binding numbers in the descriptor set layouts; and within a binding 3201array, elements are in order. 3202pname:dynamicOffsetCount must: equal the total number of dynamic descriptors 3203in the sets being bound. 3204 3205The effective offset used for dynamic uniform and storage buffer bindings is 3206the sum of the relative offset taken from pname:pDynamicOffsets, and the 3207base address of the buffer plus base offset in the descriptor set. 3208The range of the dynamic uniform and storage buffer bindings is the buffer 3209range as specified in the descriptor set. 3210 3211Each of the pname:pDescriptorSets must: be compatible with the pipeline 3212layout specified by pname:layout. 3213The layout used to program the bindings must: also be compatible with the 3214pipeline used in subsequent graphics or compute commands, as defined in the 3215<<descriptorsets-compatibility, Pipeline Layout Compatibility>> section. 3216 3217The descriptor set contents bound by a call to fname:vkCmdBindDescriptorSets 3218may: be consumed at the following times: 3219 3220ifdef::VK_EXT_descriptor_indexing[] 3221 * For descriptor bindings created with the 3222 ename:VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set, the 3223 contents may: be consumed when the command buffer is submitted to a 3224 queue, or during shader execution of the resulting draws and dispatches, 3225 or any time in between. 3226 Otherwise, 3227endif::VK_EXT_descriptor_indexing[] 3228 * during host execution of the command, or during shader execution of the 3229 resulting draws and dispatches, or any time in between. 3230 3231Thus, the contents of a descriptor set binding must: not be altered 3232(overwritten by an update command, or freed) between the first point in time 3233that it may: be consumed, and when the command completes executing on the 3234queue. 3235 3236The contents of pname:pDynamicOffsets are consumed immediately during 3237execution of fname:vkCmdBindDescriptorSets. 3238Once all pending uses have completed, it is legal to update and reuse a 3239descriptor set. 3240 3241.Valid Usage 3242**** 3243 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-00358]] 3244 Each element of pname:pDescriptorSets must: have been allocated with a 3245 sname:VkDescriptorSetLayout that matches (is the same as, or identically 3246 defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, 3247 where _n_ is the sum of pname:firstSet and the index into 3248 pname:pDescriptorSets 3249 * [[VUID-vkCmdBindDescriptorSets-dynamicOffsetCount-00359]] 3250 pname:dynamicOffsetCount must: be equal to the total number of dynamic 3251 descriptors in pname:pDescriptorSets 3252 * [[VUID-vkCmdBindDescriptorSets-firstSet-00360]] 3253 The sum of pname:firstSet and pname:descriptorSetCount must: be less 3254 than or equal to sname:VkPipelineLayoutCreateInfo::pname:setLayoutCount 3255 provided when pname:layout was created 3256 * [[VUID-vkCmdBindDescriptorSets-pipelineBindPoint-00361]] 3257 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 3258 parent sname:VkCommandPool's queue family 3259 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01971]] 3260 Each element of pname:pDynamicOffsets which corresponds to a descriptor 3261 binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: 3262 be a multiple of 3263 sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment 3264 * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01972]] 3265 Each element of pname:pDynamicOffsets which corresponds to a descriptor 3266 binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: 3267 be a multiple of 3268 sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment 3269 * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-01979]] 3270 For each dynamic uniform or storage buffer binding in 3271 pname:pDescriptorSets, the sum of the effective offset, as defined 3272 above, and the range of the binding must: be less than or equal to the 3273 size of the buffer 3274**** 3275 3276include::../validity/protos/vkCmdBindDescriptorSets.txt[] 3277-- 3278 3279 3280ifdef::VK_KHR_push_descriptor[] 3281[[descriptorsets-push-descriptors]] 3282=== Push Descriptor Updates 3283 3284[open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] 3285-- 3286 3287In addition to allocating descriptor sets and binding them to a command 3288buffer, an application can: record descriptor updates into the command 3289buffer. 3290 3291To push descriptor updates into a command buffer, call: 3292 3293include::../api/protos/vkCmdPushDescriptorSetKHR.txt[] 3294 3295 * pname:commandBuffer is the command buffer that the descriptors will be 3296 recorded in. 3297 * pname:pipelineBindPoint is a elink:VkPipelineBindPoint indicating 3298 whether the descriptors will be used by graphics pipelines or compute 3299 pipelines. 3300 There is a separate set of push descriptor bindings for each of graphics 3301 and compute, so binding one does not disturb the other. 3302 * pname:layout is a slink:VkPipelineLayout object used to program the 3303 bindings. 3304 * pname:set is the set number of the descriptor set in the pipeline layout 3305 that will be updated. 3306 * pname:descriptorWriteCount is the number of elements in the 3307 pname:pDescriptorWrites array. 3308 * pname:pDescriptorWrites is a pointer to an array of 3309 slink:VkWriteDescriptorSet structures describing the descriptors to be 3310 updated. 3311 3312_Push descriptors_ are a small bank of descriptors whose storage is 3313internally managed by the command buffer rather than being written into a 3314descriptor set and later bound to a command buffer. 3315Push descriptors allow for incremental updates of descriptors without 3316managing the lifetime of descriptor sets. 3317 3318When a command buffer begins recording, all push descriptors have undefined 3319contents. 3320Push descriptors can: be updated incrementally and cause shaders to use the 3321updated descriptors for subsequent rendering commands (either compute or 3322graphics, according to the pname:pipelineBindPoint) until the descriptor is 3323overwritten, or else until the set is disturbed as described in 3324<<descriptorsets-compatibility, Pipeline Layout Compatibility>>. 3325When the set is disturbed or push descriptors with a different descriptor 3326set layout are set, all push descriptors become invalid. 3327 3328Valid descriptors must: be pushed for all bindings that any shaders in a 3329pipeline access, at the time that a draw or dispatch command is recorded to 3330execute using that pipeline. 3331This includes immutable sampler descriptors, which must: be pushed before 3332they are accessed by a pipeline. 3333However, if none of the shaders in a pipeline statically use certain 3334bindings in the push descriptor set, then those descriptors need not be 3335valid. 3336 3337Push descriptors do not use dynamic offsets. 3338Instead, the corresponding non-dynamic descriptor types can: be used and the 3339pname:offset member of slink:VkDescriptorBufferInfo can: be changed each 3340time the descriptor is written. 3341 3342Each element of pname:pDescriptorWrites is interpreted as in 3343slink:VkWriteDescriptorSet, except the pname:dstSet member is ignored. 3344 3345To push an immutable sampler, use a slink:VkWriteDescriptorSet with 3346pname:dstBinding and pname:dstArrayElement selecting the immutable sampler's 3347binding. 3348If the descriptor type is ename:VK_DESCRIPTOR_TYPE_SAMPLER, the 3349pname:pImageInfo parameter is ignored and the immutable sampler is taken 3350from the push descriptor set layout in the pipeline layout. 3351If the descriptor type is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, 3352the pname:sampler member of the pname:pImageInfo parameter is ignored and 3353the immutable sampler is taken from the push descriptor set layout in the 3354pipeline layout. 3355 3356.Valid Usage 3357**** 3358 * [[VUID-vkCmdPushDescriptorSetKHR-pipelineBindPoint-00363]] 3359 pname:pipelineBindPoint must: be supported by the pname:commandBuffer's 3360 parent sname:VkCommandPool's queue family 3361 * [[VUID-vkCmdPushDescriptorSetKHR-set-00364]] 3362 pname:set must: be less than 3363 sname:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when 3364 pname:layout was created 3365 * [[VUID-vkCmdPushDescriptorSetKHR-set-00365]] 3366 pname:set must: be the unique set number in the pipeline layout that 3367 uses a descriptor set layout that was created with 3368 ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR 3369**** 3370 3371include::../validity/protos/vkCmdPushDescriptorSetKHR.txt[] 3372 3373-- 3374 3375ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 3376=== Push Descriptor Updates with Descriptor Update Templates 3377 3378[open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] 3379-- 3380 3381It is also possible to use a descriptor update template to specify the push 3382descriptors to update. 3383To do so, call: 3384 3385include::../api/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 3386 3387 * pname:commandBuffer is the command buffer that the descriptors will be 3388 recorded in. 3389 * pname:descriptorUpdateTemplate A descriptor update template which 3390 defines how to interpret the descriptor information in pData. 3391 * pname:layout is a slink:VkPipelineLayout object used to program the 3392 bindings. 3393 It must: be compatible with the layout used to create the 3394 pname:descriptorUpdateTemplate handle. 3395 * pname:set is the set number of the descriptor set in the pipeline layout 3396 that will be updated. 3397 This must: be the same number used to create the 3398 pname:descriptorUpdateTemplate handle. 3399 * pname:pData Points to memory which contains the descriptors for the 3400 templated update. 3401 3402.Valid Usage 3403**** 3404 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366]] 3405 The pipelineBindPoint specified during the creation of the descriptor 3406 update template must: be supported by the pname:commandBuffer's parent 3407 sname:VkCommandPool's queue family 3408 * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] 3409 pname:pData must: be a valid pointer to a memory that contains one or 3410 more valid instances of slink:VkDescriptorImageInfo, 3411 slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined 3412 by pname:descriptorUpdateTemplate when it was created with 3413 flink:vkCreateDescriptorUpdateTemplateKHR 3414**** 3415 3416include::../validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] 3417 3418.API example 3419[source,c++] 3420--------------------------------------------------- 3421 3422struct AppBufferView { 3423 VkBufferView bufferView; 3424 uint32_t applicationRelatedInformation; 3425}; 3426 3427struct AppDataStructure 3428{ 3429 VkDescriptorImageInfo imageInfo; // a single image info 3430 // ... some more application related data 3431}; 3432 3433const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] = 3434{ 3435 // binding to a single image descriptor 3436 { 3437 0, // binding 3438 0, // dstArrayElement 3439 1, // descriptorCount 3440 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, // descriptorType 3441 offsetof(AppDataStructure, imageInfo), // offset 3442 0 // stride is not required if descriptorCount is 1. 3443 } 3444 3445}; 3446 3447// create a descriptor update template for descriptor set updates 3448const VkDescriptorUpdateTemplateCreateInfo createInfo = 3449{ 3450 VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO, // sType 3451 NULL, // pNext 3452 0, // flags 3453 1, // descriptorUpdateEntryCount 3454 descriptorUpdateTemplateEntries, // pDescriptorUpdateEntries 3455 VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR, // templateType 3456 0, // descriptorSetLayout, ignored by given templateType 3457 VK_PIPELINE_BIND_POINT_GRAPHICS, // pipelineBindPoint 3458 myPipelineLayout, // pipelineLayout 3459 0, // set 3460}; 3461 3462VkDescriptorUpdateTemplate myDescriptorUpdateTemplate; 3463myResult = vkCreateDescriptorUpdateTemplate( 3464 myDevice, 3465 &createInfo, 3466 NULL, 3467 &myDescriptorUpdateTemplate); 3468} 3469 3470AppDataStructure appData; 3471// fill appData here or cache it in your engine 3472vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); 3473--------------------------------------------------- 3474 3475-- 3476endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 3477 3478endif::VK_KHR_push_descriptor[] 3479 3480 3481=== Push Constant Updates 3482 3483[[descriptorsets-push-constants]] 3484 3485As described above in section <<descriptorsets-pipelinelayout, Pipeline 3486Layouts>>, the pipeline layout defines shader push constants which are 3487updated via Vulkan commands rather than via writes to memory or copy 3488commands. 3489 3490[NOTE] 3491.Note 3492==== 3493Push constants represent a high speed path to modify constant data in 3494pipelines that is expected to outperform memory-backed resource updates. 3495==== 3496 3497The values of push constants are undefined at the start of a command buffer. 3498 3499[open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] 3500-- 3501 3502To update push constants, call: 3503 3504include::../api/protos/vkCmdPushConstants.txt[] 3505 3506 * pname:commandBuffer is the command buffer in which the push constant 3507 update will be recorded. 3508 * pname:layout is the pipeline layout used to program the push constant 3509 updates. 3510 * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying 3511 the shader stages that will use the push constants in the updated range. 3512 * pname:offset is the start offset of the push constant range to update, 3513 in units of bytes. 3514 * pname:size is the size of the push constant range to update, in units of 3515 bytes. 3516 * pname:pValues is an array of pname:size bytes containing the new push 3517 constant values. 3518 3519.Valid Usage 3520**** 3521 * [[VUID-vkCmdPushConstants-offset-01795]] 3522 For each byte in the range specified by pname:offset and pname:size and 3523 for each shader stage in pname:stageFlags, there must: be a push 3524 constant range in pname:layout that includes that byte and that stage 3525 * [[VUID-vkCmdPushConstants-offset-01796]] 3526 For each byte in the range specified by pname:offset and pname:size and 3527 for each push constant range that overlaps that byte, pname:stageFlags 3528 must: include all stages in that push constant range's 3529 slink:VkPushConstantRange::pname:stageFlags 3530 * [[VUID-vkCmdPushConstants-offset-00368]] 3531 pname:offset must: be a multiple of `4` 3532 * [[VUID-vkCmdPushConstants-size-00369]] 3533 pname:size must: be a multiple of `4` 3534 * [[VUID-vkCmdPushConstants-offset-00370]] 3535 pname:offset must: be less than 3536 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize 3537 * [[VUID-vkCmdPushConstants-size-00371]] 3538 pname:size must: be less than or equal to 3539 sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus 3540 pname:offset 3541**** 3542 3543include::../validity/protos/vkCmdPushConstants.txt[] 3544-- 3545