include::meta/VK_EXT_vertex_attribute_divisor.txt[]

*Last Modified Date*::
    2018-08-03
*IP Status*::
    No known IP claims.
*Contributors*::
  - Vikram Kushwaha, NVIDIA
  - Jason Ekstrand, Intel

This extension allows instance-rate vertex attributes to be repeated for
certain number of instances instead of advancing for every instance when
instanced rendering is enabled.

=== New Object Types

None.

=== New Enum Constants

Extending elink:VkStructureType:

  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT
  ** ename:VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT

=== New Enums

None.

=== New Structures

  * Extending slink:VkPipelineVertexInputStateCreateInfo:
  ** slink:VkPipelineVertexInputDivisorStateCreateInfoEXT
  * slink:VkPhysicalDeviceVertexAttributeDivisorPropertiesEXT
  * slink:VkVertexInputBindingDivisorDescriptionEXT
  * Extending slink:VkPhysicalDeviceFeatures2:
  ** slink:VkPhysicalDeviceVertexAttributeDivisorFeaturesEXT

=== New Functions

None.

=== Issues

1) What is the effect of a non-zero value for pname:firstInstance?

*RESOLVED*: The Vulkan API should follow the OpenGL convention and offset
attribute fetching by pname:firstInstance while computing vertex attribute
offsets.

2) Should zero be an allowed divisor?

*RESOLVED*: Yes.
A zero divisor means the vertex attribute is repeated for all instances.


=== Examples

To create a vertex binding such that the first binding uses instanced
rendering and the same attribute is used for every 4 draw instances, an
application could use the following set of structures:


[source,c++]
----------------------------------------

    const VkVertexInputBindingDivisorDescriptionEXT divisorDesc =
    {
        0,
        4
    };

    const VkPipelineVertexInputDivisorStateCreateInfoEXT divisorInfo =
    {
        VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT, // sType
        NULL,                                                             // pNext
        1,                                                                // vertexBindingDivisorCount
        &divisorDesc                                                      // pVertexBindingDivisors
    }

    const VkVertexInputBindingDescription binding =
    {
        0,                                                                // binding
        sizeof(Vertex),                                                   // stride
        VK_VERTEX_INPUT_RATE_INSTANCE                                     // inputRate
    };

    const VkPipelineVertexInputStateCreateInfo viInfo =
    {
        VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_CREATE_INFO,              // sType
        &divisorInfo,                                                     // pNext
        ...
    };
    //...
----------------------------------------

=== Version History

  * Revision 1, 2017-12-04 (Vikram Kushwaha)
    - First Version
  * Revision 2, 2018-07-16 (Jason Ekstrand)
    - Adjust the interaction between pname:divisor and pname:firstInstance
      to match the OpenGL convention.
    - Disallow divisors of zero.
  * Revision 3, 2018-08-03 (Vikram Kushwaha)
    - Allow a zero divisor.
    - Add a physical device features structure to query/enable this feature.