// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[VK_KHR_shader_draw_parameters]]
== VK_KHR_shader_draw_parameters

*Name String*::
    +VK_KHR_shader_draw_parameters+
*Extension Type*::
    Device extension
*Registered Extension Number*::
    64
*Status*::
    Complete
*Last Modified Data*::
    2016-10-05
*Revision*::
    1
*IP Status*::
    No known IP claims.
*Dependencies*::
  - This extension is written against version 1.0 of the Vulkan API.
  - Requires Vulkan 1.0.
  - Requires the +SPV_KHR_shader_draw_parameters+ SPIR-V extension.
  - Requires +GL_ARB_shader_draw_parameters+ for GLSL source languages.
*Contributors*::
  - Daniel Koch, NVIDIA Corporation
  - Jeff Bolz, NVIDIA
  - Daniel Rakos, AMD
  - Jan-Harald Fredriksen, ARM
  - John Kessenich, Google
  - Stuart Smith, IMG
*Contact*::
  - Daniel Koch (dkoch 'at' nvidia.com)
*Overview*::

This extension adds support for the following SPIR-V extension in Vulkan:

* +SPV_KHR_shader_draw_parameters+

+
--
The extension provides access to three additional built-in shader variables
in Vulkan:

  * code:BaseInstance, which contains the firstInstance parameter passed to
    draw commands,
  * code:BaseVertex, which contains the firstVertex/vertexOffset parameter
    passed to draw commands, and
  * code:DrawIndex, which contains the index of the draw call currently
    being processed from an indirect draw call.

When using GLSL source-based shader languages, the following variables from
+GL_ARB_shader_draw_parameters+ can map to these SPIR-V built-in
decorations:

  * in int gl_BaseInstanceARB; -> code:BaseInstance,
  * in int gl_BaseVertexARB -> code:BaseVertex, and
  * in int gl_DrawIDARB; -> code:DrawIndex.
--

=== New Object Types

None.

=== New Enum Constants

None.

=== New Enums

None.

=== New Structures

None.

=== New Functions

None.

=== New Built-In Variables

  * <<interfaces-builtin-variables-baseinstance,code:BaseInstance>>
  * <<interfaces-builtin-variables-basevertex,code:BaseVertex>>
  * <<interfaces-builtin-variables-drawindex,code:DrawIndex>>

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-drawparameters,DrawParameters>>

=== Issues

1) Is this the same functionality as +GL_ARB_shader_draw_parameters+?

*RESOLVED*: It's actually a superset as it also adds in support for arrayed
drawing commands.

In GL for +GL_ARB_shader_draw_parameters+, code:gl_BaseVertexARB holds the
integer value passed to the parameter to the command that resulted in the
current shader invocation.
In the case where the command has no baseVertex parameter, the value of
code:gl_BaseVertexARB is zero.
This means that code:gl_BaseVertexARB = baseVertex (for code:glDrawElements
commands with baseVertex) or 0.
In particular there are no code:glDrawArrays commands that take a baseVertex
parameter.

Now in Vulkan, we have *BaseVertex* = _vertexOffset_ (for indexed drawing
commands) or _firstVertex_ (for arrayed drawing commands), and so Vulkan's
version is really a superset of GL functionality.

=== Version History

  * Revision 1, 2016-10-05 (Daniel Koch)
    - Internal revisions