Vulkan.Extensions.VK_KHR_push_descriptor

Name

VK_KHR_push_descriptor - device extension

VK_KHR_push_descriptor

Name String

VK_KHR_push_descriptor

Extension Type

Device extension

Registered Extension Number

81

Revision

2

Extension and Version Dependencies

• Requires support for Vulkan 1.0
• Requires VK_KHR_get_physical_device_properties2 to be enabled for any device-level functionality

Contact

• Jeff Bolz @jeffbolznv%0A*Here describe the issue or question you have about the VK_KHR_push_descriptor extension*

Other Extension Metadata

Last Modified Date

2017-09-12

IP Status

No known IP claims.

Contributors

• Jeff Bolz, NVIDIA
• Michael Worcester, Imagination Technologies

Description

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.

New Commands

• cmdPushDescriptorSetKHR

If VK_KHR_descriptor_update_template is supported:

• cmdPushDescriptorSetWithTemplateKHR

If Version 1.1 is supported:

• cmdPushDescriptorSetWithTemplateKHR

New Structures

• Extending PhysicalDeviceProperties2:

  • PhysicalDevicePushDescriptorPropertiesKHR

New Enum Constants

• KHR_PUSH_DESCRIPTOR_EXTENSION_NAME

• KHR_PUSH_DESCRIPTOR_SPEC_VERSION

• Extending DescriptorSetLayoutCreateFlagBits:

  • DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR

• Extending StructureType:

  • STRUCTURE_TYPE_PHYSICAL_DEVICE_PUSH_DESCRIPTOR_PROPERTIES_KHR

If VK_KHR_descriptor_update_template is supported:

• Extending DescriptorUpdateTemplateType:

  • DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR

If Version 1.1 is supported:

• Extending DescriptorUpdateTemplateType:

  • DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR

Version History

• Revision 1, 2016-10-15 (Jeff Bolz)

  • Internal revisions

• Revision 2, 2017-09-12 (Tobias Hector)

  • Added interactions with Vulkan 1.1

See Also

PhysicalDevicePushDescriptorPropertiesKHR, cmdPushDescriptorSetKHR

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Documentation

cmdPushDescriptorSetKHR

Arguments

:: forall io. MonadIO io

=> CommandBuffer

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

-> PipelineBindPoint

pipelineBindPoint is a PipelineBindPoint indicating the type of the pipeline that will use the descriptors. There is a separate set of push descriptor bindings for each pipeline type, so binding one does not disturb the others.

-> PipelineLayout

layout is a PipelineLayout object used to program the bindings.

-> ("set" ::: Word32)

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

-> ("descriptorWrites" ::: Vector (SomeStruct WriteDescriptorSet))

pDescriptorWrites is a pointer to an array of WriteDescriptorSet structures describing the descriptors to be updated.

-> io ()

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 drawing or dispatching 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
• For each element i where pDescriptorWrites[i].descriptorType is DESCRIPTOR_TYPE_SAMPLED_IMAGE, DESCRIPTOR_TYPE_STORAGE_IMAGE, or DESCRIPTOR_TYPE_INPUT_ATTACHMENT, pDescriptorWrites[i].pImageInfo must be a valid pointer to an array of pDescriptorWrites[i].descriptorCount valid DescriptorImageInfo structures

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
• This command must only be called outside of a video coding scope
• 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

'

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Both	Outside	Graphics Compute	State

See Also

VK_KHR_push_descriptor, CommandBuffer, PipelineBindPoint, PipelineLayout, WriteDescriptorSet

cmdPushDescriptorSetWithTemplateKHR

Arguments

:: forall io. MonadIO io

=> CommandBuffer

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

-> DescriptorUpdateTemplate

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

-> PipelineLayout

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

-> ("set" ::: Word32)

set is 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.

-> ("data" ::: Ptr ())

pData is a pointer to memory containing descriptors for the templated update.

-> io ()

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 createDescriptorUpdateTemplate
• 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

• 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
• This command must only be called outside of a video coding scope
• 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

'

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Both	Outside	Graphics Compute	State

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 push 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

VK_KHR_descriptor_update_template, VK_KHR_push_descriptor, VK_VERSION_1_1, CommandBuffer, DescriptorUpdateTemplate, PipelineLayout

data PhysicalDevicePushDescriptorPropertiesKHR

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

Description

If the PhysicalDevicePushDescriptorPropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Valid Usage (Implicit)

See Also

VK_KHR_push_descriptor, StructureType

Constructors

PhysicalDevicePushDescriptorPropertiesKHR

Fields

• maxPushDescriptors :: Word32

  maxPushDescriptors is the maximum number of descriptors that can be used in a descriptor set created with DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set.

Instances

Eq PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

(==) :: PhysicalDevicePushDescriptorPropertiesKHR -> PhysicalDevicePushDescriptorPropertiesKHR -> Bool

(/=) :: PhysicalDevicePushDescriptorPropertiesKHR -> PhysicalDevicePushDescriptorPropertiesKHR -> Bool

Show PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

showsPrec :: Int -> PhysicalDevicePushDescriptorPropertiesKHR -> ShowS

show :: PhysicalDevicePushDescriptorPropertiesKHR -> String

showList :: [PhysicalDevicePushDescriptorPropertiesKHR] -> ShowS

Storable PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

sizeOf :: PhysicalDevicePushDescriptorPropertiesKHR -> Int

alignment :: PhysicalDevicePushDescriptorPropertiesKHR -> Int

peekElemOff :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> Int -> IO PhysicalDevicePushDescriptorPropertiesKHR

pokeElemOff :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> Int -> PhysicalDevicePushDescriptorPropertiesKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO PhysicalDevicePushDescriptorPropertiesKHR

pokeByteOff :: Ptr b -> Int -> PhysicalDevicePushDescriptorPropertiesKHR -> IO ()

peek :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> IO PhysicalDevicePushDescriptorPropertiesKHR

poke :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> PhysicalDevicePushDescriptorPropertiesKHR -> IO ()

FromCStruct PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

peekCStruct :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> IO PhysicalDevicePushDescriptorPropertiesKHR

ToCStruct PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

withCStruct :: PhysicalDevicePushDescriptorPropertiesKHR -> (Ptr PhysicalDevicePushDescriptorPropertiesKHR -> IO b) -> IO b

pokeCStruct :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> PhysicalDevicePushDescriptorPropertiesKHR -> IO b -> IO b

withZeroCStruct :: (Ptr PhysicalDevicePushDescriptorPropertiesKHR -> IO b) -> IO b

pokeZeroCStruct :: Ptr PhysicalDevicePushDescriptorPropertiesKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PhysicalDevicePushDescriptorPropertiesKHR

Defined in Vulkan.Extensions.VK_KHR_push_descriptor

Methods

zero :: PhysicalDevicePushDescriptorPropertiesKHR

type KHR_PUSH_DESCRIPTOR_SPEC_VERSION = 2

pattern KHR_PUSH_DESCRIPTOR_SPEC_VERSION :: forall a. Integral a => a

type KHR_PUSH_DESCRIPTOR_EXTENSION_NAME = "VK_KHR_push_descriptor"

pattern KHR_PUSH_DESCRIPTOR_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a