Vulkan-Docs/appendices/VK_EXT_descriptor_indexing.txt

include::meta/VK_EXT_descriptor_indexing.txt[]

*Status*::
    Complete
*Last Modified Data*::
    2017-10-02
*Contributors*::
  - Jeff Bolz, NVIDIA
  - Daniel Rakos, AMD
  - Slawomir Grajewski, Intel
  - Tobias Hector, Imagination Technologies

This extension adds several small features which together enable
applications to create large descriptor sets containing substantially all of
their resources, and selecting amongst those resources with dynamic
(non-uniform) indexes in the shader.
There are feature enables and SPIR-V capabilities for non-uniform descriptor
indexing in the shader, and non-uniform indexing in the shader requires use
of a new code:NonUniformEXT decoration defined in the
`SPV_EXT_descriptor_indexing` SPIR-V extension.
There are descriptor set layout binding creation flags enabling several
features:

  * Descriptors can be updated after they are bound to a command buffer,
    such that the execution of the command buffer reflects the most recent
    update to the descriptors.
  * Descriptors that are not used by any pending command buffers can be
    updated, which enables writing new descriptors for frame N+1 while frame
    N is executing.
  * Relax the requirement that all descriptors in a binding that is
    "`statically used`" must be valid, such that descriptors that are not
    accessed by a submission need not be valid and can be updated while that
    submission is executing.
  * The final binding in a descriptor set layout can have a variable size
    (and unsized arrays of resources are allowed in the
    `GL_EXT_nonuniform_qualifier` and `SPV_EXT_descriptor_indexing`
    extensions).

Note that it is valid for multiple descriptor arrays in a shader to use the
same set and binding number, as long as they are all compatible with the
descriptor type in the pipeline layout.
This means a single array binding in the descriptor set can serve multiple
texture dimensionalities, or an array of buffer descriptors can be used with
multiple different block layouts.

There are new descriptor set layout and descriptor pool creation flags that
are required to opt in to the update-after-bind functionality, and there are
separate pname:maxPerStage* and pname:maxDescriptorSet* limits that apply to
these descriptor set layouts which may: be much higher than the pre-existing
limits.
The old limits only count descriptors in non-updateAfterBind descriptor set
layouts, and the new limits count descriptors in all descriptor set layouts
in the pipeline layout.

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_FEATURES_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_INDEXING_PROPERTIES_EXT
  ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_ALLOCATE_INFO_EXT
  ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_SET_VARIABLE_DESCRIPTOR_COUNT_LAYOUT_SUPPORT_EXT

  * Extending elink:VkDescriptorPoolCreateFlagBits:
  ** ename:VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT

  * Extending elink:VkDescriptorSetLayoutCreateFlagBits:
  ** ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT

  * Extending elink:VkResult:
  ** ename:VK_ERROR_FRAGMENTATION_EXT

=== New Enums

  * elink:VkDescriptorBindingFlagBitsEXT

=== New Structures

  * slink:VkDescriptorSetLayoutBindingFlagsCreateInfoEXT
  * slink:VkPhysicalDeviceDescriptorIndexingFeaturesEXT
  * slink:VkPhysicalDeviceDescriptorIndexingPropertiesEXT
  * slink:VkDescriptorSetVariableDescriptorCountAllocateInfoEXT
  * slink:VkDescriptorSetVariableDescriptorCountLayoutSupportEXT

=== New Functions

None.

=== Issues

None.

=== Version History

  * Revision 1, 2017-07-26 (Jeff Bolz)
    - Internal revisions