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 Description static int
VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
ExtendsVkDescriptorSetLayoutCreateFlagBits
.static int
VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR
ExtendsVkDescriptorUpdateTemplateType
.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
ExtendsVkStructureType
.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
nvkCmdPushDescriptorSetKHR(VkCommandBuffer commandBuffer, int pipelineBindPoint, long layout, int set, int descriptorWriteCount, long pDescriptorWrites)
Unsafe version of:CmdPushDescriptorSetKHR
static void
vkCmdPushDescriptorSetKHR(VkCommandBuffer commandBuffer, int pipelineBindPoint, long layout, int set, VkWriteDescriptorSet.Buffer pDescriptorWrites)
Pushes descriptor updates into a command buffer.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.
-
-
-
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
ExtendsVkStructureType
.- 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
ExtendsVkDescriptorSetLayoutCreateFlagBits
.- 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
ExtendsVkDescriptorUpdateTemplateType
.- See Also:
- Constant Field Values
-
-
Method Detail
-
nvkCmdPushDescriptorSetKHR
public static void nvkCmdPushDescriptorSetKHR(VkCommandBuffer commandBuffer, int pipelineBindPoint, long layout, int set, int descriptorWriteCount, long pDescriptorWrites)
Unsafe version of:CmdPushDescriptorSetKHR
- Parameters:
descriptorWriteCount
- the number of elements in thepDescriptorWrites
array.
-
vkCmdPushDescriptorSetKHR
public static void vkCmdPushDescriptorSetKHR(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 ofVkDescriptorBufferInfo
can be changed each time the descriptor is written.Each element of
pDescriptorWrites
is interpreted as inVkWriteDescriptorSet
, except thedstSet
member is ignored.To push an immutable sampler, use a
VkWriteDescriptorSet
withdstBinding
anddstArrayElement
selecting the immutable sampler's binding. If the descriptor type isDESCRIPTOR_TYPE_SAMPLER
, thepImageInfo
parameter is ignored and the immutable sampler is taken from the push descriptor set layout in the pipeline layout. If the descriptor type isDESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
, thesampler
member of thepImageInfo
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 thecommandBuffer
’s parentVkCommandPool
’s queue familyset
must be less thanVkPipelineLayoutCreateInfo
::setLayoutCount
provided whenlayout
was createdset
must be the unique set number in the pipeline layout that uses a descriptor set layout that was created withDESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR
Valid Usage (Implicit)
commandBuffer
must be a validVkCommandBuffer
handlepipelineBindPoint
must be a validVkPipelineBindPoint
valuelayout
must be a validVkPipelineLayout
handlepDescriptorWrites
must be a valid pointer to an array ofdescriptorWriteCount
validVkWriteDescriptorSet
structurescommandBuffer
must be in the recording state- The
VkCommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations descriptorWriteCount
must be greater than 0- Both of
commandBuffer
, andlayout
must have been created, allocated, or retrieved from the sameVkDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized - Host access to the
VkCommandPool
thatcommandBuffer
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
- Parameters:
commandBuffer
- the command buffer that the descriptors will be recorded in.pipelineBindPoint
- aVkPipelineBindPoint
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
- aVkPipelineLayout
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 ofVkWriteDescriptorSet
structures describing the descriptors to be updated.
-
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 thecommandBuffer
’s parentVkCommandPool
’s queue family pData
must be a valid pointer to a memory that contains one or more valid instances ofVkDescriptorImageInfo
,VkDescriptorBufferInfo
, orVkBufferView
in a layout defined bydescriptorUpdateTemplate
when it was created withCreateDescriptorUpdateTemplateKHR
Valid Usage (Implicit)
commandBuffer
must be a validVkCommandBuffer
handledescriptorUpdateTemplate
must be a validVkDescriptorUpdateTemplate
handlelayout
must be a validVkPipelineLayout
handlecommandBuffer
must be in the recording state- The
VkCommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations - Each of
commandBuffer
,descriptorUpdateTemplate
, andlayout
must have been created, allocated, or retrieved from the sameVkDevice
Host Synchronization
- Host access to
commandBuffer
must be externally synchronized - Host access to the
VkCommandPool
thatcommandBuffer
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 that defines how to interpret the descriptor information inpData
.layout
- aVkPipelineLayout
object used to program the bindings. It must be compatible with the layout used to create thedescriptorUpdateTemplate
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 thedescriptorUpdateTemplate
handle.pData
- points to memory which contains the descriptors for the templated update.
- The
-
-