[mesa.git] / docs / specs / MESA_shader_integer_functions.txt

Name

    MESA_shader_integer_functions

Name Strings

    GL_MESA_shader_integer_functions

Contact

    Ian Romanick <ian.d.romanick@intel.com>

Contributors

    All the contributors of GL_ARB_gpu_shader5

Status

    Supported by all GLSL 1.30 capable drivers in Mesa 12.1 and later

Version

    Version 3, March 31, 2017

Number

    OpenGL Extension #495

Dependencies

    This extension is written against the OpenGL 3.2 (Compatibility Profile)
    Specification.

    This extension is written against Version 1.50 (Revision 09) of the OpenGL
    Shading Language Specification.

    GLSL 1.30 (OpenGL) or GLSL ES 3.00 (OpenGL ES) is required.

    This extension interacts with ARB_gpu_shader5.

    This extension interacts with ARB_gpu_shader_fp64.

    This extension interacts with NV_gpu_shader5.

Overview

    GL_ARB_gpu_shader5 extends GLSL in a number of useful ways.  Much of this
    added functionality requires significant hardware support.  There are many
    aspects, however, that can be easily implmented on any GPU with "real"
    integer support (as opposed to simulating integers using floating point
    calculations).

    This extension provides a set of new features to the OpenGL Shading
    Language to support capabilities of these GPUs, extending the
    capabilities of version 1.30 of the OpenGL Shading Language and version
    3.00 of the OpenGL ES Shading Language.  Shaders using the new
    functionality provided by this extension should enable this
    functionality via the construct

      #extension GL_MESA_shader_integer_functions : require   (or enable)

    This extension provides a variety of new features for all shader types,
    including:

      * support for implicitly converting signed integer types to unsigned
        types, as well as more general implicit conversion and function
        overloading infrastructure to support new data types introduced by
        other extensions;

      * new built-in functions supporting:

        * splitting a floating-point number into a significand and exponent
          (frexp), or building a floating-point number from a significand and
          exponent (ldexp);

        * integer bitfield manipulation, including functions to find the
          position of the most or least significant set bit, count the number
          of one bits, and bitfield insertion, extraction, and reversal;

        * extended integer precision math, including add with carry, subtract
          with borrow, and extenended multiplication;

    The resulting extension is a strict subset of GL_ARB_gpu_shader5.

IP Status

    No known IP claims.

New Procedures and Functions

    None

New Tokens

    None

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

    None.

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

    None.

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

    None.

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

    None.

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

    None.

Additions to Appendix A of the OpenGL 3.2 (Compatibility Profile)
Specification (Invariance)

    None.

Additions to the AGL/GLX/WGL Specifications

    None.

Modifications to The OpenGL Shading Language Specification, Version 1.50
(Revision 09)

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

      #extension GL_MESA_shader_integer_functions : <behavior>

    where <behavior> is as specified in section 3.3.

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

      #define GL_MESA_shader_integer_functions        1


    Modify Section 4.1.10, Implicit Conversions, p. 27

    (modify table of implicit conversions)

                                Can be implicitly
        Type of expression        converted to
        ---------------------   -----------------
        int                     uint, float
        ivec2                   uvec2, vec2
        ivec3                   uvec3, vec3
        ivec4                   uvec4, vec4

        uint                    float
        uvec2                   vec2
        uvec3                   vec3
        uvec4                   vec4

    (modify second paragraph of the section) No implicit conversions are
    provided to convert from unsigned to signed integer types or from
    floating-point to integer types.  There are no implicit array or structure
    conversions.

    (insert before the final paragraph of the section) When performing
    implicit conversion for binary operators, there may be multiple data types
    to which the two operands can be converted.  For example, when adding an
    int value to a uint value, both values can be implicitly converted to uint
    and float.  In such cases, a floating-point type is chosen if either
    operand has a floating-point type.  Otherwise, an unsigned integer type is
    chosen if either operand has an unsigned integer type.  Otherwise, a
    signed integer type is chosen.
    

    Modify Section 5.9, Expressions, p. 57

    (modify bulleted list as follows, adding support for implicit conversion
    between signed and unsigned types)

    Expressions in the shading language are built from the following:

    * Constants of type bool, int, int64_t, uint, uint64_t, float, all vector
      types, and all matrix types.

    ...

    * The operator modulus (%) operates on signed or unsigned integer scalars
      or vectors.  If the fundamental types of the operands do not match, the
      conversions from Section 4.1.10 "Implicit Conversions" are applied to
      produce matching types.  ...


    Modify Section 6.1, Function Definitions, p. 63

    (modify description of overloading, beginning at the top of p. 64)

     Function names can be overloaded.  The same function name can be used for
     multiple functions, as long as the parameter types differ.  If a function
     name is declared twice with the same parameter types, then the return
     types and all qualifiers must also match, and it is the same function
     being declared.  For example,

       vec4 f(in vec4 x, out vec4  y);   // (A)
       vec4 f(in vec4 x, out uvec4 y);   // (B) okay, different argument type
       vec4 f(in ivec4 x, out uvec4 y);  // (C) okay, different argument type

       int  f(in vec4 x, out ivec4 y);  // error, only return type differs
       vec4 f(in vec4 x, in  vec4  y);  // error, only qualifier differs
       vec4 f(const in vec4 x, out vec4 y);  // error, only qualifier differs

     When function calls are resolved, an exact type match for all the
     arguments is sought.  If an exact match is found, all other functions are
     ignored, and the exact match is used.  If no exact match is found, then
     the implicit conversions in Section 4.1.10 (Implicit Conversions) will be
     applied to find a match.  Mismatched types on input parameters (in or
     inout or default) must have a conversion from the calling argument type
     to the formal parameter type.  Mismatched types on output parameters (out
     or inout) must have a conversion from the formal parameter type to the
     calling argument type.

     If implicit conversions can be used to find more than one matching
     function, a single best-matching function is sought.  To determine a best
     match, the conversions between calling argument and formal parameter
     types are compared for each function argument and pair of matching
     functions.  After these comparisons are performed, each pair of matching
     functions are compared.  A function definition A is considered a better
     match than function definition B if:

       * for at least one function argument, the conversion for that argument
         in A is better than the corresponding conversion in B; and

       * there is no function argument for which the conversion in B is better
         than the corresponding conversion in A.

     If a single function definition is considered a better match than every
     other matching function definition, it will be used.  Otherwise, a
     semantic error occurs and the shader will fail to compile.

     To determine whether the conversion for a single argument in one match is
     better than that for another match, the following rules are applied, in
     order:

       1. An exact match is better than a match involving any implicit
          conversion.

       2. A match involving an implicit conversion from float to double is
          better than a match involving any other implicit conversion.

       3. A match involving an implicit conversion from either int or uint to
          float is better than a match involving an implicit conversion from
          either int or uint to double.

     If none of the rules above apply to a particular pair of conversions,
     neither conversion is considered better than the other.

     For the function prototypes (A), (B), and (C) above, the following
     examples show how the rules apply to different sets of calling argument
     types:

       f(vec4, vec4);        // exact match of vec4 f(in vec4 x, out vec4 y)
       f(vec4, uvec4);       // exact match of vec4 f(in vec4 x, out ivec4 y)
       f(vec4, ivec4);       // matched to vec4 f(in vec4 x, out vec4 y)
                             //   (C) not relevant, can't convert vec4 to 
                             //   ivec4.  (A) better than (B) for 2nd
                             //   argument (rule 2), same on first argument.
       f(ivec4, vec4);       // NOT matched.  All three match by implicit
                             //   conversion.  (C) is better than (A) and (B)
                             //   on the first argument.  (A) is better than
                             //   (B) and (C).


    Modify Section 8.3, Common Functions, p. 84

    (add support for single-precision frexp and ldexp functions)

    Syntax:

      genType frexp(genType x, out genIType exp);
      genType ldexp(genType x, in genIType exp);

    The function frexp() splits each single-precision floating-point number in
    <x> into a binary significand, a floating-point number in the range [0.5,
    1.0), and an integral exponent of two, such that:

      x = significand * 2 ^ exponent

    The significand is returned by the function; the exponent is returned in
    the parameter <exp>.  For a floating-point value of zero, the significant
    and exponent are both zero.  For a floating-point value that is an
    infinity or is not a number, the results of frexp() are undefined.  

    If the input <x> is a vector, this operation is performed in a
    component-wise manner; the value returned by the function and the value
    written to <exp> are vectors with the same number of components as <x>.

    The function ldexp() builds a single-precision floating-point number from
    each significand component in <x> and the corresponding integral exponent
    of two in <exp>, returning:

      significand * 2 ^ exponent

    If this product is too large to be represented as a single-precision
    floating-point value, the result is considered undefined.

    If the input <x> is a vector, this operation is performed in a
    component-wise manner; the value passed in <exp> and returned by the
    function are vectors with the same number of components as <x>.


    (add support for new integer built-in functions)

    Syntax:

      genIType bitfieldExtract(genIType value, int offset, int bits);
      genUType bitfieldExtract(genUType value, int offset, int bits);

      genIType bitfieldInsert(genIType base, genIType insert, int offset, 
                              int bits);
      genUType bitfieldInsert(genUType base, genUType insert, int offset, 
                              int bits);

      genIType bitfieldReverse(genIType value);
      genUType bitfieldReverse(genUType value);

      genIType bitCount(genIType value);
      genIType bitCount(genUType value);

      genIType findLSB(genIType value);
      genIType findLSB(genUType value);

      genIType findMSB(genIType value);
      genIType findMSB(genUType value);

    The function bitfieldExtract() extracts bits <offset> through
    <offset>+<bits>-1 from each component in <value>, returning them in the
    least significant bits of corresponding component of the result.  For
    unsigned data types, the most significant bits of the result will be set
    to zero.  For signed data types, the most significant bits will be set to
    the value of bit <offset>+<base>-1.  If <bits> is zero, the result will be
    zero.  The result will be undefined if <offset> or <bits> is negative, or
    if the sum of <offset> and <bits> is greater than the number of bits used
    to store the operand.  Note that for vector versions of bitfieldExtract(),
    a single pair of <offset> and <bits> values is shared for all components.

    The function bitfieldInsert() inserts the <bits> least significant bits of
    each component of <insert> into the corresponding component of <base>.
    The result will have bits numbered <offset> through <offset>+<bits>-1
    taken from bits 0 through <bits>-1 of <insert>, and all other bits taken
    directly from the corresponding bits of <base>.  If <bits> is zero, the
    result will simply be <base>.  The result will be undefined if <offset> or
    <bits> is negative, or if the sum of <offset> and <bits> is greater than
    the number of bits used to store the operand.  Note that for vector
    versions of bitfieldInsert(), a single pair of <offset> and <bits> values
    is shared for all components.

    The function bitfieldReverse() reverses the bits of <value>.  The bit
    numbered <n> of the result will be taken from bit (<bits>-1)-<n> of
    <value>, where <bits> is the total number of bits used to represent
    <value>.

    The function bitCount() returns the number of one bits in the binary
    representation of <value>.

    The function findLSB() returns the bit number of the least significant one
    bit in the binary representation of <value>.  If <value> is zero, -1 will
    be returned.

    The function findMSB() returns the bit number of the most significant bit
    in the binary representation of <value>.  For positive integers, the
    result will be the bit number of the most significant one bit.  For
    negative integers, the result will be the bit number of the most
    significant zero bit.  For a <value> of zero or negative one, -1 will be
    returned.


    (support for unsigned integer add/subtract with carry-out)

    Syntax:

      genUType uaddCarry(genUType x, genUType y, out genUType carry);
      genUType usubBorrow(genUType x, genUType y, out genUType borrow);

    The function uaddCarry() adds 32-bit unsigned integers or vectors <x> and
    <y>, returning the sum modulo 2^32.  The value <carry> is set to zero if
    the sum was less than 2^32, or one otherwise.

    The function usubBorrow() subtracts the 32-bit unsigned integer or vector
    <y> from <x>, returning the difference if non-negative or 2^32 plus the
    difference, otherwise.  The value <borrow> is set to zero if x >= y, or
    one otherwise.


    (support for signed and unsigned multiplies, with 32-bit inputs and a
     64-bit result spanning two 32-bit outputs)

    Syntax:

      void umulExtended(genUType x, genUType y, out genUType msb, 
                        out genUType lsb);
      void imulExtended(genIType x, genIType y, out genIType msb,
                        out genIType lsb);

    The functions umulExtended() and imulExtended() multiply 32-bit unsigned
    or signed integers or vectors <x> and <y>, producing a 64-bit result.  The
    32 least significant bits are returned in <lsb>; the 32 most significant
    bits are returned in <msb>.


GLX Protocol

    None.

Dependencies on ARB_gpu_shader_fp64

    This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
    of implicit conversions supported in the OpenGL Shading Language.  If more
    than one of these extensions is supported, an expression of one type may
    be converted to another type if that conversion is allowed by any of these
    specifications.

    If ARB_gpu_shader_fp64 or a similar extension introducing new data types
    is not supported, the function overloading rule in the GLSL specification
    preferring promotion an input parameters to smaller type to a larger type
    is never applicable, as all data types are of the same size.  That rule
    and the example referring to "double" should be removed.


Dependencies on NV_gpu_shader5

    This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
    of implicit conversions supported in the OpenGL Shading Language.  If more
    than one of these extensions is supported, an expression of one type may
    be converted to another type if that conversion is allowed by any of these
    specifications.

    If NV_gpu_shader5 is supported, integer data types are supported with four
    different precisions (8-, 16, 32-, and 64-bit) and floating-point data
    types are supported with three different precisions (16-, 32-, and
    64-bit).  The extension adds the following rule for output parameters,
    which is similar to the one present in this extension for input
    parameters:

       5. If the formal parameters in both matches are output parameters, a
          conversion from a type with a larger number of bits per component is
          better than a conversion from a type with a smaller number of bits
          per component.  For example, a conversion from an "int16_t" formal
          parameter type to "int"  is better than one from an "int8_t" formal
          parameter type to "int".

    Such a rule is not provided in this extension because there is no
    combination of types in this extension and ARB_gpu_shader_fp64 where this
    rule has any effect.


Errors

    None


New State

    None

New Implementation Dependent State

    None

Issues

    (1) What should this extension be called?

      UNRESOLVED.  This extension borrows from GL_ARB_gpu_shader5, so creating
      some sort of a play on that name would be viable.  However, nothing in
      this extension should require SM5 hardware, so such a name would be a
      little misleading and weird.

      Since the primary purpose is to add integer related functions from
      GL_ARB_gpu_shader5, call this extension GL_MESA_shader_integer_functions
      for now.

    (2) Why is some of the formatting in this extension weird?

      RESOLVED: This extension is formatted to minimize the differences (as
      reported by 'diff --side-by-side -W180') with the GL_ARB_gpu_shader5
      specification.

    (3) Should ldexp and frexp be included?

      RESOLVED: Yes.  Few GPUs have native instructions to implement these
      functions.  These are generally implemented using existing GLSL built-in
      functions and the other functions provided by this extension.

    (4) Should umulExtended and imulExtended be included?

      RESOLVED: Yes.  These functions should be implementable on any GPU that
      can support the rest of this extension, but the implementation may be
      complex.  The implementation on a GPU that only supports 32bit x 32bit =
      32bit multiplication would be quite expensive.  However, many GPUs
      (including OpenGL 4.0 GPUs that already support this function) have a
      32bit x 16bit = 48bit multiplier.  The implementation there is only
      trivially more expensive than regular 32bit multiplication.

    (5) Should the pack and unpack functions be included?

      RESOLVED: No.  These functions are already available via
      GL_ARB_shading_language_packing.

    (6) Should the "BitsTo" functions be included?

      RESOLVED: No.  These functions are already available via
      GL_ARB_shader_bit_encoding.

Revision History

    Rev.      Date     Author    Changes
    ----  -----------  --------  -----------------------------------------
     3    31-Mar-2017  Jon Leech Add ES support (OpenGL-Registry/issues/3)
     2     7-Jul-2016  idr       Fix typo in #extension line
     1    20-Jun-2016  idr       Initial version based on GL_ARB_gpu_shader5.