xref: /third_party/openGLES/extensions/APPLE/APPLE_element_array.txt

Name

    APPLE_element_array

Name Strings

    GL_APPLE_element_array

Contact

    Bob Beretta, Apple Computer (beretta 'at' apple.com)

Version

    1.0

Number

    271

Dependencies

    Written based on the wording of the OpenGL 1.3 specification.

    Assumes support for the APPLE_vertex_array_range extension.

Overview

    This extension provides facilities to improve DrawElements style vertex
    indices submission performance by allowing index arrays.  Using this
    extension these arrays can be contained inside a vertex array range and
    thus pulled directly by the graphics processor, avoiding the CPU overhead
    of touching the index data.

    This extension is most useful when used in conjunction with the
    APPLE_vertex_array_range extension. APPLE_vertex_array_range provides an
    interface for storing vertex array data. In cases where large amounts of
    vertex data are in use, the index data used to construct primitives
    (typically as passed to the GL through DrawElements) can impose a
    significant bandwidth burden. APPLE_element_array allows the application to
    specify independent arrays of elements, which can then be cached using
    APPLE_vertex_array_range.  In effect this creates a more orthogonal
    interface for both vertex indices and data.


Issues

    Must the element array be enabled?

        RESOLVED: Yes, for orthogonality with the rest of the API.

New Procedures and Functions

    void ElementPointerAPPLE(enum type, const void *pointer);

    void DrawElementArrayAPPLE(enum mode, int first, sizei count)

    void DrawRangeElementArrayAPPLE(enum mode, uint start,
                                    uint end, int first, sizei count)

    void MultiDrawElementArrayAPPLE(enum mode, const int *first,
                                    const sizei *count, sizei primcount);

    void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
                                         const int *first,
                                         const sizei *count,
                                         sizei primcount);


New Tokens

    Accepted by the <array> parameter of EnableClientState and
    DisableClientState and the <value> parameter of IsEnabled:

        ELEMENT_ARRAY_APPLE             0x8A0C

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

        ELEMENT_ARRAY_TYPE_APPLE        0x8A0D

    Accepted by the <pname> parameter of GetPointerv:

        ELEMENT_ARRAY_POINTER_APPLE     0x8A0E


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

    In section 2.6.3, GL Commands within Begin/End, add
    ElementArrayAPPLE to the list of commands that are not allowed
    within any Begin/End pair, but may or may not generate an error.


    Inserted in section 2.8, Vertex Arrays, after the description of
    DrawRangeElements, but before the description of
    InterleavedArrays:

    "The commands

        void DrawElementArrayAPPLE(enum mode, int first, sizei count)

        void DrawRangeElementArrayAPPLE(enum mode, uint start,
                                        uint end, int first, sizei count)

    can be used to construct a sequence of geometric primitives in the same
    manner as DrawElements and DrawRangeElements, but using a previously defined
    array of indices. For DrawElementArrayAPPLE, the <mode> and <count>
    arguments match the corresponding arguments to DrawElements. For
    DrawRangeElementArrayAPPLE, the <mode>, <start>, <end> and <count> arguments
    match the corresponding arguments to DrawRangeElements.  For either routine,
    the <first> argument specifies the first element of the current element
    array to be used in generating primitives.

    For both DrawElementArrayAPPLE and DrawRangeElementArrayAPPLE, the list of
    indices used to generate primitives is defined by the command

        void ElementPointer(enum type, const void *pointer)

    The <pointer> argument is used to specify the list of indices, and the
    <type> argument specifies their format. These arguments match the <type> and
    <indices> arguments to DrawElements and DrawRangeElements, and the allowed
    types match those accepted by these two commands -- GL_UNSIGNED_BYTE,
    GL_UNSIGNED_SHORT, and GL_UNSIGNED_INT. ElementPointer does not specify a
    stride between successive indices in the array, the values must be stored
    sequentially in memory.

    The commands MultiDrawElementArrayAPPLE and MultiDrawRangeElementArrayAPPLE
    provides functionality equivalent to EXT_multi_draw_arrays allowing multiple
    lists of indices in one call.


    The command

      void MultiDrawElementArrayAPPLE(enum mode, const int *first,
                                   const sizei *count, sizei primcount)

    is equivalent to the following sequence of commands:

        for(i=0; i<primcount; i++) {
            if ((*(first+i)>=0) && (*(count+i)>0))
                DrawElementArrayAPPLE(mode, *(first+i), *(count+i));
        }

    and the command

      void MultiDrawRangeElementArrayAPPLE(enum mode, uint start, uint end,
                                        const int *first,
                                        const sizei *count,
                                        sizei primcount)

    is equivalent to the following sequence of commands:

        for(i=0; i<primcount; i++) {
            if ((*(first+i)>=0) && (*(count+i)>0))
                DrawRangeElementArrayAPPLE(mode, start, end, *(first+i),
                                           *(count+i));
        }

    The array of element indices can be enabled and disabled by calling
    EnableClientState and DisableClientState with the argument
    ELEMENT_ARRAY_APPLE. DrawElements and DrawRangeElements ignore the currently
    enabled element array.

    If a DrawElementArrayAPPLE or DrawRangeElementArrayAPPLE command is issued
    when there is no currently enabled element array, an error is generated, no
    drawing is done and the current state is not updated."


    Replace the last paragraph of section 2.8 "Vertex Arrays" (page 28) with the
    following:

    "If the number of supported texture units (the value of MAX_TEXTURE_UNITS)
    is k, then the client state required to implement vertex arrays consists of
    5+k boolean values, 6+k memory pointers, 5+k integer stride values, 5+k
    symbolic constants representing array types, and 3+k integers representing
    values per element. In the initial state, the boolean values are each
    disabled, the memory pointers are each null, the strides are each zero, the
    array types are each FLOAT, except for the element array type, which is
    UNSIGNED_INT, and the integers representing values per element are each
    four."


    Add to the section describing the operation of the vertex array range:

    "When the vertex array range is valid, changes to element array data used by
    the DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
    MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE commands
    need to be synchronized in the same manner as other vertex array data.

    Undefined vertices maybe generated by DrawElementArrayAPPLE,
    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
    MultiDrawRangeElementArrayAPPLE when the vertex array range is enabled if
    any element required by the element array falls outside of the vertex array
    range."


Additions to Chapter 3 of the 1.3 Specification (Rasterization)

    None


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

    None


Additions to Chapter 5 of the 1.3 Specification (Special Functions)

    In section 5.4, Display Lists, change the last sentence of the first
    paragraph to read:

    "(Vertex array and element array pointers are de-referenced when the
    commands ArrayElement, DrawArrays, DrawElements, DrawRangeElements,
    DrawElementArrayAPPLE, or DrawRangeElementArrayAPPLE are accumulated into a
    display list.)

    In section 5.4, Display Lists, add ElementArrayAPPLE to the list of commands
    that are not compiled into display lists but are executed immediately.  In
    additional add to the end of the section:

    "If a display list is compiled while VERTEX_ARRAY_RANGE_APPLE is enabled,
    the commands ArrayElement, DrawArrays, DrawElements,
    DrawRangeElements, DrawElementArrayAPPLE, DrawRangeElementArrayAPPLE,
    MultiDrawElementArrayAPPLE, and MultiDrawRangeElementArrayAPPLE are
    accumulated into a display list as if VERTEX_ARRAY_RANGE_APPLE is
    disabled."


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

    In "Pointer and String Queries", section 6.1.11, add
    ELEMENT_ARRAY_POINTER_APPLE to the list of possible values for the
    <pname> parameter of GetPointerv.


Additions to the specification of APPLE_vertex_array_range

    The element array is included in the vertex array data that is expected
    to reside fully within the specified vertex array range, if enabled.  If
    elements in the array lie outside the current vertex array range the
    result is undefined.


Errors

    The error INVALID_OPERATION is generated if DrawElementArrayAPPLE,
    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE, or
    MultiDrawRangeElementArrayAPPLE is called between the execution of Begin and
    the corresponding execution of End.

    The error INVALID_VALUE is generated if DrawElementArrayAPPLE or
    DrawRangeElementArrayAPPLE is called where either <first> or <count> is
    negative.

    The error INVALID_VALUE is generated if MultiDrawElementArrayAPPLE or
    MultiDrawRangeElementArrayAPPLE is called where <primcount> is negative.

    The error INVALID_VALUE is generated if DrawRangeElementArrayAPPLE or
    MultiDrawRangeElementArrayAPPLE is called where <start> is greater than
    <end>.

    INVALID_ENUM is generated if the <type> parameter of ElementPointerAPPLE is
    not UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT.

    INVALID_OPERATION is generated if a DrawElementArrayAPPLE,
    DrawRangeElementArrayAPPLE, MultiDrawElementArrayAPPLE or
    MultiDrawRangeElementArrayAPPLE command is issued when there is no currently
    enabled element array.


New State

    Added to table 6.6, Vertex Array Data

    Get Value                   Get Command     Type    Initial Value   Attrib
    ---------                   -----------     ----    -------------   ------
    ELEMENT_ARRAY_APPLE         IsEnabled       B       False           client
    ELEMENT_ARRAY_TYPE_APPLE    GetIntegerv     Z4      UNSIGNED_INT    client
    ELEMENT_ARRAY_POINTER_APPLE GetPointerv     Z+      0               client


Implementation Notes

    For maximum performance, applications should use
    UNSIGNED_SHORT or UNSIGNED_INT indices.