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

include::{generated}/meta/VK_EXT_subgroup_size_control.txt[]

*Last Modified Date*::
    2019-03-05
*Contributors*::
  - Jeff Bolz, NVIDIA
  - Jason Ekstrand, Intel
  - Sławek Grajewski, Intel
  - Jesse Hall, Google
  - Neil Henning, AMD
  - Daniel Koch, NVIDIA
  - Jeff Leger, Qualcomm
  - Graeme Leese, Broadcom
  - Allan MacKinnon, Google
  - Mariusz Merecki, Intel
  - Graham Wihlidal, Electronic Arts

=== Short Description

Enables an implementation to control the subgroup size by allowing a varying
subgroup size and also specifying a required subgroup size.

=== Description

This extension extends the subgroup support in Vulkan 1.1 to allow an
implementation to expose a varying subgroup size.
Previously Vulkan exposed a single subgroup size per physical device, with
the expectation that implementations will behave as if all subgroups have
the same size.
Some implementations may: dispatch shaders with a varying subgroup size for
different subgroups.
As a result they could implicitly split a large subgroup into smaller
subgroups or represent a small subgroup as a larger subgroup, some of whose
invocations were inactive on launch.

To aid developers in understanding the performance characteristics of their
programs, this extension exposes a minimum and maximum subgroup size that a
physical device supports and a pipeline create flag to enable that pipeline
to vary its subgroup size.
If enabled, any code:SubgroupSize decorated variables in the SPIR-V shader
modules provided to pipeline creation may: vary between the
<<limits-min-subgroup-size,minimum>> and
<<limits-max-subgroup-size,maximum>> subgroup sizes.

An implementation is also optionally allowed to support specifying a
required subgroup size for a given pipeline stage.
Implementations advertise which <<limits-required-subgroup-size-stages,
stages support a required subgroup size>>, and any pipeline of a supported
stage can be passed a
slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure to
set the subgroup size for that shader stage of the pipeline.
For compute shaders, this requires the developer to query the
<<limits-max-subgroups-per-workgroup, pname:maxComputeWorkgroupSubgroups>>
and ensure that:

[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
s = {WorkGroupSize.x * WorkGroupSize.y * WorkgroupSize.z <= SubgroupSize * maxComputeWorkgroupSubgroups }
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Developers can also specify a new pipeline shader stage create flag that
requires the implementation to have fully populated subgroups within local
workgroups.
This requires the workgroup size in the X dimension to be a multiple of the
subgroup size.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_FEATURES_EXT
     (added in version 2)
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SUBGROUP_SIZE_CONTROL_PROPERTIES_EXT
  ** ename:VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_REQUIRED_SUBGROUP_SIZE_CREATE_INFO_EXT
  * Extending elink:VkPipelineShaderStageCreateFlagBits:
  ** ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT
  ** ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT

=== New Structures

  * slink:VkPhysicalDeviceSubgroupSizeControlFeaturesEXT (added in version
    2)
  * slink:VkPhysicalDeviceSubgroupSizeControlPropertiesEXT
  * slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT

=== Issues

None.

=== Version History

  * Revision 1, 2019-03-05 (Neil Henning)
    - Initial draft

  * Revision 2, 2019-07-26 (Jason Ekstrand)
    - Add the missing slink:VkPhysicalDeviceSubgroupSizeControlFeaturesEXT
      for querying subgroup size control features.