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

Name

    ARB_arrays_of_arrays

Name Strings

    GL_ARB_arrays_of_arrays

Contact

    John Kessenich (cepheus 'at' frii.com)

Contributors

    XXX

Notice

    Copyright (c) 2012-2013 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 on 2012/06/12.

Version

    Last Modified Date: 2012/07/01
    Revision: 7

Number

    ARB Extension #120

Dependencies

    GLSL 1.2 is required.

    OpenGL ?? (Core Profile) specification is required.  (See issues.)

Overview

    Multi-dimensional arrays are a frequently requested feature.  This extension
    removes the restriciton that arrays cannot be formed into arrays, allowing
    arrays of arrays to be declared.  Technically, removing this restriction is 
    all that is necessary to enable this feature, but it is worthwhile showing
    what the result of doing that looks like.

    The following will be true of arrays of arrays

    - They will first class objects.  (They know their size, can be passed by 
      copy-in semantics to functions, etc.)

    - They will only be one-dimensional arrays of other first class objects.
      (arrays are already first class objects).

    - The syntax

        vec4 a[3][2];

      Declares a one-dimensional array of size 3 of one-dimensional arrays of 
      size 2 of vec4s.  Also, these syntaxes do the same thing:

        vec4[2] a[3];
        vec4[3][2] a;

      or, looking at more dimensions, these are all the same

        int a[1][2][3][4][5][6];

        int[1][2][3][4][5][6] a;

        int[4][5][6] a[1][2][3];

      note this latter is equivalent to C, in meaning the same thing, if done as

        typedef int int456[4][5][6];

        int456 a[1][2][3];

      that is, this GLSL proposal matches C behavior in this way.  The type needed for
      both constructors and nameless parameters is:

         int[1][2][3][4][5][6]

    - This type could be declared as a formal parameter in a function prototype as

        void foo(vec4[3][2]);

    - Accessing is done as

        a[x][y]  // x selects which array of size 2 is desired
                 // y selects which vec4 is desired

        a[x]     // this results in a one-dimensional array, with all rights and
                 // priviledges implied

    - The .length() operator works as normal:

        a.length()     // this is 3
        a[x].length()  // this is 2

    - The constructor for the above is

        vec4[3][2](vec4[2](vec4(0.0), vec4(1.0)),   
                   vec4[2](vec4(0.0), vec4(1.0)),   
                   vec4[2](vec4(0.0), vec4(1.0)))

    - Initializers for the above are

        vec4 a[3][2] = vec4[3][2](vec4[2](vec4(0.0), vec4(1.0)),   
                                  vec4[2](vec4(0.0), vec4(1.0)),   
                                  vec4[2](vec4(0.0), vec4(1.0)));

        // or

        vec4 a[3][2] = {vec4[2](vec4(0.0), vec4(1.0)),   
                        vec4[2](vec4(0.0), vec4(1.0)),   
                        vec4[2](vec4(0.0), vec4(1.0))) };

        // or 

        vec4 a[3][2] = {{ vec4(0.0), vec4(1.0) },   
                        { vec4(0.0), vec4(1.0) },   
                        { vec4(0.0), vec4(1.0) }  };  // requires matching nesting of 
                                                      // {} with object's hierarchy


    Note that all the above is naturally already specified in the core 
    specification.


New Procedures and Functions


New Tokens


Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification
(OpenGL Operation)


Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification
(Rasterization)

    None.

Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification
(Per-Fragment Operations and the Framebuffer)

    None.

Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification
(Special Functions)


Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification
(State and State Requests)

    None.

Additions to Chapter 4 of the OpenGL Shading Language Specification, Version
4.20 (Variables and Types)

    Section 4.1.9 Arrays

    Rewrite the sentences "Only one-dimensional arrays may be declared. All 
    basic types and structures can be formed into arrays." as 

    "Arrays only have a single dimension (a single number within "[ ]", 
     however, arrays of arrays can be declared.  All types (basic types, 
     structures, arrays) can be formed into an array."

    "When in transparent memory (like in a uniform block), the layout is that 
     the 'inner' (right-most in declaration) dimensions iterate faster than the 
     out dimensions.  That is, for the above, the order in memory would be:

         low address...a[0][0] a[0][1] a[1][0] a[1][1] a[2][0] a[2][1]...high address"

    Expand the examples in this section by incorporating the declaration and
    use content from the overview section above.

    Add

        vec4 a[3][2];
        a.length()     // this is 3
        a[x].length()  // this is 2

    When the *length* method will return a compile-time constant, the expression 
    in brackets (x above) will be evaluated and subject to the rules required
    for array indexes, but the array will not be deferenced.  Thus, behavior
    is well defined even if the run-time value of the expression is out of bounds.

    Remove the illegal examples of arrays of arrays.

    Add the following:

    "For unsized arrays, only the outermost dimension can be lacking a
    size. A type that includes an unknown array size cannot be formed into
    an array until it gets an explicit size."

    Section 4.1.11 Initializers

    Expand the examples in this section by incorporating the initializer
    content from the overview section above.

    Section 4.3.4 Input Variables

    For this paragraph, keep this introductory text the same

    "Some inputs and outputs are arrayed, meaning that for an interface between 
    two shader stages either the input or output declaration requires an extra 
    level of array indexing for the declarations to match.  

    but rewrite the remainder

    "For example, with 
    the interface between a vertex shader and a geometry shader, vertex shader 
    output variables and geometry shader input variables of the same name must 
    match in type and qualification, except that the vertex shader name cannot 
    be declared as an array while the geometry shader name must be declared 
    as an array, to allow for vertex indexing.  
    It is a link error if a 
    non-arrayed input is not declared with the same type, qualification, and 
    array dimensionality as the matching output.  It is an error if an arrayed 
    input is not declared as an array of the same type and qualification as the 
    corresponding (non-array) output. Symmetrically, it is an error if an 
    arrayed output is not  declared as an array of the same type and 
    qualification as the corresponding (non-array) input."

    instead as 

    "For example, with 
    the interface between a vertex shader and a geometry shader, vertex shader 
    output variables and geometry shader input variables of the same name must 
    match in type and storage qualification, except that the geometry shader will have 
    one more array dimension than the vertex shader, to allow for vertex 
    indexing.
    If such an arrayed interface variable is not declared with the necessary 
    additional input or output array dimension, a link-time error will result."

    "For non-arrayed interfaces (meaning array dimensionally stays the same between 
    stages), it is a link-time error if the input variable is not declared with the 
    same type, including array dimensionality, as the matching output variable."

    Remove the following paragraph

    "If the output corresponding to an arrayed input is itself an array, it 
    must appear in an output block (see interface blocks below) in the 
    outputting shader and in an input block in the inputting shader with a block
    instance name declared as an array.  This is required because two-dimensional 
    arrays are not supported."

    Section 4.3.6 Output Variables

    Remove the following paragraph

    "As described under the section 4.3.4 'Input Variables' above, if a 
    per-vertex output of the tessellation control shader is itself an array 
    with multiple values per vertex, it must appear in an output block (see 
    interface blocks below) in the tessellation control shader with a block 
    instance name declared as an array."

Additions to Chapter 5 of the OpenGL Shading Language Specification, Version
4.20 (Built-in Variables)

    Section 5.4 Array Constructors

    Expand the constructor examples with the constructor examples from the
    overview section of this specification.

    Section 5.7 Structure and Array Operations

    Expand the examples with the .length() and [] examples from the overview
    section of this specification.

Changes to the grammar

    There are 7 pairs of rules that allowed either an empty array 
    declaration or one with a size.  For example:

        init_declarator_list:
                init_declarator_list COMMA IDENTIFIER LEFT_BRACKET RIGHT_BRACKET 
                init_declarator_list COMMA IDENTIFIER LEFT_BRACKET constant_expression RIGHT_BRACKET 

    plus 1 rule for parameter array declarations:
        
        parameter_declarator:
                type_specifier IDENTIFIER LEFT_BRACKET constant_expression RIGHT_BRACKET 

    These 15 total (2*7 + 1) declaration rules are all replaced with 8 uses 
    of a new rule array_specifier:

        array_specifier:
                LEFT_BRACKET RIGHT_BRACKET
                LEFT_BRACKET constant_expression RIGHT_BRACKET
                array_specifier LEFT_BRACKET RIGHT_BRACKET
                array_specifier LEFT_BRACKET constant_expression RIGHT_BRACKET

    For example, the pair given in the example above becomes:

        init_declarator_list:
                init_declarator_list COMMA IDENTIFIER array_specifier

    The LEFT_BRACKET now appears in exactly 5 rules now; the 1 for postfix 
    expressions (remains unchanged) and the 4 for array_specifier.

New State

    None.

New Implementation Dependent State

    None.

Issues


1.  Do we want to support the following form as well?

        vec4[3][2] a;

    Probably, to match the constructor and formal parameter declaration.  These
    require that 

        vec4[3][2]   // a valid type

    is a type in its own right, and the general syntax to declare something is 

        <type> <name>

    GLSL already has required the following since 1.2:

        vec4[3] a;

    RESOLUTION: Yes, allow this syntax.
    
2.  What does the enumeration API look like?  Don't want to enumerate down to 
    10,000 little individual elements, want something more hierarchical instead.

    This will significantly effect this extension if this extension turns into
    defining a new discovery API.

    Nested issue: What about optimizers eliminating holes in a data structure?

    RESOLUTION: Belongs in another extension.

3.  How are large buffer/memory arrays declared?  E.g.,

        buffer vec4 a[][2];

    RESOLUTION: Belongs in another extension.  Probably will be

        buffer BufferBlock {
            vec4 a[][2];
        };

4.  Can large memory arrays be passed by reference to a function?  Want to pick 
    up pointer-like feature without full introduction of pointers.

    RESOLUTION: Belongs in another extension.

5.  How does this extension interact with ??, which is adding the large 
    memory/buffer style arrays.

    RESOLUTION: Belongs in another extension.

6.  Can vertex inputs be arrays of arrays?

    RESOLUTION: Yes.  

7.  Can fragment outputs be arrays of arrays?

    RESOLUTION: Yes.

8.  Can vertex outputs be arrays of arrays?  Note that some stage inputs can 
    now be arrays of arrays, due to adding a new array level to a previous
    stage's output type.

    RESOLUTION: Yes.

9.  Can uniforms be arrays of arrays?

    RESOLUTION: Yes.

10.  Can interface blocks (e.g. uniform blocks) be arrays of arrays?

    RESOLUTION: Yes.

11.  Can subroutine variables be arrays of arrays?

    Recommended: Yes.

    RESOLUTION:

12.  Do we want to eliminate the syntax?

    vec4[2] a[3];  // same as vec4 a[3][2];

    It might seem the 3 and 2 should be reversed.  However, thinking through how 
    precedence, the grammar, etc. all work, this is actually very well defined 
    and correct and consistent with C/C++.

    RESOLUTION: Yes, allow these syntaxes.

Revision History

    Rev.    Date      Author    Changes
    ----  --------    --------  -----------------------------------------
     7    1-Jul-2012  JohnK     Added grammar changes.
     6   10-May-2012  JohnK     Editorial fixes before merging into core spec.
     5   16-Mar-2012  JohnK     Update with resolutions from language meeting
                                (Generally, allow arrays of arrays for most I/O, 
                                 and allow the syntaxes that naturally fall out.)
     4   24-Feb-2012  JohnK     Minor clarifications within issues.
     3    3-Feb-2012  JohnK     Fix reversed 2/3, add new example, resolve issues 2-5
     2    1-Feb-2012  JohnK     Flesh out with specification language
     1    1-Feb-2012  JohnK     Initial revision