Vulkan-Docs/doc/specs/vulkan/man/vkUpdateDescriptorSets.txt

vkUpdateDescriptorSets(3)
=========================

Name
----
vkUpdateDescriptorSets - Update the contents of a descriptor set object.

C Specification
---------------

include::../protos/vkUpdateDescriptorSets.txt[]

Parameters
----------

pname:device::
    A handle to the device on which to update descriptor sets.

pname:descriptorWriteCount::
    Number of descriptor set write requests.

pname:pDescriptorWrites::
    Pointer to an array of pname:descriptorWriteCount number of
    slink:VkWriteDescriptorSet structures each specifying the parameters of
    a descriptor write request to a descriptor set.

pname:descriptorCopyCount::
    Number of descriptor set copy requests.

pname:pDescriptorCopies::
    Pointer to an array of pname:descriptorCopyCount number of
    slink:VkCopyDescriptorSet structures each specifying the parameters of a
    descriptor copy request between two descriptor sets.

Description
-----------

fname:vkUpdateDescriptorSets allows performing one or more descriptor set
update operations.

There are two types of descriptor set update operations: descriptor write and descriptor copy requests.

Descriptor write requests allow writing descriptor data coming from buffer view, image view, and sampler objects
to a range of descriptors within a destination descriptor set. Each descriptor write request is described
by an instance of the sname:VkWriteDescriptorSet structure. The definition of this structure is:

include::../structs/VkWriteDescriptorSet.txt[]

Additionally, the structure contains a pointer to an array of pname:descriptorCount
data structures that specify the buffer view, image view, and/or sampler
objects from where the descriptor data is sourced. The information about each
of the descriptor updates is stored in up to three arrays, ptext:pTexelBufferInfo,
which is an array of stext:VkBufferView handles, and pname:pImageInfo and
pname:pBufferInfo, which are arrays of slink:VkDescriptorImageInfo and
slink:VkDescriptorBufferInfo structures, respectively. The definitions of these
structures are as follows:

include::../structs/VkDescriptorImageInfo.txt[]
include::../structs/VkDescriptorBufferInfo.txt[]

Which of the ptext:pImageInfo, ptext:pBufferInfo and ptext:pTexelBufferView arrays is used
is determined from the value of ptext:descriptorType, as follows:

If descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,
ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC,
then the entries in ptext:pBufferInfo are used to update the descriptors and ptext:pImageInfo and
ptext:pTexelBufferInfo parameters are ignored. For each entry of ptext:pBufferInfo, ptext:buffer
specifies the handle of the buffer to bind to the descriptor set, and ptext:offset and ptext:range
specify the starting offset and size of the range of the buffer to bind, respectively, in bytes.

For ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
descriptor types, ptext:offset is the base offset from which the dynamic offset is applied and ptext:range
is the static size used for all dynamic offsets.

If ptext:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or
ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, then the ptext:pTexelBufferView array are used to
update the descriptors, and the ptext:pImageInfo and ptext:pBufferInfo parameters are ignored.

If ptext:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER, ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or
ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the members in ptext:pImageInfo array are used to update the
descriptors and the ptext:pBufferInfo and ptext:pTexelBufferInfo members are ignored.

Within each element of the ptext:pImageInfo array, the ptext:sampler member is a handle to the
sampler to bind and is used for descriptor types ename:VK_DESCRIPTOR_TYPE_SAMPLER and
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER. The ptext:imageView is the image view handle
used for descriptor updates of type ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT.
The ptext:imageLayout member specifies the layout of the image and is used with descriptor types
ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,
ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT.

A single descriptor write request may only update a continuous range of descriptors of the same type
though that range may cross binding boundaries. See slink:VkWriteDescriptorSet for more information.

Descriptor copy requests allow copying a range of descriptors between a source and destination descriptor set.
Each descriptor copy request is described by an instance of the sname:VkCopyDescriptorSet structure, the definition
of which is:

include::../structs/VkCopyDescriptorSet.txt[]

This structure specifies the source and destination descriptor sets of the
copy operation in the pname:srcSet and pname:dstSet members, respectively.
The pname:srcBinding and pname:srcArrayElement members of the structure
specify the first entry in the source descriptor set that should be copied;
the pname:dstBinding and pname:dstArrayElement members specify the first
entry in the destination descriptor set where the source descriptors should
be copied to, while the pname:descriptorCount member specifies the number of
descriptors to copy. A single descriptor copy request may only copy between
two continuous ranges of descriptors of the same type though both the source
and desintation ranges may cross binding boundaries. See
slink:VkCopyDescriptorSet for more information.

Attempting to update the contents of a descriptor set that is used by any command buffer that is pending
execution may result in undefined behavior.

include::../validity/protos/vkUpdateDescriptorSets.txt[]

See Also
--------

slink:VkWriteDescriptorSet, slink:VkCopyDescriptorSet, slink:VkDescriptorBufferInfo, slink:VkDescriptorImageInfo

include::footer.txt[]