Name

    ARB_compute_variable_group_size

Name Strings

    GL_ARB_compute_variable_group_size

Contact

    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)

Contributors

    Slawomir Grajewski, Intel Corporation
    Jeannot Breton, NVIDIA
    Daniel Koch, NVIDIA

Notice

    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Status

    Complete. Approved by the ARB on June 3, 2013.
    Ratified by the Khronos Board of Promoters on July 19, 2013.

Version

    Last Modified Date:         December 10, 2018
    Revision:                   9

Number

    ARB Extension #153

Dependencies

    This extension is written against the OpenGL 4.3 (Compatibility Profile)
    Specification, dated August 6, 2012.

    This extension is written against the OpenGL Shading Language
    Specification, Version 4.30, Revision 7, dated September 24, 2012.

    OpenGL 4.3 or ARB_compute_shader is required.

    This extension interacts with NV_compute_program5.

Overview

    This extension allows applications to write generic compute shaders that
    operate on workgroups with arbitrary dimensions.  Instead of specifying a
    fixed workgroup size in the compute shader, an application can use a
    compute shader using the /local_size_variable/ layout qualifer to indicate
    a variable workgroup size.  When using such compute shaders, the new
    command DispatchComputeGroupSizeARB should be used to specify both a
    workgroup size and workgroup count.

    In this extension, compute shaders with fixed group sizes must be
    dispatched by DispatchCompute and DispatchComputeIndirect.  Compute
    shaders with variable group sizes must be dispatched via
    DispatchComputeGroupSizeARB.  No support is provided in this extension for
    indirect dispatch of compute shaders with a variable group size.

New Procedures and Functions

    void DispatchComputeGroupSizeARB(uint num_groups_x, uint num_groups_y,
                                     uint num_groups_z, uint group_size_x,
                                     uint group_size_y, uint group_size_z);

New Tokens

    Accepted by the <pname> parameter of GetIntegerv, GetBooleanv, GetFloatv,
    GetDoublev and GetInteger64v:

        MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB      0x9344
        MAX_COMPUTE_FIXED_GROUP_INVOCATIONS_ARB         0x90EB (see note)

    Accepted by the <pname> parameter of GetIntegeri_v, GetBooleani_v,
    GetFloati_v, GetDoublei_v and GetInteger64i_v:

        MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB             0x9345
        MAX_COMPUTE_FIXED_GROUP_SIZE_ARB                0x91BF (see note)

    Note:  MAX_COMPUTE_FIXED_GROUP_INVOCATIONS_ARB and
    MAX_COMPUTE_FIXED_GROUP_SIZE_ARB are aliases for the OpenGL 4.3 core enums
    MAX_COMPUTE_WORK_GROUP_INVOCATIONS and MAX_COMPUTE_WORK_GROUP_SIZE,
    respectively.


Modifications to the OpenGL 4.3 (Compatibility Profile) Specification

    Modify Chapter 19, Compute Shaders, p. 585

    (modify second paragraph, p. 585)

    ... One or more workgroups is launched by calling

      void DispatchCompute(uint num_groups_x, uint num_groups_y,
                           uint num_groups_z)

    or

      void DispatchComputeGroupSizeARB(uint num_groups_x, uint num_groups_y,
                                       uint num_groups_z, uint group_size_x,
                                       uint group_size_y, uint group_size_z);

    (modify second paragraph, p. 586)

    For DispatchCompute, the workgroup size in each dimension must be
    specified at compile time in the active program for the compute shader
    stage.  The workgroup size is specified using an input layout qualifer
    ...

    (insert after second paragraph, p. 586)

    For DispatchComputeGroupSizeARB, the workgroup size must be specified as
    variable in the active program for the compute shader stage.  The group
    size used to execute the compute shader is taken from the <group_size_x>,
    <group_size_y>, and <group_size_z> parameters.  For the purposes of the
    COMPUTE_WORK_GROUP_SIZE query, a program without a workgroup size
    specified at compile time will be considered to have a size of zero in
    each dimension.

    (modify the third paragraph, p. 586)

    The maximum size of a workgroup may be determined by calling
    GetIntegeri_v with <index> set to 0, 1, or 2 to retrieve the maximum work
    size in the X, Y and Z dimension, respectively.  <target> should be set to
    MAX_COMPUTE_FIXED_GROUP_SIZE_ARB for compute shaders with fixed group
    sizes or MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB for compute shaders with
    variable local group sizes.  Furthermore, the maximum number of
    invocations in a single workgroup (i.e., the product of the three
    dimensions) may be determined by calling GetIntegerv with <pname> set to
    MAX_COMPUTE_FIXED_GROUP_INVOCATIONS_ARB for compute shaders with fixed
    group sizes or MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB for compute
    shaders with variable group sizes.

    (insert after the first INVALID_OPERATION error in the first error block,
     shared between DispatchCompute and DispatchComputeGroupSizeARB, p. 586)

    An INVALID_OPERATION error is generated by DispatchCompute if the active
    program for the compute shader stage has a variable workgroup
    size.

    An INVALID_OPERATION error is generated by DispatchComputeGroupSizeARB if
    the active program for the compute shader stage has a fixed workgroup
    size.

    (insert at the end of the first error block, shared between
     DispatchCompute and DispatchComputeGroupSizeARB, p. 586)

    An INVALID_VALUE error is generated by DispatchComputeGroupSizeARB if any
    of <group_size_x>, <group_size_y>, or <group_size_z> is less than or equal
    to zero or greater than the maximum workgroup size for compute
    shaders with variable group size (MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB) in
    the corresponding dimension.

    An INVALID_VALUE error is generated by DispatchComputeGroupSizeARB if the
    product of <group_size_x>, <group_size_y>, and <group_size_z> exceeds the
    implementation-dependent maximum workgroup invocation count for
    compute shaders with variable group size
    (MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB).

    (insert at the end of the first error block, for DispatchComputeIndirect,
     p. 587)

    An INVALID_OPERATION error is generated if the active program for the
    compute shader stage has a variable workgroup size.


Modifications to the OpenGL Shading Language Specification, Version 4.30

    Including the following line in a shader can be used to control the
    language features described in this extension:

      #extension GL_ARB_compute_variable_group_size : <behavior>

    where <behavior> is as specified in section 3.3.

    New preprocessor #defines are added to the OpenGL Shading Language:

      #define GL_ARB_compute_variable_group_size        1


    Modify Section 4.4.1.4, Compute Shader Inputs (p. 59)

    (add to list of layout qualifiers for compute shader inputs, p. 59)

      layout-qualifier-id
        local_size_x = integer-constant
        local_size_y = integer-constant
        local_size_z = integer-constant
        local_size_variable

    (modify the last paragraph, p. 59)

    The local_size_x, local_size_y, and local_size_z qualifiers are used to
    declare a fixed local group size for the kernel in the first, second...

    (modify the second to last paragaph in the section)

    If the fixed local group size of the shader in any dimension...
    ... If multiple compute shaders attached to a single program object declare
    a fixed local group size, the declarations must be identical; otherwise a
    link-time error results.

    (insert before the last paragraph of the section, p. 60)

    The *local_size_variable* qualifier is used to declare that
    the local group size of the shader is variable, and will be specified
    using arguments to OpenGL API compute dispatch commands.  If a compute
    shader including a *local_size_variable* qualifier also declares a
    fixed local group size using the *local_size_x*, *local_size_y*, or
    *local_size_z* qualifiers, a compile-time error results.  If one compute
    shader attached to a program declares a variable local group size and a
    second compute shader attached to the same program declares a fixed
    local group size, a link-time error results.

    (modify last paragraph of the section, p. 60, which specified link errors
     if *local_size* layout qualifiers were omitted)

    Furthermore, if a program object contains any compute shaders, at least
    one must contain an input layout qualifier specifying a fixed or variable
    local group size for the program, or a link-time error will occur.


    Modify Section 7.1, Built-In Language Variables, p. 110

    (add to list of compute built-ins, p. 110)

      in    uvec3 gl_NumWorkGroups;     // already exists in 4.30
      const uvec3 gl_WorkGroupSize;     // already exists in 4.30
      in    uvec3 gl_LocalGroupSizeARB; // new!

    (modify third paragraph, p. 113)

    The built-in constant gl_WorkGroupSize is a compute-shader constant ...
    It is a compile-time error to use gl_WorkGroupSize in a shader that does
    not declare a fixed local group size, or before that shader has declared
    a fixed local group size, using local_size_x, local_size_y, and
    local_size_z.   ...

    (insert after third paragraph, p. 113)

    The built-in variable /gl_LocalGroupSizeARB/ is a compute-shader input
    variable containing the workgroup size for the current compute-
    shader workgroup.  For compute shaders with a fixed local group size (using
    *local_size_x*, *local_size_y*, or *local_size_z* layout qualifiers), its
    value will be the same as the constant /gl_WorkGroupSize/.  For compute
    shaders with a variable local group size (using *local_size_variable*),
    the value of /gl_LocalGroupSizeARB/ will be the workgroup
    size specified in the OpenGL API command dispatching the current
    compute shader work.

    (modify next-to-last paragraph, p. 113)

    The built-in variable gl_LocalInvocationID ...  The possible values for
    this varaible range across the workgroup size, i.e., (0,0,0) to
    (gl_LocalGroupSizeARB.x - 1, gl_LocalGroupSizeARB.y - 1,
    gl_LocalGroupSizeARB.z - 1).

    (modify last paragraph, p. 113)

    The built-in variable gl_GlobalInvocationID ...  This is computed as:

      gl_GlobalInvocationID = gl_WorkGroupID * gl_LocalGroupSizeARB +
                              gl_LocalInvocationID;


    (modify first paragraph, p. 114)

    The built-in variable gl_LocalInvocationIndex ...  This is computed as:

      gl_LocalInvocationIndex =
        gl_LocalInvocationID.z * (gl_LocalGroupSizeARB.x *
                                  gl_LocalGroupSizeARB.y) +
        gl_LocalInvocationID.y * gl_LocalGroupSizeARB.x +
        gl_LocalInvocationID.x;


Additions to the AGL/EGL/GLX/WGL Specifications

    None

GLX Protocol

    TBD

Dependencies on NV_compute_program5

    If NV_compute_program5 is supported, variable workgroup sizes are
    supported for assembly programs.  Make the following edits to the
    NV_compute_program5 specification:

    (modify the NV_compute_program5 edits to Section 2.X.3.2, Program
     Attribute Variables)

    If a compute attribute binding matches "invocation.groupsize", the "x",
    "y", and "z" components of the invocation attribute variable are filled
    the "x", "y", and "z" dimensions, respectively, of the workgroup,
    as specified by the GROUP_SIZE declaration for programs with fixed-size
    workgroups or through the OpenGL API for programs with variable-size
    workgroups.  The "w" component of the attribute is undefined.

    (add to section 2.X.6 of the NV_gpu_program4/5 spec, Program Options)

    + Compute Shader Variable Group Size (ARB_compute_variable_group_size)

    If a program specifies the "ARB_compute_variable_group_size" option, it
    supports variable-size workgroups.  Compute programs with a variable
    workgroup size must be dispatched with DispatchComputeGroupSizeARB.  Compute
    programs with a fixed workgroup size must be dispatched with
    DispatchCompute or DispatchComputeIndirect.

    (modify Section 2.X.7.Y, Compute Program Declarations)

    - Shader Thread Group Size (GROUP_SIZE)

    The GROUP_SIZE statement declares the number of shader threads in a one-,
    two-, or three-dimensional workgroup.  The statement must have one
    to three unsigned integer arguments.  Each argument must be less than or
    equal to the value of the implementation-dependent limit
    MAX_COMPUTE_LOCAL_WORK_SIZE for its corresponding dimension (X, Y, or Z).
    If the ARB_compute_variable_group_size option is specified, no fixed group
    size should be specified and a program will fail to load if it includes
    any GROUP_SIZE declaration.  If the ARB_compute_variable_group_size option
    is not specified, a program will fail to load unless it contains exactly
    one GROUP_SIZE declaration.

Errors

    An INVALID_OPERATION error is generated by DispatchCompute or
    DispatchComputeIndirect if the active program for the compute shader stage
    has a variable workgroup size.

    An INVALID_OPERATION error is generated by DispatchComputeGroupSizeARB if
    the active program for the compute shader stage has a fixed workgroup
    size.

    An INVALID_VALUE error is generated by DispatchComputeGroupSizeARB if any
    of <group_size_x>, <group_size_y>, or <group_size_z> is less than or equal
    to zero or greater than the maximum workgroup size for compute
    shaders with variable group size (MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB) in
    the corresponding dimension.

    An INVALID_VALUE error is generated by DispatchComputeGroupSizeARB if the
    product of <group_size_x>, <group_size_y>, and <group_size_z> exceeds the
    implementation-dependent maximum workgroup invocation count for
    compute shaders with variable group size
    (MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB).

New State

    None.

New Implementation Dependent State

    Add to Table 23.73 (Implementation Dependent Compute Shader Limits),
    p. 716

                                                    Minimum
    Get Value                  Type  Get Command     Value     Description                    Sec.
    -------------------------  ----  -------------  ---------  ----------------------------   ------
    MAX_COMPUTE_VARIABLE_      3xZ+  GetIntegeri_v  512 (x,y)  maximum local group size for   19
      WORK_GROUP_SIZE_ARB                           64 (z)     compute shaders with variable
                                                               group size (per dimension)
    MAX_COMPUTE_VARIABLE_      Z+    GetIntegerv    512        maximum number of invocations  19
      WORK_GROUP_                                              in a group for compute shaders
      INVOCATIONS_ARB                                          with variable group size

    In table 23.73, rename entries for "MAX_COMPUTE_WORK_GROUP_SIZE" and
    "MAX_COMPUTE_WORK_GROUP_INVOCATIONS" to use the labels
    "MAX_COMPUTE_FIXED_GROUP_SIZE_ARB" and
    "MAX_COMPUTE_FIXED_GROUP_INVOCATIONS_ARB", respectively.  Also modify the
    description of these entries to refer to "compute shaders with fixed group
    size".

Issues

    (1) If a compute shader declares a workgroup size, can it be dispatched
        using OpenGL APIs accepting an explicit workgroup size as part of the
        command?  If so, what happens?

      RESOLVED:  No.  Attempting to do so will generate an INVALID_OPERATION
      error.

      Since the fixed workgroup size may affect the compilation of the shader
      and the value of certain built-in constants, having the OpenGL API
      override the workgroup size baked into the compute shader seems
      suspect.  We could conceivably allow an explicit workgroup size in the
      OpenGL API and require that it match the workgroup size baked into the
      compute shader, but doing so seems to be of limited value.

    (2) If a compute shader doesn't declare a workgroup size, can it be
        dispatched using OpenGL APIs that do not accept an explicit workgroup
        size as part of the command?  If so, what happens?

      RESOLVED:  No.  Attempting to do so will generate an INVALID_OPERATION
      error.

      We could theoretically treat this case as allowing OpenGL
      implementations to pick a workgroup size that "works well" on a
      particular piece of hardware.  However, that wouldn't resolve the
      question of what the "num_groups" arguments to DispatchCompute would
      mean if the group size were implementation-dependent.  One could
      intepret the "num_groups" arguments as specifying the number of
      *invocations* in each dimension, as though the group size were 1x1x1.
      But it's just easier to make this condition an error, as we do for APIs
      attempting to override the group size of a compute shader.

    (3) What new GLSL built-ins should we provide to expose the group size
        specified in the OpenGL API?

      RESOLVED:  We will provide a new built-in variable exposing the group
      size specified in the API.  The name choice is potentially tricky, since
      we now have two different "workgroup size" variables -- a previously
      existing constant for the fixed workgroup size and now a second input
      for the variable workgroup size specified in the API.  We choose the
      name "gl_LocalGroupSizeARB" here, which seems to fit reasonably well with
      existing inputs such as "gl_LocalInvocationID".

      If we had provided this functionality in the original compute shader
      extension, maybe we could have only had "gl_LocalGroupSizeARB"?
      However, the constant "gl_WorkGroupSize" would still be useful for
      sizing built-in arrays for shaders with a fixed workgroup size.  For
      example, a shader might want to declare a shared variable with one
      instance per workgroup invocation, such as:

        shared float shared_values[gl_WorkGroupSize.x * gl_WorkGroupSize.y *
                                   gl_WorkGroupSize.z];

      Such declarations would be illegal using the input
      "gl_LocalGroupSizeARB".

    (4) Do we need to modify the behavior of existing GLSL built-ins for
        compute shaders without an explicit workgroup size?

      RESOLVED:  No, not really.

      The constant gl_WorkGroupSize seems like it would be affected by
      omitting an explicit workgroup size.  However, it is already an error
      to use gl_WorkGroupSize in a shader before a workgroup size layout
      qualifier is declared.  That would make its use illegal in shaders where
      workgroup size layout qualifiers are not declared at all.

      We do need to make minor modifications to the language describing other
      built-in inputs such as gl_LocalInvocationIndex, that are today defined
      to be a function of the constant gl_WorkGroupSize.  We modify these
      definitions to use the input gl_LocalGroupSizeARB instead.

    (5) Should we provide a function (e.g.,
        DispatchComputeIndirectGroupSizeARB) that takes both a workgroup
        count and a workgroup size from indirect dispatch buffers?  If so,
        what do we do if the workgroup size is not positive or exceeds
        implementation-dependent limits?

      RESOLVED:  No, let's leave this out of this extension.

    (6) Is it necessary for compute shaders to include a "#extension"
        directive to enable this extension in order to link successfully
        without a fixed workgroup size?

      RESOLVED:  Yes, compute shaders will have to use the
      "local_size_variable" layout qualifier to declare a variable workgroup
      size, and an "#extension" directive is required to be able to use that
      layout qualifier.

      In unextended OpenGL 4.3, we get a link error if no shaders in the
      program exercise an existing language feature (declaring the fixed
      workgroup size).  We could have simply removed this error, but the general
      rule for "#extension" is that a user should be able to determine if a
      shader were legal or not simply by examining the source code.

      Note that it is necessary to use "#extension" to use the new built-in
      input (gl_LocalGroupSizeARB) provided by this extension.

    (7) Do we need different implementation-dependent limits for dynamic group
    sizes?

      RESOLVED:  Yes, some implementations of this extension may require lower
      limits for variable local group sizes.  We add new tokens
      MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB and
      MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB to query these limits.
      Implementations must support variable group dimensions of 512/512/64,
      with at least 512 invocations per group.  The minimum limits for fixed
      group sizes in unextended OpenGL 4.3 are 1024/1024/64 with at least 1024
      invocations per group.

    (8) Do we need an explicit query to determine if a program with a compute
    shader has a fixed or variable local group size?

      RESOLVED:  No.  The existing COMPUTE_WORK_GROUP_SIZE query will return
      zero when using a shader with a variable local group size, and will
      always return non-zero values for shaders with a fixed group size.

Revision History

    Revision 9, December 10, 2018 (Jon Leech)
      - Use 'workgroup' consistently throughout (Bug 11723, internal API
        issue 87).

    Revision 8, May 30, 2013 (pbrown)
      - Fix a typo in the MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB description;
        that limit applies only to shaders with variable group sizes.

    Revision 7, May 30, 2013 (pbrown)
      - Mark issue (8) as resolved.

    Revision 6, May 12, 2013 (JohnK)
      - Editorial things:
         - be more consistent/broader with "fixed local group size" language
           (vs. variable), and related, also bringing in another paragraph from
           the core spec.
         - move spec. more toward using bold layout qualifier ids everywhere
         - few minor typos, other tiny changes

    Revision 5, May 8, 2013
      - Assign enum values for new tokens.
      - Add interaction with NV_compute_program5 assembly programs.

    Revision 4, May 7, 2013
      - Add new implementation limits MAX_COMPUTE_VARIABLE_GROUP_SIZE_ARB and
        MAX_COMPUTE_VARIABLE_GROUP_INVOCATIONS_ARB for compute shaders with
        variable group sizes, with minimum values of 512/512/64 and 512,
        respectively.
      - Add new tokens MAX_COMPUTE_FIXED_GROUP_SIZE_ARB and
        MAX_COMPUTE_FIXED_GROUP_INVOCATIONS_ARB for compute shaders with fixed
        group sizes, which are aliased to existing OpenGL 4.3 tokens
        (MAX_COMPUTE_WORK_GROUP_SIZE and MAX_COMPUTE_WORK_GROUP_INVOCATIONS).

    Revision 3, May 4, 2013
      - Add ARB suffixes for the new entry point (DispatchComputeGroupSizeARB)
        and GLSL built-in variable (gl_LocalGroupSizeARB).
      - Add a missing INVALID_OPERATION error to DispatchComputeIndirect,
        which requires a compute shader with a variable local group size.
      - Add new issue (8) about querying if a program with a compute shader
        has a fixed or variable group size.

    Revision 2, May 3, 2013
      - Modify the spec to accept an explicit layout qualifer
        /local_size_variable/ to specify a compute shader with a variable
        local group size instead of inferring it from the lack of fixed-size
        layout qualifiers.
      - Modify some spec language to refer to the existing and new types of
        compute shaders as having a fixed and variable local group size,
        respectively.
      - Mark various issues as resolved based on work group discussions.
      - Add new issue (7) about different implementation-dependent size limits
        for compute shaders with variable-size work groups.

    Revision 1, January 20, 2013
      - Initial revision.