xref: /third_party/openGLES/extensions/ARB/ARB_shader_subroutine.txt

Name

    ARB_shader_subroutine

Name Strings

    GL_ARB_shader_subroutine

Contact

    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)

Contributors

    Barthold Lichtenbelt, NVIDIA
    Bill Licea-Kane, AMD
    Bruce Merry, ARM
    Eric Werness, NVIDIA
    Graham Sellers, AMD
    Greg Roth, NVIDIA
    Nick Haemel, AMD
    Pat Brown, NVIDIA
    Pierre Boudier, AMD
    Piers Daniell, NVIDIA

Notice

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

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL Working Group. For
    extensions which have been promoted to a core Specification, fixes will
    first appear in the latest version of that core Specification, and will
    eventually be backported to the extension document. This policy is
    described in more detail at
        https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Status

    Complete. Approved by the ARB at the 2010/01/22 F2F meeting.
    Approved by the Khronos Board of Promoters on March 10, 2010.

Version

    Last Modified Date:         02/28/2014
    Revision:                   19

Number

    ARB Extension #90

Dependencies

    This extension is written against the OpenGL 3.2 core specification and
    version 1.50 of the GLSL specification.

    ARB_gpu_shader5 is required.

    This extension interacts with NV_gpu_program5.

    This extension interacts trivially with EXT_separate_shader_objects.

Overview

    This extension adds support to shaders for "indirect subroutine calls", 
    where a single shader can include many subroutines and dynamically select
    through the API which subroutine is called from each call site. 
    Switching subroutines dynamically in this fashion can avoid the cost of 
    recompiling and managing multiple shaders, while still retaining most of
    the performance of specialized shaders.

IP Status

    No known IP claims.

New Procedures and Functions

    int GetSubroutineUniformLocation(uint program, enum shadertype, 
                                     const char *name);
    uint GetSubroutineIndex(uint program, enum shadertype,
                            const char *name);
    void GetActiveSubroutineUniformiv(uint program, enum shadertype,
                                      uint index, enum pname, int *values);
    void GetActiveSubroutineUniformName(uint program, enum shadertype,
                                        uint index, sizei bufsize,
                                        sizei *length, char *name);
    void GetActiveSubroutineName(uint program, enum shadertype, uint index, 
                                 sizei bufsize, sizei *length, char *name);
    void UniformSubroutinesuiv(enum shadertype, sizei count,
                               const uint *indices);
    void GetUniformSubroutineuiv(enum shadertype, int location,
                                 uint *params);
    void GetProgramStageiv(uint program, enum shadertype, 
                           enum pname, int *values);

New Tokens

    Accepted by the <pname> parameter of GetProgramStageiv: 

        ACTIVE_SUBROUTINES                              0x8DE5
        ACTIVE_SUBROUTINE_UNIFORMS                      0x8DE6
        ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS             0x8E47
        ACTIVE_SUBROUTINE_MAX_LENGTH                    0x8E48
        ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH            0x8E49

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

        MAX_SUBROUTINES                                 0x8DE7
        MAX_SUBROUTINE_UNIFORM_LOCATIONS                0x8DE8

    Accepted by the <pname> parameter of GetActiveSubroutineUniformiv:

        NUM_COMPATIBLE_SUBROUTINES                      0x8E4A
        COMPATIBLE_SUBROUTINES                          0x8E4B
        UNIFORM_SIZE
        UNIFORM_NAME_LENGTH
        

Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation)

    Add a section "Subroutine Uniform Variables" after Section 2.11.4,
    "Uniform Variables"

    Subroutine uniform variables are similar to uniform variables, except they
    are context state rather than program state. Having subroutine uniforms be
    context state allows them to have different values if the program is used
    in multiple contexts simultaneously.  There is a set of subroutine
    uniforms for each shader stage.

    The command

        int GetSubroutineUniformLocation(uint program, enum shadertype, 
                                         const char *name);
        
    will return the location of the subroutine uniform variable <name> in the
    shader stage of type <shadertype> attached to <program>, with behavior otherwise
    identical to GetUniformLocation.  The value -1 will be returned if <name>
    is not the name of an active subroutine uniform.  Active subroutine
    locations are assigned using consecutive integers in the range from zero
    to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS minus one for the shader
    stage.  There is an implementation-dependent limit on the number of active
    subroutine uniform locations in each shader stage; a program will fail to
    link if the number of subroutine uniform locations required is greater
    than the value of MAX_SUBROUTINE_UNIFORM_LOCATIONS.  If <program> has not
    been successfully linked, the error INVALID_OPERATION will be generated.
    For active subroutine uniforms declared as arrays, the declared array
    elements are assigned consecutive locations.

    Each function in a shader associated with a subroutine type is considered
    an active subroutine, unless the compiler conclusively determines that the
    function could never be assigned to an active subroutine uniform.  Each
    active subroutine will be assigned an unsigned integer subroutine index
    that is unique to the shader stage.  This index can be queried with the
    command

        uint GetSubroutineIndex(uint program, enum shadertype,
                                const char *name);

    where <name> is the null-terminated name of a function in the shader stage
    of type <shadertype> attached to <program>.  Subroutine indices are assigned using
    consecutive integers in the range from zero to the value of
    ACTIVE_SUBROUTINES minus one for the shader stage.  The value INVALID_INDEX will
    be returned if <name> is not the name of an active subroutine in the
    shader stage.  After the program has been linked, the subroutine index
    will not change unless the program is re-linked.

    There is an implementation-dependent limit on the number of active
    subroutines in each shader stage; a program will fail to link if the
    number of subroutines is greater than the maximum subroutine count
    (the value of MAX_SUBROUTINES).

    Information about active subroutine uniforms can be obtained by calling

        void GetActiveSubroutineUniformiv(uint program, enum shadertype,
                                          uint index, enum pname, int *values);
        void GetActiveSubroutineUniformName(uint program, enum shadertype,
                                            uint index, sizei bufsize,
                                            sizei *length, char *name);

    <program> and <shadertype> specify the program and shader stage.  <index>
    must be an active subroutine uniform index in the range from zero to the
    value of ACTIVE_SUBROUTINE_UNIFORMS minus one for the shader stage.  If <index>
    is greater than or equal to the value of ACTIVE_SUBROUTINE_UNIFORMS, the
    error INVALID_VALUE is generated.

    For GetActiveSubroutineUniformiv, <pname> identifies a property of the
    active subroutine uniform being queried.  If <pname> is
    NUM_COMPATIBLE_SUBROUTINES, a single integer indicating the number of
    subroutines that can be assigned to the uniform is returned in <values>.
    If <pname> is COMPATIBLE_SUBROUTINES, an array of integers is returned in
    <values>, with each integer specifying the index of an active subroutine
    that can be assigned to the selected subroutine uniform.  The number of
    integers returned is the same as the value returned for
    NUM_COMPATIBLE_SUBROUTINES.  If <pname> is UNIFORM_SIZE, a single integer
    is returned in <values>.  If the selected subroutine uniform is an array,
    the declared size of the array is returned; otherwise, one is returned.
    If <pname> is UNIFORM_NAME_LENGTH, a single integer specifying the length
    of the subroutine uniform name (including the terminating null character)
    is returned in <values>.

    For GetActiveSubroutineUniformName, the uniform name is returned as a
    null-terminated string in <name>.  The actual number of characters written
    into <name>, excluding the null terminator is returned in <length>.  If
    <length> is NULL, no length is returned.  The maximum number of characters
    that may be written into <name>, including the null terminator, is
    specified by <bufsize>.  The length of the longest subroutine uniform name
    in <program> and <shadertype> is given by the value of
    ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH, which can be queried with
    GetProgramStageiv.

    The name of an active subroutine can be queried given its subroutine
    index with the command:

        void GetActiveSubroutineName(uint program, enum shadertype,
                                     uint index, sizei bufsize,
                                     sizei *length, char *name);

    <program> and <shadertype> specify the program and shader stage.  <index>
    must be an active subroutine index in the range from zero to the value of
    ACTIVE_SUBROUTINES minus one for the shader stage.  If <index> is greater than
    or equal to the value of ACTIVE_SUBROUTINES, the error INVALID_VALUE is
    generated.  The name of the selected subroutine is returned as a
    null-terminated string in <name>. The actual number of characters written
    into <name>, excluding the null terminator, is returned in <length>. If
    <length> is NULL, no length is returned. The maximum number of characters
    that may be written into <name>, including the null terminator, is
    specified by <bufsize>.  The length of the longest subroutine name in
    <program> and <shadertype> is given by the value of
    ACTIVE_SUBROUTINE_MAX_LENGTH, which can be queried with GetProgramStageiv.

    The command

        void UniformSubroutinesuiv(enum shadertype, sizei count,
                                   const uint *indices);

    will load all active subroutine uniforms for shader stage <shadertype>
    with subroutine indices from <indices>, storing <indices>[i] into the
    uniform at location i.  If <count> is not equal to the value of
    ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the program currently in use at
    shader stage <shadertype>, or if any value in <indices> is greater than or
    equal to the value of ACTIVE_SUBROUTINES for the shader stage, the error
    INVALID_VALUE is generated.  If, for any subroutine index being loaded to
    a particular uniform location, the function corresponding to the
    subroutine index was not associated (as defined in Section 6.1.2 of the
    GLSL spec) with the type of the subroutine variable at that location, then
    the error INVALID_OPERATION is generated. If no program is active for
    the shader stage identified by <shadertype>, the error INVALID_OPERATION
    is generated.

    Each subroutine uniform must have at least one subroutine to assign to the
    uniform.  A program will fail to link if any stage has one or more
    subroutine uniforms that has no subroutine associated with the subroutine
    type of the uniform.

    When UseProgram is called, the subroutine uniforms for all shader stages
    are reset to arbitrarily chosen default functions with compatible
    subroutine types.  When UseShaderProgramEXT is called, the subroutine
    uniforms for the shader stage specified by <type> are reset to arbitrarily
    chosen default functions with compatible subroutine types.


Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)

    None.

Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment
Operations and the Frame Buffer)

    None.

Additions to Chapter 5 of the OpenGL 3.2 Specification (Special Functions)

    None.

Additions to Chapter 6 of the OpenGL 3.2 Specification (State and
State Requests)

    Add to Section 6.1.15 (Shader and Program Queries)

    The command
    
        void GetUniformSubroutineuiv(enum shadertype, int location, 
                                     uint *params);

    returns the value of the subroutine uniform at location <location> for
    shader stage <shadertype> of the current program.  If <location> is
    greater than or equal to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS
    for the shader currently in use at shader stage <shadertype>, the error
    INVALID_VALUE is generated.  If no program is active, the error
    INVALID_OPERATION is generated.

    The command

        void GetProgramStageiv(uint program, enum shadertype, 
                               enum pname, int *values);

    returns properties of the program object <program> specific to the
    programmable stage corresponding to <shadertype> in <values>. The
    parameter value to return is specified by <pname>.  If <pname> is
    ACTIVE_SUBROUTINE_UNIFORMS, the number of active subroutine variables in
    the stage is returned.  If <pname> is ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS,
    the number of active subroutine variable locations in the stage is
    returned.  If <pname> is ACTIVE_SUBROUTINES, the number of active
    subroutines in the stage is returned.  If <pname> is
    ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH or ACTIVE_SUBROUTINE_MAX_LENGTH, the
    length of the longest subroutine uniform or subroutine name, respectively,
    for the stage is returned.  The returned name length includes space for a
    null terminator.  If there is no shader of type <shadertype> in <program>,
    the values returned will be consistent with a shader with no subroutines
    or subroutine uniforms.


Modifications to The OpenGL Shading Language Specification, Version 1.50

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

      #extension GL_ARB_shader_subroutine : <behavior>

    where <behavior> is as specified in section 3.3.

    In section 3.6, p.14 (Keywords)

    Add subroutine to the list of reserved keywords.

    Modify Section 6.1.1 (Function Calling Conventions)

    (modify the last paragraph of the section, p. 66, to forbid potential
    recursion via subroutines) Recursion is not allowed, not even statically.
    Static recursion is present if the static function-call graph of a program
    contains cycles.  This includes all potential function calls through
    variables declared as subroutine uniform (described below).  It is an
    error if a single compilation unit (shader) contains either static
    recursion or the potential for recursion through subroutine variables.

    Add a new Section 6.1.2 (Subroutines)

    Subroutines provide a mechanism allowing shaders to be compiled in a
    manner where the target of one or more function calls can be changed at
    run-time without requiring any shader recompilation.  For example, a
    single shader may be compiled with support for multiple illumination
    algorithms to handle different kinds of lights or surface materials.  An
    application using such a shader may switch illumination algorithms by
    changing the value of its subroutine uniforms.  To use subroutines, a
    subroutine type is declared, one or more functions are associated with
    that subroutine type, and a subroutine variable of that type is declared.
    The function currently assigned to the variable function is then called by
    using function calling syntax replacing a function name with the name of
    the subroutine variable.  Subroutine variables are assigned to specific
    functions only through commands (UniformSubroutinesuiv) in the OpenGL API.

    Subroutine types can be declared using a statement similar to a function 
    declaration, as follows:

        subroutine returnType subroutineTypeName(type0 arg0, type1 arg1,
                                                 ..., typen argn);

    Functions may be associated to subroutine types that have a matching 
    prototype by prepending the subroutine types to the function definition:

        subroutine(subroutineTypeName0, ..., subroutineTypeNameN)
        returnType functionName (type0 arg0, type1 arg1, ..., typen argn)
        ... // function body
    
    Subroutine declarations cannot be prototyped. It is an error to prepend
    subroutine(...) to a function declaration. It is an error to declare
    two distinct functions with the same function name within the same shader
    (i.e. overloaded function names) that are both associated to subroutine
    types.

    Subroutine types share a namespace with standard function names.
    Overloading (section 6.1) is not supported for functions that may be
    associated with subroutine types.  A program will fail to link if any
    shader includes two or more functions with the same name, at least one of
    which is associated with a subroutine type.

    Subroutine variables are required to be "subroutine uniforms", and 
    are declared with a specific subroutine type in a subroutine uniform 
    variable declaration:

        subroutine uniform subroutineTypeName subroutineVarName;

    and are called the same way simple functions are called. Subroutine
    variables may be declared as explicitly-sized arrays, which can be 
    dynamically indexed at use.

    Subroutine variables are associated to functions declared with the
    same subroutine type with the UniformSubroutinesuiv command in the OpenGL
    API. When a subroutine variable (or an element of a subroutine variable
    array) is associated to a particular function, all function calls through
    that variable will call that particular function.

Additions to the AGL/GLX/WGL Specifications

    None.

GLX Protocol

    None.

Errors

    The error INVALID_OPERATION is generated by GetSubroutineUniformLocation
    if the program object identified by <program> has not been successfully
    linked.

    The error INVALID_VALUE is generated by GetActiveSubroutineUniformiv or
    GetActiveSubroutineUniformName if <index> is greater than or equal to the
    value of ACTIVE_SUBROUTINE_UNIFORMS for the shader stage.

    The error INVALID_VALUE is generated by GetActiveSubroutineName if <index>
    is greater than or equal to the value of ACTIVE_SUBROUTINES for the shader
    stage.

    The error INVALID_VALUE is generated by UniformSubroutinesuiv if <count>
    is not equal to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the
    shader stage <shadertype>.

    The error INVALID_VALUE is generated by UniformSubroutinesuiv if any value
    in <indices> is greater than or equal to the value of ACTIVE_SUBROUTINES
    for the shader stage.

    The error INVALID_OPERATION is generated by UniformSubroutinesuiv if any
    subroutine index in <indices> identifies a subroutine not associated with
    the type of the subroutine uniform variable assigned to the corresponding
    location.

    The error INVALID_OPERATION is generated by UniformSubroutinesuiv if no
    program is active.

    The error INVALID_VALUE is generated by GetUniformSubroutineuiv if
    <location> is greater than or equal to the value of
    ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the shader stage.

    The error INVALID_OPERATION is generated by GetUniformSubroutineuiv if no
    program is active for the shader stage identified by <shadertype>.


New State

    (add to table 6.28, Program Object State, p. 293)

                                                               Initial
    Get Value                     Type        Get Command       Value  Description                  Sec.  
    ---------------------------   ----------  -----------      ------- ---------------------------  ------
    ACTIVE_SUBROUTINE_UNIFORM_    5xZ+        GetProgram-         0    Number of subroutine unif.   2.11.4
      LOCATIONS                               Stageiv                  locations in the shader
    ACTIVE_SUBROUTINE_UNIFORMS    5xZ+        GetProgram-         0    Number of subroutine unif.   2.11.4
                                              Stageiv                  variables in the shader
    ACTIVE_SUBROUTINES            5xZ+        GetProgram-         0    Number of subroutine         2.11.4
                                              Stageiv                  functions in the shader
    ACTIVE_SUBROUTINE_UNIFORM_    5xZ+        GetProgram-         0    Maximum subroutine uniform   2.11.4
      MAX_LENGTH                              Stageiv                  name length
    ACTIVE_SUBROUTINE_MAX_LENGTH  5xZ+        GetProgram-         0    Maximum subroutine name      2.11.4
                                              Stageiv                  length
    NUM_COMPATIBLE_SUBROUTINES    5x0*xZ+     GetActiveSub-       -    Number of subroutines comp-  2.11.4
                                              routineUniformiv         atible with a sub. uniform
    COMPATIBLE_SUBROUTINES        5x0*x0*xZ+  GetActiveSub-       -    List of subroutines comp-    2.11.4
                                              routineUniformiv         atible with a sub. uniform
    UNIFORM_SIZE                  5x0*xZ+     GetActiveSub-       -    Number of elements in sub.   2.11.4
                                              routineUniformiv         uniform array
    UNIFORM_NAME_LENGTH           5x0*xZ+     GetActiveSub-       -    Length of sub. uniform name  2.11.4
                                              routineUniformiv
    -                             5x0*xS      GetActiveSub-       -    Sub. uniform name string     2.11.4
                                              routineUniformName
    -                             5x0*xS      GetActiveSub-       -    Length of subroutine name    2.11.4
                                              routineName
    -                             5x0*xS      GetActiveSub-       -     Subroutine name string      2.11.4
                                              routineName

    (For the above, the "5" is indicates separate state for each of the five
    shader stages in the program.)


New Implementation Dependent State

                                                          Minimum
    Get Value                      Type  Get Command       Value   Description           Sec.   Attrib
    -----------------------------  ----  ---------------  -------  --------------------- ------ ------
    MAX_SUBROUTINES                 Z+   GetIntegerv        256    Maximum number of     2.14.1   -   
                                                                   subroutines per
                                                                   shader stage
    MAX_SUBROUTINE_UNIFORM_         Z+   GetIntegerv       1024    Maximum number of     2.X.5    -
     LOCATIONS                                                     subroutine uniform
                                                                   locations per stage


Dependencies on NV_gpu_program5:

    If NV_gpu_program5 is supported, the following edits are made to extend
    the assembly programming model documented in the NV_gpu_program4 extension
    and extended by NV_gpu_program5.  No "OPTION" line is required; the
    following capability is implied by NV_gpu_program5 program headers such as
    "!!NVfp5.0".

    New Procedures and Functions

    void ProgramSubroutineParametersuivNV(enum target, sizei count, 
                                          const uint *params);
    void GetProgramSubroutineParameteruivNV(enum target, uint index,
                                            uint *param);

    New Tokens

    Accepted by the <pname> parameter of GetProgramivARB: 

        MAX_PROGRAM_SUBROUTINE_PARAMETERS_NV            0x8F44
        MAX_PROGRAM_SUBROUTINE_NUM_NV                   0x8F45

    (Modify "Section 2.14.1" of the ARB_vertex_program specification,
    describing program parameters.)

    Each program target has an associated array of program subroutine
    parameters. Unlike program local parameters, program subroutine parameters
    are context state rather than program state. Program subroutine parameters
    are scalar unsigned integer values that correspond to "SUBROUTINENUM"
    declarations in a program. The number of scalars is given by the
    implementation-dependent value MAX_PROGRAM_SUBROUTINE_PARAMETERS_NV.
    The command

        void ProgramSubroutineParametersuivNV(enum target, sizei count, 
                                              const uint *params);

    updates the values of all program subroutine parameters used by the 
    currently bound program for the given program target <target>. <params> 
    points to an array of <count> values, where the first value is used to 
    update the program subroutine parameter numbered zero and the last value 
    is used to update the program subroutine parameter numbered <count> - 1. 
    The error INVALID_VALUE is generated if <count> is not equal to one plus 
    the maximum program subroutine parameter index used in the currently bound 
    program.

    Program subroutine parameters for a given target are reset to arbitrary 
    defaults when the program string is respecified, and when BindProgram is 
    called to bind a program to that target, even if the specified program is
    already bound. 

    The error INVALID_OPERATION is generated by
    ProgramSubroutineParametersuivNV if, for any number <i> in [0, <count>),
    program.subroutine[<i>] is a live parameter of a certain SUBROUTINETYPE,
    and <params>[<i>] is not a SUBROUTINENUM that was associated to that
    SUBROUTINETYPE as described in Section 2.X.5.

    Modify Section 2.X.2 of NV_gpu_program4, Program Grammar

    If a program begins with a header string defined by GL_NV_gpu_program5, 
    the following modifications apply to the program grammar:

    <FlowInstruction>       ::= <BRAop_instruction>
                              | <FLOWCCop_instruction>
                              | <IFop_instruction>
                              | <REPop_instruction>
                              | <ENDFLOWop_instruction>
                              | <CALI_instruction>

    <namingStatement>       ::= <varMods> <ATTRIB_statement>
                              | <varMods> <PARAM_statement>
                              | <varMods> <TEMP_statement>
                              | <varMods> <OUTPUT_statement>
                              | <varMods> <BUFFER_statement>
                              | <ALIAS_statement>
                              | <SUBROUTINETYPE_statement>
                              | <SUBROUTINE_statement>

    <labelList>             ::= <identifier>
                              | <identifier> "," <labelList>

    <labelInitList>         ::= /* empty */
                              | <labelList>

    <SUBROUTINETYPE_statement> ::= "SUBROUTINETYPE" <establishName> "{" 
                                <labelInitList> "}"

    <progSubroutineParam>   ::= "program" "." "subroutine" <arrayMemAbs>

    <progSubroutineParams>  ::= <progSubroutineParam>
                              | "program" "." "subroutine" <arrayRange>

    <progSubroutineInitList>::= <progSubroutineParams>
                              | <progSubroutineParams> "," 
                                <progSubroutineInitList>

    <SUBROUTINE_statement>  ::= "SUBROUTINE" <establishedName> <establishName> 
                                "=" <progSubroutineParam>
                              | "SUBROUTINE" <establishedName> <establishName> 
                                <optArraySize> "=" "{" <progSubroutineInitList> 
                                "}"

    <CALIop>                ::= "CALI"

    <CALI_instruction>      ::= <CALIop> <opModifiers> <subroutineVarName> 
                                <optArrayMem> <optBranchCond>

    <instLabel>             ::= <identifier>
                              | <identifier> "SUBROUTINENUM" "(" <int> ")"


    Modify Section 2.X.4, Program Execution Environment

    (Update the instruction set table to add CALI)

      Instr-      Modifiers 
      uction  V  F I C S H D  Out Inputs    Description
      ------- -- - - - - - -  --- --------  --------------------------------
      CALI    50 - - - - - -  -   c         indirect subroutine call

    Modify Section 2.X.5 (Program Flow Control) of the NV_gpu_program4
    specification

    (Add after the description of subroutines)

    Subroutines may be called indirectly using the CALI instruction. An 
    "indirect" call will transfer control to one of a set of labels, where
    the specific label that is used in a particular program invocation is
    set through a "subroutine" parameter (see Section 2.14.1).

    Functions that will be used for indirect subroutine calls must all be
    assigned a unique unsigned integer SUBROUTINENUM using the modified
    <instLabel> grammar rule. 

    A <SUBROUTINETYPE_statement> associates one or more subroutine labels with
    a "type". For example:

      SUBROUTINETYPE Hero { batman, robin };

    creates a SUBROUTINETYPE named "Hero" (if it does not already exist) and
    adds the subroutines whose labels are "batman" and "robin" to the
    SUBROUTINETYPE. 

    A "subroutine" parameter is a special type of program parameter whose value
    refers to one of a set of subroutines, selected by the API. A subroutine is
    given a SUBROUTINETYPE when it is declared, and it may refer to any label
    of that type. Continuing this example:

      SUBROUTINETYPE Hero { superman, wolverine };
      SUBROUTINETYPE Hero { batman, robin };
      SUBROUTINETYPE GothamHero { batman, robin };

      # anyHero may "point to" any Hero
      SUBROUTINE Hero anyHero = program.subroutine[0];
      # gothamHero may "point to" any GothamHero
      SUBROUTINE GothamHero gothamHero = program.subroutine[1];

      batman SUBROUTINENUM(0):
        ...
      robin SUBROUTINENUM(1):
        ...
      superman SUBROUTINENUM(2):
        ...
      wolverine SUBROUTINENUM(3):
        ...
      
      main:
      # could call any of the four heros
      CALI anyHero;
      # could call either batman or robin
      CALI gothamHero;

    Program subroutine parameters are assigned to labels by setting the 
    corresponding SUBROUTINENUMs via ProgramSubroutineParametersuivNV. For
    example, 
    
      uint params[2] = {2, 0};
      ProgramSubroutineParametersuivNV(target, 2, params);

    would assign program.subroutine[0] (and therefore "anyHero") to "superman",
    and program.subroutine[1] (and therefore "gothamHero") to "batman".

    All SUBROUTINENUMs must be greater than or equal to zero, and less than the 
    value of MAX_PROGRAM_SUBROUTINE_NUM_NV. A label may be assigned to multiple 
    SUBROUTINETYPEs. A program subroutine parameter may only be assigned to 
    subroutine variables of a single SUBROUTINETYPE.

    Programs that may potentially cause infinite recursion through indirect
    calls will fail to compile.


    Section 2.X.8.Z, CALI:  Indirect Subroutine Call

    The CALI instruction conditionally transfers control to the instruction
    following some label, as described in CAL. The determination of which
    label is used is described in Section 2.X.5 (Program Flow Control).

    Add to Chapter 6 (State and State Requests)

    The command

      void GetProgramSubroutineParameteruivNV(enum target, uint index,
                                              uint *params);

    obtains the current value for the program subroutine parameter numbered
    <index> for the given program target <target>, and places the single 
    unsigned integer value in the array <params>.  The error INVALID_ENUM is 
    generated if <target> specifies a nonexistent program target or a program 
    target that does not support program environment parameters.  The error 
    INVALID_VALUE is generated if <index> is greater than or equal to the
    implementation-dependent number of supported program subroutine parameters
    for the program target.

    Add various new conditions by which a program string would fail to load.

    The error INVALID_ENUM is generated by GetProgramSubroutineParameteruivNV 
    and ProgramSubroutineParametersuivNV if <target> specifies a nonexistent 
    program target.

    The error INVALID_VALUE is generated by GetProgramSubroutineParameteruivNV
    if <index> is greater than or equal to the max number of program subroutine 
    parameters, and by ProgramSubroutineParametersuivNV if <count> is <count>
    is not equal to one plus the maximum program subroutine parameter index used
    in the currently bound program.

    The error INVALID_OPERATION is generated by
    ProgramSubroutineParametersuivNV if, for any number <i> in [0, <count>),
    program.subroutine[<i>] is a live parameter of a certain SUBROUTINETYPE,
    and <params>[<i>] is not a SUBROUTINENUM that was associated to that
    SUBROUTINETYPE as described in Section 2.X.5.

    Add new implementation dependent state
                                                             Minimum
    Get Value                         Type  Get Command       Value   Description           Sec.   Attrib
    --------------------------------  ----  ---------------  -------  --------------------- ------ ------
    MAX_PROGRAM_SUBROUTINE_            Z+   GetProgramivARB   1024    Maximum number of     2.14.1   -   
      PARAMETERS_NV                                                   program subroutine
                                                                      parameters
    MAX_PROGRAM_SUBROUTINENUM_NV       Z+   GetProgramivARB    256    Maximum SUBROUTINENUM 2.X.5    -
                                                                      value


Dependencies on EXT_separate_shader_objects

    If EXT_separate_shader_objects is not supported, remove references to
    UseShaderProgramEXT.

Issues

    (1) What terms should we use to describe the various data types and
    concepts in this specification?

    RESOLVED:  This extension uses mechanisms similar to function pointers in
    C.  We aren't directly exposing function pointers, but are instead using a
    function pointer-like data type.  We are using the term "subroutine" to
    qualify various concepts in this extension.  The function pointer type is
    referred to as a "subroutine type".  Integer indices used to identify
    functions that can be assigned to a function pointer type are referred to
    as "subroutine indices".  Uniforms that can hold function pointer values
    are referred to as "subroutine uniforms".

    We considered using the term "interfaces", but were concerns about
    confusion with object-oriented programming models -- the model we are
    using is not object-oriented.  Referring instead to these limited function
    pointers as "subroutines" avoids this confusion and matches its use in
    similar circumstances. The term is not currently used in any GLSL nor
    OpenGL specification.

    (2) What happens if you try to link a program that has active subroutines
    that have no subroutines that can be assigned ot them?
    
    RESOLVED: Attempting to link a program that calls a function pointer
    with no potential associations produces a link error.

    (3) What happens if the app specifies a bad subroutine index?

    RESOLVED: There are two different forms of invalid subroutine indices --
    ones that correspond to no subroutine, and ones that correspond to a
    subroutine of the wrong type. If the app specifies a number that
    corresponds to no subroutine, an INVALID_VALUE error is generated. If the
    number corresponds to a subroutine of the wrong type, an INVALID_OPERATION
    error is generated.

    (4) What happens if the shaders change without reassigning subroutine
    associations?

    RESOLVED: The subroutine uniforms will revert to a default function of
    of those associated with it in the shader. The default function chosen
    may be implementation dependent.

    (5) How should subroutine parameters be updated?

    RESOLVED: UniformSubroutinesuivARB requires sending all subroutine
    parameters at once so they can be validated in a single burst. This is
    similar to D3D which goes as far as to require setting all of them in the
    same operation that binds the shader.

    (6) Why is the new "subroutine" state owned by the context rather than
    by the assembly program or GLSL program/shader? 

    RESOLVED: We expect that a common usage of this extension 
    would be to create a so-called "uber-shader" -- a program that can 
    support many different state configurations.  If an application uses
    such a program in multiple contexts, it likely it would not want changes
    to linkage for one context to affect the other context.

    (7) Does that mean other types of uniforms also need to be context state?

    RESOLVED: Apps can choose to share or not share numeric uniform types at
    their discretion using UBO, however for more "opaque" uniform types like 
    samplers it may be desirable to have context state. Such a change is
    beyond the scope of this extension. No effort was made to make subroutine
    uniforms generic enough to support other potential usages. Should such
    emerge, they will define their own unique uniform types.

    (8) GLSL allows function name overloading, how can you query a 
    subroutine location in that case?

    RESOLVED:  Disallow overloading of function names used for subroutine
    functions.

    (9) What sort of implementation-dependent limits apply to subroutines?

    RESOLVED:  There is an limit on the number of subroutines per shader stage
    (MAX_SUBROUTINES) and also a limit on the number of subroutine uniform
    locations (MAX_SUBROUTINE_UNIFORM_LOCATIONS).

    (10) How many subroutine variables be used? Should they be allowed as
    function parameters, structure members, and arrays?

    RESOLVED:  Arrays of subroutine uniforms are allowed.  The spec does not
    currently permit them as function parameters or structure members, as it
    requires subroutine variables be declared as uniforms.  Subroutine
    function parameters can be emulated by declaring a uniform array holding
    all possible subroutines that a shader might want to pass as a parameter
    and then passing an integer index to select a subroutine to call.

    (11) Is the "subroutine" keyword necessary when declaring a subroutine
    uniform?

    RESOLVED:  Yes, "subroutine uniform" in the declaration is required.

    (12) Why don't the new tokens and entry points in this extension have
     "ARB" suffixes like other ARB extensions?

     RESOLVED:  Unlike most ARB extensions, this is a strict subset of
     functionality already approved for the OpenGL core.  This extension
     exists only to support that functionality on older hardware that cannot
     implement all the functionality in that OpenGL version.  Since there are
     no possible behavior changes between the ARB extension and core features,
     source code compatibility is improved by not using suffixes on the
     extension.

    (13) Are compilers permitted to eliminate unreferenced elements at the end
    of an array for subroutine uniforms like they can for regular uniforms?

      RESOLVED:  No, because of differences in the uniform loading APIs.
      Consider the following example:

        uniform float array[10];
        // shader only references array[0..5]

      The GL implementation is permitted to treat "array" as having a size of
      6, but may also use the declared size of 10.  An application may have
      built-in knowledge that "array" has a declared length of 10, and might
      call Uniform1f() with a <count> of 10.  The specified behavior for
      Uniform*() APIs is that any values specified that extend beyond the last
      active element of the array are ignored.  As a result, passing "extra"
      elements to Uniform*() causes no problems; applications don't need to
      query the active size of a uniform array to get correct behavior.

      The subroutine uniform loading API is different, as it accepts a single
      array containing the values for every active uniform.  This allows
      applications to specify the values for all subroutine uniforms in a
      single call, instead of multiple calls for regular uniforms.  However,
      this approach doesn't provide a mechanism for discarding unused array
      elements.  If "array" above was a subroutine uniform and the application
      wrote 10 values into the array it would pass to UniformSubroutinesuiv,
      it might overwrite the values of other subroutines or write off the end
      of the array if the compiler only assigned 6 locations for "array".  If
      unused elements could be eliminated, implementations would have to query
      the active size for each subroutine uniform array, even if they knew the
      declared size up-front.  To avoid the need to always query lengths, we
      instead specify that all elements of an active subroutine array are
      active.

Revision History

    Rev.    Date      Author    Changes
    ----  ----------  --------  ----------------------------------------------
    19    02/28/2014  Jon Leech Restrict error for UniformSubroutinesuiv to  
                                the case where no program stage is active for
                                the shader stage identified by <shadertype>
                                (Bug 11306).

    18    02/10/2011  pbrown    Add a clarification to the GLSL spec language
                                prohibiting potential recursion via subroutine
                                uniforms; a program will fail to link if there
                                is any possible combination of subroutine 
                                uniform values that would result in recursion
                                (bug 7327).

    17    03/29/2010  pbrown    Update issues (1) and (10).

    16    03/21/2010  pbrown    Minor clarification in the NV_gpu_program5
                                interaction that no OPTION is required to
                                use subroutines in assembly programs.

    15    02/08/2010  Jon Leech Minor wording changes for consistency with
                                4.0 specification.

    14    01/30/2010  pbrown    Specify that implementations are not permitted
                                to chop unreferenced elements off the end of
                                a subroutine uniform array like they are with
                                regular uniforms (bug 5978).  Minor 
                                clarification on the meaning of "active
                                subroutines".

    13    01/26/2010  pbrown    Assigned enum values for enums added by most
                                recent edits.

    12    01/20/2010  pbrown    Update state tables to classify per-subroutine
                                and per-subroutine uniform state as "5x" to
                                indicate a separate set of values for each
                                shader stage.

    11    01/18/2010  pbrown    Rename GetActiveSubroutineUniformiv.  Add
                                enums to query the longest subroutine uniform
                                and subroutine names in a stage.  Rename enum
                                NUM_COMPATIBLE_SUBROUTINES.  Change error
                                behavior to allow most queries on unlinked
                                programs and ones without the specified stage
                                (except GetSubroutineUniformLocation).  Added
                                errors in UniformSubroutines and
                                GetUniformSubroutineuiv if no program is
                                active.  Minor spec language cleanups.  All
                                based on review comments in bug 5861.

    10    01/15/2010  pbrown    Significant changes to allow for full
                                discoverability of subroutine uniforms,
                                subroutines, and their locations (bug 5861).
                                Rename the term "subroutine number" to "active
                                subroutine index".  Rename GetSubroutineIndex
                                (was GetSubroutineNumber) and the <indices>
                                parameter of UniformSubroutinesuiv.  Fix
                                prototype of GetSubroutineIndex and other APIs
                                to consistently use "uint".  Add APIs to query
                                properties of active subroutine uniforms
                                (name, associated subroutines).  Separate the
                                notion of subroutine uniform indices and
                                locations just like regular uniforms.  Arrays
                                may have one index but multiple locations.
                                Specify that locations are packed in
                                consecutive locations.  Rename
                                GetSubroutineName to GetActiveSubroutineName
                                to match other enumeration APIs.  Add a query
                                for the number of active subroutine uniform
                                locations, and change the implementation limit
                                to be on active locations instead of indices.
                                Clarify that subroutines in a shader need not
                                be active if there is no active uniform that
                                can call them (bug 5859).  Update state tables
                                and some issues.

     9    01/14/2010  pbrown    Add some more text to the introduction to 
                                subroutines in the GLSL spec section.

     8    12/10/2009  groth     ARBify.

     7    12/10/2009  groth     Correct prototypes and clarify/correct errors.
                                Fix a few state retrieval typos.

     6    10/29/2009  groth     Clarify a number of areas in response to
                                feedback from bmerry.

     5    09/24/2009  groth     Fix typo in GLSL example. Assign enums.

     4    09/17/2009  pbrown    Add implementation-dependent limits on
                                subroutines.  Document some of these limits
                                and restrictions on function overloading and
                                subroutine uniforms with no matching function.

     3    09/16/2009  groth     Resolve issues. A few clarifications.
                                rename interface to subroutine.

     2    09/14/2009  groth     EXTify. move asm changes to dependencies.

     1                jbolz     Internal revisions.