// Copyright 2016-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_EXT_shader_subgroup_vote.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2016-11-28
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - This extension requires
    {spirv}/KHR/SPV_KHR_subgroup_vote.html[`SPV_KHR_subgroup_vote`]
  - This extension provides API support for
    https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_shader_group_vote.txt[`GL_ARB_shader_group_vote`]
*Contributors*::
  - Neil Henning, Codeplay
  - Daniel Koch, NVIDIA Corporation

=== Description

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

  * `SPV_KHR_subgroup_vote`

This extension provides new SPIR-V instructions:

  * code:OpSubgroupAllKHR,
  * code:OpSubgroupAnyKHR, and
  * code:OpSubgroupAllEqualKHR.

to compute the composite of a set of boolean conditions across a group of
shader invocations that are running concurrently (a _subgroup_).
These composite results may be used to execute shaders more efficiently on a
slink:VkPhysicalDevice.

When using GLSL source-based shader languages, the following shader
functions from GL_ARB_shader_group_vote can map to these SPIR-V
instructions:

  * code:anyInvocationARB() -> code:OpSubgroupAnyKHR,
  * code:allInvocationsARB() -> code:OpSubgroupAllKHR, and
  * code:allInvocationsEqualARB() -> code:OpSubgroupAllEqualKHR.

The subgroup across which the boolean conditions are evaluated is
implementation-dependent, and this extension provides no guarantee over how
individual shader invocations are assigned to subgroups.
In particular, a subgroup has no necessary relationship with the compute
shader _local workgroup_ -- any pair of shader invocations in a compute
local workgroup may execute in different subgroups as used by these
instructions.

Compute shaders operate on an explicitly specified group of threads (a local
workgroup), but many implementations will also group non-compute shader
invocations and execute them concurrently.
When executing code like

[source,c++]
----------------------------------------
if (condition) {
  result = do_fast_path();
} else {
  result = do_general_path();
}
----------------------------------------

where code:condition diverges between invocations, an implementation might
first execute code:do_fast_path() for the invocations where code:condition
is true and leave the other invocations dormant.
Once code:do_fast_path() returns, it might call code:do_general_path() for
invocations where code:condition is code:false and leave the other
invocations dormant.
In this case, the shader executes *both* the fast and the general path and
might be better off just using the general path for all invocations.

This extension provides the ability to avoid divergent execution by
evaluating a condition across an entire subgroup using code like:

[source,c++]
----------------------------------------
if (allInvocationsARB(condition)) {
  result = do_fast_path();
} else {
  result = do_general_path();
}
----------------------------------------

The built-in function code:allInvocationsARB() will return the same value
for all invocations in the group, so the group will either execute
code:do_fast_path() or code:do_general_path(), but never both.
For example, shader code might want to evaluate a complex function
iteratively by starting with an approximation of the result and then
refining the approximation.
Some input values may require a small number of iterations to generate an
accurate result (code:do_fast_path) while others require a larger number
(code:do_general_path).
In another example, shader code might want to evaluate a complex function
(code:do_general_path) that can be greatly simplified when assuming a
specific value for one of its inputs (code:do_fast_path).

=== Deprecated by Vulkan 1.1

All functionality in this extension is superseded by the core Vulkan 1.1
<<VkPhysicalDeviceSubgroupProperties, subgroup operations>>.

include::{generated}/interfaces/VK_EXT_shader_subgroup_vote.txt[]

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-SubgroupVoteKHR,SubgroupVoteKHR>>

=== Version History

  * Revision 1, 2016-11-28 (Daniel Koch)
    - Initial draft