org.lwjgl.vulkan

Class KHRDescriptorUpdateTemplate

java.lang.Object

org.lwjgl.vulkan.KHRDescriptorUpdateTemplate

public class KHRDescriptorUpdateTemplate
extends java.lang.Object

Applications may wish to update a fixed set of descriptors in a large number of descriptors sets very frequently, i.e. during initializaton phase or if it is required to rebuild descriptor sets for each frame. For those cases it is also not unlikely that all information required to update a single descriptor set is stored in a single struct. This extension provides a way to update a fixed set of descriptors in a single VkDescriptorSet with a pointer to a user defined data structure describing the new descriptors.

Promotion to Vulkan 1.1

CmdPushDescriptorSetWithTemplateKHR is included as an interaction with VK_KHR_push_descriptor. If Vulkan 1.1 and VK_KHR_push_descriptor are supported, this is included by VK_KHR_push_descriptor.

The base functionality in this extension is included in core Vulkan 1.1, with the KHR suffix omitted. The original type, enum and command names are still available as aliases of the core functionality.

Name String

VK_KHR_descriptor_update_template

Extension Type

Device extension

Registered Extension Number

86

Revision

1

Extension and Version Dependencies

• Requires Vulkan 1.0

Deprecation state

• Promoted to Vulkan 1.1

Contact

• Markus Tavenrath mtavenrath

Last Modified Date

2017-09-05

IP Status

No known IP claims.

Interactions and External Dependencies

• Interacts with VK_KHR_push_descriptor
• Promoted to Vulkan 1.1 Core

Contributors

• Jeff Bolz, NVIDIA
• Michael Worcester, Imagination Technologies

Field Summary

Fields

Modifier and Type	Field and Description
static int	VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT Extends VkDebugReportObjectTypeEXT.
static int	VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR Extends VkDescriptorUpdateTemplateType.
static int	VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR Extends VkDescriptorUpdateTemplateType.
static java.lang.String	VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME The extension name.
static int	VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION The extension specification version.
static int	VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR Extends VkObjectType.
static int	VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static int	nvkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device, long pCreateInfo, long pAllocator, long pDescriptorUpdateTemplate) Unsafe version of: CreateDescriptorUpdateTemplateKHR
static void	nvkDestroyDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device, long descriptorUpdateTemplate, long pAllocator) Unsafe version of: DestroyDescriptorUpdateTemplateKHR
static void	vkCmdPushDescriptorSetWithTemplateKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long descriptorUpdateTemplate, long layout, int set, long pData) Pushes descriptor updates into a command buffer using a descriptor update template.
static int	vkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device, VkDescriptorUpdateTemplateCreateInfo pCreateInfo, VkAllocationCallbacks pAllocator, long[] pDescriptorUpdateTemplate) Array version of: CreateDescriptorUpdateTemplateKHR
static int	vkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device, VkDescriptorUpdateTemplateCreateInfo pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pDescriptorUpdateTemplate) See CreateDescriptorUpdateTemplate.
static void	vkDestroyDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device, long descriptorUpdateTemplate, VkAllocationCallbacks pAllocator) See DestroyDescriptorUpdateTemplate.
static void	vkUpdateDescriptorSetWithTemplateKHR(org.lwjgl.vulkan.VkDevice device, long descriptorSet, long descriptorUpdateTemplate, long pData) See UpdateDescriptorSetWithTemplate.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION

public static final int VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_SPEC_VERSION

The extension specification version.

See Also:

Constant Field Values

VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME

public static final java.lang.String VK_KHR_DESCRIPTOR_UPDATE_TEMPLATE_EXTENSION_NAME

The extension name.

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR

public static final int VK_STRUCTURE_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_CREATE_INFO_KHR

Extends VkStructureType.

See Also:

Constant Field Values

VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR

public static final int VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR

Extends VkObjectType.

See Also:

Constant Field Values

VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR

public static final int VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_DESCRIPTOR_SET_KHR

Extends VkDescriptorUpdateTemplateType.

See Also:

Constant Field Values

VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR

public static final int VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR

Extends VkDescriptorUpdateTemplateType.

See Also:

Constant Field Values

VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT

public static final int VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT

Extends VkDebugReportObjectTypeEXT.

See Also:

Constant Field Values

Method Detail

nvkCreateDescriptorUpdateTemplateKHR

public static int nvkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                       long pCreateInfo,
                                                       long pAllocator,
                                                       long pDescriptorUpdateTemplate)

Unsafe version of: CreateDescriptorUpdateTemplateKHR

vkCreateDescriptorUpdateTemplateKHR

public static int vkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                      VkDescriptorUpdateTemplateCreateInfo pCreateInfo,
                                                      @Nullable
                                                      VkAllocationCallbacks pAllocator,
                                                      java.nio.LongBuffer pDescriptorUpdateTemplate)

See CreateDescriptorUpdateTemplate.

Parameters:

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

pCreateInfo - a pointer to a VkDescriptorUpdateTemplateCreateInfo structure specifying the set of descriptors to update with a single call to CmdPushDescriptorSetWithTemplateKHR or UpdateDescriptorSetWithTemplate.

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

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

nvkDestroyDescriptorUpdateTemplateKHR

public static void nvkDestroyDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                         long descriptorUpdateTemplate,
                                                         long pAllocator)

Unsafe version of: DestroyDescriptorUpdateTemplateKHR

vkDestroyDescriptorUpdateTemplateKHR

public static void vkDestroyDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                        long descriptorUpdateTemplate,
                                                        @Nullable
                                                        VkAllocationCallbacks pAllocator)

See DestroyDescriptorUpdateTemplate.

Parameters:

device - the logical device that has been used to create the descriptor update template

descriptorUpdateTemplate - the descriptor update template to destroy.

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

vkUpdateDescriptorSetWithTemplateKHR

public static void vkUpdateDescriptorSetWithTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                        long descriptorSet,
                                                        long descriptorUpdateTemplate,
                                                        long pData)

See UpdateDescriptorSetWithTemplate.

Parameters:

device - the logical device that updates the descriptor sets.

descriptorSet - the descriptor set to update

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

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

vkCmdPushDescriptorSetWithTemplateKHR

public static void vkCmdPushDescriptorSetWithTemplateKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                                         long descriptorUpdateTemplate,
                                                         long layout,
                                                         int set,
                                                         long pData)

Pushes descriptor updates into a command buffer using a descriptor update template.

C Specification

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

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 CreateDescriptorUpdateTemplateKHR

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

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

Parameters:

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

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

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

set - 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 - a pointer to memory containing descriptors for the templated update.

vkCreateDescriptorUpdateTemplateKHR

public static int vkCreateDescriptorUpdateTemplateKHR(org.lwjgl.vulkan.VkDevice device,
                                                      VkDescriptorUpdateTemplateCreateInfo pCreateInfo,
                                                      @Nullable
                                                      VkAllocationCallbacks pAllocator,
                                                      long[] pDescriptorUpdateTemplate)

Array version of: CreateDescriptorUpdateTemplateKHR