Package org.lwjgl.vulkan

Class 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 which describes 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
    Contact
    Last Modified Date
    2017-09-05
    IP Status
    No known IP claims.
    Interactions and External Dependencies
    Contributors
    • Jeff Bolz, NVIDIA
    • Michael Worcester, Imagination Technologies

    • Method Detail

      • nvkCreateDescriptorUpdateTemplateKHR

        public static int nvkCreateDescriptorUpdateTemplateKHR​(VkDevice device,
                                                       long pCreateInfo,
                                                       long pAllocator,
                                                       long pDescriptorUpdateTemplate)
        Unsafe version of: CreateDescriptorUpdateTemplateKHR

      • nvkDestroyDescriptorUpdateTemplateKHR

        public static void nvkDestroyDescriptorUpdateTemplateKHR​(VkDevice device,
                                                         long descriptorUpdateTemplate,
                                                         long pAllocator)
        Unsafe version of: DestroyDescriptorUpdateTemplateKHR

      • vkDestroyDescriptorUpdateTemplateKHR

        public static void vkDestroyDescriptorUpdateTemplateKHR​(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​(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 - the VkDescriptorUpdateTemplate which specifies the update mapping between pData and the descriptor set to update.
        pData - a pointer to memory which contains one or more structures of VkDescriptorImageInfo, VkDescriptorBufferInfo, or VkBufferView used to write the descriptors.

      • vkCmdPushDescriptorSetWithTemplateKHR

        public static void vkCmdPushDescriptorSetWithTemplateKHR​(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 that contains 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 LevelsRender Pass ScopeSupported Queue TypesPipeline Type
        Primary SecondaryBothGraphics 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 that defines 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 - points to memory which contains the descriptors for the templated update.