org.lwjgl.vulkan

Class KHRPushDescriptor

java.lang.Object

org.lwjgl.vulkan.KHRPushDescriptor

public class KHRPushDescriptor
extends java.lang.Object

This extension allows descriptors to be written into the command buffer, while the implementation is responsible for managing their memory. Push descriptors may enable easier porting from older APIs and in some cases can be more efficient than writing descriptors into descriptor sets.

Examples

None.

Name String

VK_KHR_push_descriptor

Extension Type

Device extension

Registered Extension Number

81

Revision

2

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_get_physical_device_properties2

Contact

• Jeff Bolz jeffbolznv

Last Modified Date

2017-09-12

IP Status

No known IP claims.

Contributors

• Jeff Bolz, NVIDIA
• Michael Worcester, Imagination Technologies

Field Summary

Fields

Modifier and Type	Field and Description
static int	VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR Extends VkDescriptorSetLayoutCreateFlagBits.
static int	VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR Extends VkDescriptorUpdateTemplateType.
static java.lang.String	VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME The extension name.
static int	VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION The extension specification version.
static int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static void	nvkCmdPushDescriptorSetKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int pipelineBindPoint, long layout, int set, int descriptorWriteCount, long pDescriptorWrites) Unsafe version of: CmdPushDescriptorSetKHR
static void	vkCmdPushDescriptorSetKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, int pipelineBindPoint, long layout, int set, VkWriteDescriptorSet.Buffer pDescriptorWrites) Pushes descriptor updates into a command buffer.
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.

Methods inherited from class java.lang.Object

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

Field Detail

VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION

public static final int VK_KHR_PUSH_DESCRIPTOR_SPEC_VERSION

The extension specification version.

See Also:

Constant Field Values

VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME

public static final java.lang.String VK_KHR_PUSH_DESCRIPTOR_EXTENSION_NAME

The extension name.

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR

public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR

Extends VkStructureType.

See Also:

Constant Field Values

VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

public static final int VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

Extends VkDescriptorSetLayoutCreateFlagBits.

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

Method Detail

nvkCmdPushDescriptorSetKHR

public static void nvkCmdPushDescriptorSetKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                              int pipelineBindPoint,
                                              long layout,
                                              int set,
                                              int descriptorWriteCount,
                                              long pDescriptorWrites)

Unsafe version of: CmdPushDescriptorSetKHR

Parameters:

descriptorWriteCount - the number of elements in the pDescriptorWrites array.

vkCmdPushDescriptorSetKHR

public static void vkCmdPushDescriptorSetKHR(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                             int pipelineBindPoint,
                                             long layout,
                                             int set,
                                             VkWriteDescriptorSet.Buffer pDescriptorWrites)

Pushes descriptor updates into a command buffer.

C Specification

In addition to allocating descriptor sets and binding them to a command buffer, an application can record descriptor updates into the command buffer.

To push descriptor updates into a command buffer, call:

 void vkCmdPushDescriptorSetKHR(
     VkCommandBuffer                             commandBuffer,
     VkPipelineBindPoint                         pipelineBindPoint,
     VkPipelineLayout                            layout,
     uint32_t                                    set,
     uint32_t                                    descriptorWriteCount,
     const VkWriteDescriptorSet*                 pDescriptorWrites);

Description

Push descriptors are a small bank of descriptors whose storage is internally managed by the command buffer rather than being written into a descriptor set and later bound to a command buffer. Push descriptors allow for incremental updates of descriptors without managing the lifetime of descriptor sets.

When a command buffer begins recording, all push descriptors are undefined. Push descriptors can be updated incrementally and cause shaders to use the updated descriptors for subsequent rendering commands (either compute or graphics, according to the pipelineBindPoint) until the descriptor is overwritten, or else until the set is disturbed as described in Pipeline Layout Compatibility. When the set is disturbed or push descriptors with a different descriptor set layout are set, all push descriptors are undefined.

Push descriptors that are statically used by a pipeline must not be undefined at the time that a draw or dispatch command is recorded to execute using that pipeline. This includes immutable sampler descriptors, which must be pushed before they are accessed by a pipeline (the immutable samplers are pushed, rather than the samplers in pDescriptorWrites). Push descriptors that are not statically used can remain undefined.

Push descriptors do not use dynamic offsets. Instead, the corresponding non-dynamic descriptor types can be used and the offset member of VkDescriptorBufferInfo can be changed each time the descriptor is written.

Each element of pDescriptorWrites is interpreted as in VkWriteDescriptorSet, except the dstSet member is ignored.

To push an immutable sampler, use a VkWriteDescriptorSet with dstBinding and dstArrayElement selecting the immutable sampler's binding. If the descriptor type is DESCRIPTOR_TYPE_SAMPLER, the pImageInfo parameter is ignored and the immutable sampler is taken from the push descriptor set layout in the pipeline layout. If the descriptor type is DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the sampler member of the pImageInfo parameter is ignored and the immutable sampler is taken from the push descriptor set layout in the pipeline layout.

Valid Usage

• pipelineBindPoint must be supported by the commandBuffer’s parent VkCommandPool’s queue family
• set must be less than VkPipelineLayoutCreateInfo::setLayoutCount provided when layout was created
• set must be the unique set number in the pipeline layout that uses a descriptor set layout that was created with DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• pipelineBindPoint must be a valid VkPipelineBindPoint value
• layout must be a valid VkPipelineLayout handle
• pDescriptorWrites must be a valid pointer to an array of descriptorWriteCount valid VkWriteDescriptorSet structures
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations
• descriptorWriteCount must be greater than 0
• Both of commandBuffer, 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

See Also

VkWriteDescriptorSet

Parameters:

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

pipelineBindPoint - a VkPipelineBindPoint indicating whether the descriptors will be used by graphics pipelines or compute pipelines. There is a separate set of push descriptor bindings for each of graphics and compute, so binding one does not disturb the other.

layout - a VkPipelineLayout object used to program the bindings.

set - the set number of the descriptor set in the pipeline layout that will be updated.

pDescriptorWrites - a pointer to an array of VkWriteDescriptorSet structures describing the descriptors to be updated.

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.