xref: /third_party/openGLES/extensions/EXT/EXT_static_vertex_array.txt

Name

    EXT_static_vertex_array

Name Strings

    GL_EXT_static_vertex_array

Version

    $Date: 1997/09/17 18:24:20 $ $Revision: 1.1 $

Number

    ?? 

Dependencies

    None

Overview

    This extension defines an interface which allows vertex array
    data to be cached or pre-compiled for more efficient rendering.  This
    is useful for implementations which can cache the transformed results
    of array data for reuse by several DrawArrays, ArrayElement, or
    DrawElements commands.  It is also useful for implementations which
    can transfer array data to fast memory for more efficient processing.

    For example, rendering an M by N mesh of quadrilaterals can be
    accomplished by setting up vertex arrays containing all of the
    vertexes in the mesh and issuing M DrawElements commands each of
    which operate on 2 * N vertexes.  Each DrawElements command after
    the first will share N vertexes with the preceding DrawElements
    command.  If the vertex array data is locked while the DrawElements
    commands are executed, then OpenGL may be able to transform each
    of these shared vertexes just once.

New Procedures and Functions

    void LockArraysEXT (sizei count)
    void UnlockArraysEXT (void)

New Tokens

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

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

    After the discussion of InterleavedArrays, add a description of
    array compiling/locking.

    The currently enabled vertex arrays can be locked with the command
    LockArraysEXT.  When the vertex arrays are locked, the data
    specified by the currently enabled vertex arrays is considered
    to be static by GL. An implementation can delay  the referencing 
    of the data used by the commands DrawArrays, ArrayElement or
    DrawElements or pre-process the array data or cache the transformed 
    vertex data associated with the currently enabled vertex arrays.  
    The vertex arrays are unlocked by the command UnlockArraysEXT.
    The lock count, ARRAY_ELEMENT_LOCK_COUNT_EXT, is reset
    to 0 when the vertex arrays are unlocked. 
 
    The error INVALID_OPERATION is generated if any array pointer
    command such as EdgeFlagPointer, TexCoordPointer, ColorPointer, 
    IndexPointer, NormalPointer, VertexPointer or InterleavedArrays
    or EnableClientState/DisableClientState with array set
    to EDGE_FLAG_ARRAY, TEXTURE_COORD_ARRAY, COLOR_ARRAY,
    INDEX_ARRAY, NORMAL_ARRAY or VERTEX_ARRAY is executed between
    the execution of LocakArraysEXT and the corresponding
    UnlockArraysExt.

    Between LockArraysEXT and UnlockArraysEXT the application
    should ensure that none of the array data in the range 
    specified by <count> are changed.  Changes to the array data 
    between the execution of LockArraysEXT and UnlockArraysEXT 
    commands may affect calls may affect DrawArrays, ArrayElement, 
    or DrawElements commands in non-sequential ways.

    While using a static vertex array, references to array elements
    by the commands DrawArrays, ArrayElement, or DrawElements which
    are outside of the range specified by <count> are undefined.
 
Additions to Chapter 3 of the 1.1 Specification (Rasterization)

    None

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

    None

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

    LockArraysEXT and UnlockArraysEXT are not complied into display lists
    but are executed immediately.

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

    None

Additions to the GLX Specification

    None 

GLX Protocol

    None 

Errors

    INVALID_VALUE is generated if LockArraysEXT parameter <count> is less than
    or equal to zero.

    INVALID_OPERATION is generated if LockArraysEXT is called between execution
    of LockArraysEXT and corresponding execution of UnlockArraysEXT.

    INVALID_OPERATION is generated if UnlockArraysEXT is called without a
    corresponding previous execution of LockArraysEXT.

    INVALID_OPERATION may be generated if LockArraysEXT or UnlockArraysEXT is called
    between execution of Begin and the corresponding execution of End.

    INVALID_OPERATION is generated if any array pointer command such as 
    EdgeFlagPointer, TexCoordPointer, ColorPointer, IndexPointer, 
    NormalPointer, VertexPointer or InterleavedArrays
    or EnableClientState/DisableClientState with array set
    to EDGE_FLAG_ARRAY, TEXTURE_COORD_ARRAY, COLOR_ARRAY,
    INDEX_ARRAY, NORMAL_ARRAY or VERTEX_ARRAY is executed between
    the execution of LocakArraysEXT and the corresponding
    UnlockArraysExt.

New State
                                                                Initial
    Get Value                           Get Command     Type    Value   Attrib
    ---------                           -----------     ----    ------- ------

    ARRAY_ELEMENT_LOCK_COUNT_EXT        GetIntegerv     Z+      0       client-vertex-array

New Implementation Dependent State

    None