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

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

=== Other Extension Metadata

*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


=== Description

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

It 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 \times WorkGroupSize.y \times WorkgroupSize.z \leq SubgroupSize \times 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.

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

=== 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.