vkCmdPushDescriptorSetWithTemplateKHR(3)

# vkCmdPushDescriptorSetWithTemplateKHR(3) Manual Page

## Name

vkCmdPushDescriptorSetWithTemplateKHR - Pushes descriptor updates into a command buffer using a descriptor update template

Loading… please wait.

## C Specification

It is also possible to use a descriptor update template to specify the push descriptors to update. To do so, call:

    // Provided by VK_KHR_push_descriptor with VK_VERSION_1_1, VK_KHR_push_descriptor with VK_KHR_descriptor_update_template, VK_KHR_descriptor_update_template with VK_KHR_push_descriptor
    void vkCmdPushDescriptorSetWithTemplateKHR(
        VkCommandBuffer                             commandBuffer,
        VkDescriptorUpdateTemplate                  descriptorUpdateTemplate,
        VkPipelineLayout                            layout,
        uint32_t                                    set,
        const void*                                 pData);

## Parameters

- `commandBuffer` is the command buffer that the descriptors will be recorded in.

- `descriptorUpdateTemplate` is a descriptor update template defining how to interpret the descriptor information in `pData`.

- `layout` is a VkPipelineLayout object used to program the bindings. It must be compatible with the layout used to create the `descriptorUpdateTemplate` handle.

- `set` is the set number of the descriptor set in the pipeline layout that will be updated. This must be the same number used to create the `descriptorUpdateTemplate` handle.

- `pData` is a pointer to memory containing descriptors for the templated update.

## Description

Valid Usage

- The `pipelineBindPoint` specified during the creation of the descriptor update template must be supported by the `commandBuffer`’s parent `VkCommandPool`’s queue family

- `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 vkCreateDescriptorUpdateTemplateKHR

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

- `descriptorUpdateTemplate` must be a valid VkDescriptorUpdateTemplate handle

- `layout` must be a valid VkPipelineLayout handle

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support graphics, or compute operations

- Each of `commandBuffer`, `descriptorUpdateTemplate`, and `layout` must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Both | Graphics Compute |

API example

    struct AppDataStructure
    {
        VkDescriptorImageInfo  imageInfo;          // a single image info
        // ... 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
        }
    };

    // 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
        1,                                                         // descriptorUpdateEntryCount
        descriptorUpdateTemplateEntries,                           // pDescriptorUpdateEntries
        VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR,   // templateType
        0,                                                         // descriptorSetLayout, ignored by given templateType
        VK_PIPELINE_BIND_POINT_GRAPHICS,                           // pipelineBindPoint
        myPipelineLayout,                                          // pipelineLayout
        0,                                                         // set
    };

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

    AppDataStructure appData;
    // fill appData here or cache it in your engine
    vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData);

## See Also

VkCommandBuffer, VkDescriptorUpdateTemplate, VkPipelineLayout

## 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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0