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