vkUpdateDescriptorSetWithTemplate(3)

# vkUpdateDescriptorSetWithTemplate(3) Manual Page

## Name

vkUpdateDescriptorSetWithTemplate - Update the contents of a descriptor set object using an update template

Loading… please wait.

## C Specification

Once a `VkDescriptorUpdateTemplate` has been created, descriptor sets can be updated by calling:

    // Provided by VK_VERSION_1_1
    void vkUpdateDescriptorSetWithTemplate(
        VkDevice                                    device,
        VkDescriptorSet                             descriptorSet,
        VkDescriptorUpdateTemplate                  descriptorUpdateTemplate,
        const void*                                 pData);

or the equivalent command

    // Provided by VK_KHR_descriptor_update_template
    void vkUpdateDescriptorSetWithTemplateKHR(
        VkDevice                                    device,
        VkDescriptorSet                             descriptorSet,
        VkDescriptorUpdateTemplate                  descriptorUpdateTemplate,
        const void*                                 pData);

## Parameters

- `device` is the logical device that updates the descriptor set.

- `descriptorSet` is the descriptor set to update

- `descriptorUpdateTemplate` is a VkDescriptorUpdateTemplate object specifying the update mapping between `pData` and the descriptor set to update.

- `pData` is a pointer to memory containing one or more VkDescriptorImageInfo, VkDescriptorBufferInfo, or VkBufferView structures or VkAccelerationStructureKHR or VkAccelerationStructureNV handles used to write the descriptors.

## Description

Valid Usage

- VUID-vkUpdateDescriptorSetWithTemplate-pData-01685
  `pData` must be a valid pointer to a memory containing one or more valid instances of VkDescriptorImageInfo, VkDescriptorBufferInfo, or VkBufferView in a layout defined by `descriptorUpdateTemplate` when it was created with vkCreateDescriptorUpdateTemplate

- VUID-vkUpdateDescriptorSetWithTemplate-descriptorSet-06995
  Host access to `descriptorSet` must be externally synchronized unless explicitly denoted otherwise for specific flags

Valid Usage (Implicit)

- VUID-vkUpdateDescriptorSetWithTemplate-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkUpdateDescriptorSetWithTemplate-descriptorSet-parameter
  `descriptorSet` must be a valid VkDescriptorSet handle

- VUID-vkUpdateDescriptorSetWithTemplate-descriptorUpdateTemplate-parameter
  `descriptorUpdateTemplate` must be a valid VkDescriptorUpdateTemplate handle

- VUID-vkUpdateDescriptorSetWithTemplate-descriptorUpdateTemplate-parent
  `descriptorUpdateTemplate` must have been created, allocated, or retrieved from `device`

API example

    struct AppBufferView {
        VkBufferView bufferView;
        uint32_t     applicationRelatedInformation;
    };

    struct AppDataStructure
    {
        VkDescriptorImageInfo  imageInfo;          // a single image info
        VkDescriptorBufferInfo bufferInfoArray[3]; // 3 buffer infos in an array
        AppBufferView          bufferView[2];      // An application defined structure containing a bufferView
        // ... some more application related data
    };

    const VkDescriptorUpdateTemplateEntry descriptorUpdateTemplateEntries[] =
    {
        // binding to a single image descriptor
        {
            0,                                           // binding
            0,                                           // dstArrayElement
            1,                                           // descriptorCount
            VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,   // descriptorType
            offsetof(AppDataStructure, imageInfo),       // offset
            0                                            // stride is not required if descriptorCount is 1
        },

        // binding to an array of buffer descriptors
        {
            1,                                           // binding
            0,                                           // dstArrayElement
            3,                                           // descriptorCount
            VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER,           // descriptorType
            offsetof(AppDataStructure, bufferInfoArray), // offset
            sizeof(VkDescriptorBufferInfo)               // stride, descriptor buffer infos are compact
        },

        // binding to an array of buffer views
        {
            2,                                           // binding
            0,                                           // dstArrayElement
            2,                                           // descriptorCount
            VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER,     // descriptorType
            offsetof(AppDataStructure, bufferView) +
              offsetof(AppBufferView, bufferView),       // offset
            sizeof(AppBufferView)                        // stride, bufferViews do not have to be compact
        },
    };

    // create a descriptor update template for descriptor set updates
    const VkDescriptorUpdateTemplateCreateInfo createInfo =
    {
        VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,  // sType
        NULL,                                                      // pNext
        0,                                                         // flags
        3,                                                         // descriptorUpdateEntryCount
        descriptorUpdateTemplateEntries,                           // pDescriptorUpdateEntries
        VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET,         // templateType
        myLayout,                                                  // descriptorSetLayout
        0,                                                         // pipelineBindPoint, ignored by given templateType
        0,                                                         // pipelineLayout, ignored by given templateType
        0,                                                         // set, ignored by given templateType
    };

    VkDescriptorUpdateTemplate myDescriptorUpdateTemplate;
    myResult = vkCreateDescriptorUpdateTemplate(
        myDevice,
        &createInfo,
        NULL,
        &myDescriptorUpdateTemplate);

    AppDataStructure appData;

    // fill appData here or cache it in your engine
    vkUpdateDescriptorSetWithTemplate(myDevice, myDescriptorSet, myDescriptorUpdateTemplate, &appData);

## See Also

VK_VERSION_1_1, VkDescriptorSet, VkDescriptorUpdateTemplate, VkDevice

## Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0