VKUPDATEDESCRIPTORSE(3)

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

C SPECIFICATION

    void vkUpdateDescriptorSets(
        VkDevice                                    device,
        uint32_t                                    descriptorWriteCount,
        const VkWriteDescriptorSet*                 pDescriptorWrites,
        uint32_t                                    descriptorCopyCount,
        const VkCopyDescriptorSet*                  pDescriptorCopies);

PARAMETERS

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

descriptorWriteCount
    Number of descriptor set write requests.

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

descriptorCopyCount
    Number of descriptor set copy requests.

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

DESCRIPTION

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 VkWriteDescriptorSet structure. The definition of this structure is:

    typedef struct VkWriteDescriptorSet {
        VkStructureType                  sType;
        const void*                      pNext;
        VkDescriptorSet                  dstSet;
        uint32_t                         dstBinding;
        uint32_t                         dstArrayElement;
        uint32_t                         descriptorCount;
        VkDescriptorType                 descriptorType;
        const VkDescriptorImageInfo*     pImageInfo;
        const VkDescriptorBufferInfo*    pBufferInfo;
        const VkBufferView*              pTexelBufferView;
    } VkWriteDescriptorSet;

Additionally, the structure contains a pointer to an array of 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, pTexelBufferInfo, which is an array of VkBufferView handles, and pImageInfo and pBufferInfo, which are arrays of VkDescriptorImageInfo and VkDescriptorBufferInfo structures, respectively. The definitions of these structures are as follows:

    typedef struct VkDescriptorImageInfo {
        VkSampler        sampler;
        VkImageView      imageView;
        VkImageLayout    imageLayout;
    } VkDescriptorImageInfo;

    typedef struct VkDescriptorBufferInfo {
        VkBuffer        buffer;
        VkDeviceSize    offset;
        VkDeviceSize    range;
    } VkDescriptorBufferInfo;

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

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

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

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

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

Within each element of the pImageInfo array, the sampler member is a handle to the sampler to bind and is used for descriptor types VK_DESCRIPTOR_TYPE_SAMPLER and VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER. The imageView is the image view handle used for descriptor updates of type VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT. The imageLayout member specifies the layout of the image and is used with descriptor types VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and 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 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 VkCopyDescriptorSet structure, the definition of which is:

    typedef struct VkCopyDescriptorSet {
        VkStructureType    sType;
        const void*        pNext;
        VkDescriptorSet    srcSet;
        uint32_t           srcBinding;
        uint32_t           srcArrayElement;
        VkDescriptorSet    dstSet;
        uint32_t           dstBinding;
        uint32_t           dstArrayElement;
        uint32_t           descriptorCount;
    } VkCopyDescriptorSet;

This structure specifies the source and destination descriptor sets of the copy operation in the srcSet and dstSet members, respectively. The srcBinding and srcArrayElement members of the structure specify the first entry in the source descriptor set that should be copied; the dstBinding and dstArrayElement members specify the first entry in the destination descriptor set where the source descriptors should be copied to, while the 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 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.

VALID USAGE

    • device must be a valid VkDevice handle

    • If descriptorWriteCount is not 0, pDescriptorWrites must be a pointer to an array of descriptorWriteCount valid VkWriteDescriptorSet structures

    • If descriptorCopyCount is not 0, pDescriptorCopies must be a pointer to an array of descriptorCopyCount valid VkCopyDescriptorSet structures

HOST SYNCHRONIZATION

    • Host access to pDescriptorWrites[].dstSet must be externally synchronized

    • Host access to pDescriptorCopies[].dstSet must be externally synchronized

SEE ALSO

VkWriteDescriptorSet, VkCopyDescriptorSet, VkDescriptorBufferInfo, VkDescriptorImageInfo

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.