vkCmdPushDescriptorSetKHR - Pushes descriptor updates into a command buffer

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 bound pipeline commands with the pipeline type set by 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 DescriptorBufferInfo can be changed each time the descriptor is written.

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

To push an immutable sampler, use a WriteDescriptorSet 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 CommandPool’s queue family

• set must be less than PipelineLayoutCreateInfo::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 CommandBuffer handle

• pipelineBindPoint must be a valid PipelineBindPoint value
• layout must be a valid PipelineLayout handle
• pDescriptorWrites must be a valid pointer to an array of descriptorWriteCount valid WriteDescriptorSet structures
• commandBuffer must be in the recording state
• The CommandPool 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 Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

See Also

CommandBuffer, PipelineBindPoint, PipelineLayout, WriteDescriptorSet

vkCmdPushDescriptorSetWithTemplateKHR - Pushes descriptor updates into a command buffer using a descriptor update template

Valid Usage

• The pipelineBindPoint specified during the creation of the descriptor update template must be supported by the commandBuffer’s parent CommandPool’s queue family

• pData must be a valid pointer to a memory containing one or more valid instances of DescriptorImageInfo, DescriptorBufferInfo, or BufferView in a layout defined by descriptorUpdateTemplate when it was created with createDescriptorUpdateTemplateKHR

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• descriptorUpdateTemplate must be a valid DescriptorUpdateTemplate handle
• layout must be a valid PipelineLayout handle
• commandBuffer must be in the recording state
• The CommandPool 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 Device

Host Synchronization

• Host access to commandBuffer must be externally synchronized

• Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

API example

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

See Also

CommandBuffer, DescriptorUpdateTemplate, PipelineLayout

VkPhysicalDevicePushDescriptorPropertiesKHR - Structure describing push descriptor limits that can be supported by an implementation

Members

The members of the PhysicalDevicePushDescriptorPropertiesKHR structure describe the following implementation-dependent limits:

Description

If the PhysicalDevicePushDescriptorPropertiesKHR structure is included in the pNext chain of PhysicalDeviceProperties2, it is filled with the implementation-dependent limits.

Valid Usage (Implicit)

See Also

StructureType