VulkanHub
Function Prototype

vkCmdPushDescriptorSetWithTemplateKHR

Pushes descriptor updates into a command buffer using a descriptor update template
primary / secondary
both
graphics / compute
state

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

void vkCmdPushDescriptorSetWithTemplateKHR(
    VkCommandBuffer commandBuffer,
    VkDescriptorUpdateTemplate descriptorUpdateTemplate,
    VkPipelineLayout layout,
    uint32_t set,
    const void* pData);
  • 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.

Valid Usage

VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366

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

VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686

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-vkCmdPushDescriptorSetWithTemplateKHR-layout-07993

layout must be compatible with the layout used to create descriptorUpdateTemplate

VUID-vkCmdPushDescriptorSetWithTemplateKHR-descriptorUpdateTemplate-07994

descriptorUpdateTemplate must have been created with a templateType of VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR

VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07995

set must be the same value used to create descriptorUpdateTemplate

VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07304

set must be less than VkPipelineLayoutCreateInfo::setLayoutCount provided when layout was created

VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07305

set must be the unique set number in the pipeline layout that uses a descriptor set layout that was created with VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

Valid Usage (Implicit)

VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-parameter

commandBuffer must be a valid VkCommandBuffer handle

VUID-vkCmdPushDescriptorSetWithTemplateKHR-descriptorUpdateTemplate-parameter

descriptorUpdateTemplate must be a valid VkDescriptorUpdateTemplate handle

VUID-vkCmdPushDescriptorSetWithTemplateKHR-layout-parameter

layout must be a valid VkPipelineLayout handle

VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-recording

commandBuffer must be in the recording state

VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-cmdpool

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

VUID-vkCmdPushDescriptorSetWithTemplateKHR-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdPushDescriptorSetWithTemplateKHR-commonparent

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 ::

API example

struct AppDataStructure
{
    VkDescriptorImageInfo  imageInfo;          // a single image info
    // ... some more application-related data
};

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

// create a descriptor update template for push descriptor set updates
const VkDescriptorUpdateTemplateCreateInfo createInfo =
{
    .sType = VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO,
    .pNext = NULL,
    .flags = 0,
    .descriptorUpdateEntryCount = 1,
    .pDescriptorUpdateEntries = descriptorUpdateTemplateEntries,
    .templateType = VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR,
    .descriptorSetLayout = 0,   // ignored by given templateType
    .pipelineBindPoint = VK_PIPELINE_BIND_POINT_GRAPHICS,
    .pipelineLayout = myPipelineLayout,
    .set = 0,
};

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);