vkCreateDescriptorUpdateTemplate(3)

# vkCreateDescriptorUpdateTemplate(3) Manual Page

## Name

vkCreateDescriptorUpdateTemplate - Create a new descriptor update template

Loading… please wait.

## C Specification

Updating a large `VkDescriptorSet` array can be an expensive operation since an application must specify one VkWriteDescriptorSet structure for each descriptor or descriptor array to update, each of which re-specifies the same state when updating the same descriptor in multiple descriptor sets. For cases when an application wishes to update the same set of descriptors in multiple descriptor sets allocated using the same `VkDescriptorSetLayout`, vkUpdateDescriptorSetWithTemplate can be used as a replacement for vkUpdateDescriptorSets.

`VkDescriptorUpdateTemplate` allows implementations to convert a set of descriptor update operations on a single descriptor set to an internal format that, in conjunction with vkUpdateDescriptorSetWithTemplate or vkCmdPushDescriptorSetWithTemplateKHR , can be more efficient compared to calling vkUpdateDescriptorSets or vkCmdPushDescriptorSetKHR . The descriptors themselves are not specified in the `VkDescriptorUpdateTemplate`, rather, offsets into an application provided pointer to host memory are specified, which are combined with a pointer passed to vkUpdateDescriptorSetWithTemplate or vkCmdPushDescriptorSetWithTemplateKHR . This allows large batches of updates to be executed without having to convert application data structures into a strictly-defined Vulkan data structure.

To create a descriptor update template, call:

    // Provided by VK_VERSION_1_1
    VkResult vkCreateDescriptorUpdateTemplate(
        VkDevice                                    device,
        const VkDescriptorUpdateTemplateCreateInfo* pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkDescriptorUpdateTemplate*                 pDescriptorUpdateTemplate);

or the equivalent command

    // Provided by VK_KHR_descriptor_update_template
    VkResult vkCreateDescriptorUpdateTemplateKHR(
        VkDevice                                    device,
        const VkDescriptorUpdateTemplateCreateInfo* pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkDescriptorUpdateTemplate*                 pDescriptorUpdateTemplate);

## Parameters

- `device` is the logical device that creates the descriptor update template.

- `pCreateInfo` is a pointer to a VkDescriptorUpdateTemplateCreateInfo structure specifying the set of descriptors to update with a single call to vkCmdPushDescriptorSetWithTemplateKHR or vkUpdateDescriptorSetWithTemplate.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pDescriptorUpdateTemplate` is a pointer to a `VkDescriptorUpdateTemplate` handle in which the resulting descriptor update template object is returned.

## Description

Valid Usage (Implicit)

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

- VUID-vkCreateDescriptorUpdateTemplate-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkDescriptorUpdateTemplateCreateInfo structure

- VUID-vkCreateDescriptorUpdateTemplate-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateDescriptorUpdateTemplate-pDescriptorUpdateTemplate-parameter
  `pDescriptorUpdateTemplate` must be a valid pointer to a VkDescriptorUpdateTemplate handle

Return Codes

On success, this command returns

  - `VK_SUCCESS`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

## See Also

VK_VERSION_1_1, VkAllocationCallbacks, VkDescriptorUpdateTemplate, VkDescriptorUpdateTemplateCreateInfo, 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0