xref: /third_party/openGLES/extensions/OES/OES_matrix_palette.txt

Name

    OES_matrix_palette

Name Strings

    GL_OES_matrix_palette

Contact

    Aaftab Munshi (amunshi@ati.com)

Notice

    Copyright (c) 2004-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 ES 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

    Ratified by the Khronos BOP, Aug 5, 2004.

Version

    Version 1, August 2004

Number

    OpenGL ES Extension #12

Dependencies

    OpenGL ES 1.0 is required.

Overview

    This extension adds the ability to support vertex skinning in OpenGL ES.
    A simplified version of the ARB_matrix_palette extension is used to
    define OES_matrix_palette extension.

    This extension allow OpenGL ES to support a palette of matrices.  The matrix
    palette defines a set of matrices that can be used to transform a vertex.
    The matrix palette is not part of the model view matrix stack and is enabled
    by setting the MATRIX_MODE to MATRIX_PALETTE_OES.

    The n vertex units use a palette of m modelview matrices (where n and m are
    constrained to implementation defined maxima.)  Each vertex has a set of n
    indices into the palette, and a corresponding set of n weights.
    Matrix indices and weights can be changed for each vertex.  
    
    When this extension is utilized, the enabled units transform each
    vertex by the modelview matrices specified by the vertices'
    respective indices.  These results are subsequently scaled by the
    weights of the respective units and then summed to create the
    eyespace vertex.   
    
    A similar procedure is followed for normals.  Normals, however,
    are transformed by the inverse transpose of the modelview matrix.
    
IP Status

    Unknown, but believed to be none. 

Issues

    Should this extension be an optional or mandatory extension

        Will be an optional extension since ARB_matrix_palette didn't
        see much usage in OpenGL.

    Should we allow the ability to load the current model view matrix 
    into the matrix palette

        Yes.  This will be very helpful since it makes it very easy
        to load an object heirarchy.  This will also be helpful for JSR184

    Should the Matrix palette be loaded with a new LoadMatrixPalette
    command?

        No, although this provides an easy way to support arbitrary
        palette sizes, the method loses the current (MultMatrix,
        Rotate, Translate, Scale..) matrix functionality.

        Matrices will be Loaded into the palette with current
        functions when MATRIX_MODE is MATRIX_PALETTE_OES.  The current
        palette index is set by an explicit command:
        CurrentPaletteMatrixARB(). 
    
        
    Should the Matrix Palette have a stack?

        Not required, this wastes a lot of space.
        
        
    Should the matrix palette be gettable?

        No.
       
    Should MatrixIndexARB be changed to imply LoadMatrix calls to the
    applicable MODELVIEW_MATRIXn stacks?

        No, the MODELVIEW_MATRIXn matrices are unused when
        MATRIX_PALETTE is enabled.
       
    
    Should there be a way to specify that the modelview matrices
    for two different vertex units are identical?

        Not explicitly, but indexing the matrix palette provides this
        functionality. (Both units will have the same matrix index.)
        
        
New Procedures and Functions

    void CurrentPaletteMatrixOES(uint index)

    void LoadPaletteFromModelViewMatrixOES()
    
    void MatrixIndexPointerOES(int size, enum type, sizei stride, void *pointer)

    void WeightPointerOES(int size, enum type, sizei stride, void *pointer);
 
New Tokens

    Accepted by the <mode> parameter of MatrixMode, and by the
    <cap> parameters of Enable and Disable:

      MATRIX_PALETTE_OES                    0x8840

    Accepted by the <pname> parameters of GetIntegerv:

      MAX_PALETTE_MATRICES_OES              0x8842
      MAX_VERTEX_UNITS_OES                  0x86A4
      CURRENT_PALETTE_MATRIX_OES            0x8843

    The default values for MAX_PALETTE_MATRICES_OES and MAX_VERTEX_UNITS_OES
    are 9 and 3 resp.
      
    Accepted by the <cap> parameters of EnableClientState and DisableClientState and
    by the <pname> parameter of IsEnabled:

      MATRIX_INDEX_ARRAY_OES                0x8844
      WEIGHT_ARRAY_OES                      0x86AD

    Accepted by the <pname> parameter of GetIntegerv:

      MATRIX_INDEX_ARRAY_SIZE_OES           0x8846
      MATRIX_INDEX_ARRAY_TYPE_OES           0x8847
      MATRIX_INDEX_ARRAY_STRIDE_OES         0x8848
      MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES 0x8B9E

      WEIGHT_ARRAY_SIZE_OES                 0x86AB
      WEIGHT_ARRAY_TYPE_OES                 0x86A9
      WEIGHT_ARRAY_STRIDE_OES               0x86AA
      WEIGHT_ARRAY_BUFFER_BINDING_OES       0x889E

    Accepted by the <pname> parameter of GetPointerv:

      MATRIX_INDEX_ARRAY_POINTER_OES        0x8849
      WEIGHT_ARRAY_POINTER_OES              0x86AC

Additions to Chapter 2 of the OpenGL ES 1.0 Specification

    - Added to section 2.8 

          void WeightPointerOES(int size, enum type, sizei stride, void *pointer);

          void MatrixIndexPointerOES(int size, enum type, sizei stride, void *pointer);

        WeightPointerOES & MatrixIndexPointerOES are used to describe the weights and
        matrix indices used to blend corresponding matrices for a given vertex.

        For implementations supporting matrix palette, note that <size> values for
        WeightPointerOES & MatrixIndexPointerOES must be less than or equal to the
        implementation defined value MAX_VERTEX_UNITS_OES.

    - Added to table in section 2.8

        Command                 Sizes                       Types
        -------                 -----                       -----
        WeightPointerOES        1..MAX_VERTEX_UNITS_OES     fixed, float
        MatrixIndexPointerOES   1..MAX_VERTEX_UNITS_OES     ubyte
         

    - (section 2.8) Extend the cap flags passed to EnableClientState/DisableClientState
       to include

          MATRIX_INDEX_ARRAY_OES, or WEIGHT_ARRAY_OES

    - (section 2.10) Add the following:

          "The vertex coordinates that are presented to the GL are termed
           object coordinates. The model-view matrix is applied to these
           coordinates to yield eye coordinates. In implementations with
           matrix palette, the matrices specified by the indices per vertex
           are applied to these coordinates and the weighted sum of the
           results are the eye coordinates. Then another matrix, called the
           projection matrix, is applied to eye coordinates to yield clip
           coordinates.  A perspective division is carried out on clip
           coordinates to yield normalized device coordinates.

           A final viewport transformation is applied to convert these
           coordinates into window coordinates."
    
          "... the vertex's eye coordinates are found as:

            (xe)    n-1               (xo)
            (ye)  =  SUM  w_i * M_i * (yo)
            (ze)    i=0               (zo)
            (we)                      (wo)

          where M_i is the palette matrix associated with the i'th
          Vertex unit:
          
            M_i = MatrixPalette[MatrixIndex[i]],
                     if MATRIX_PALETTE_OES is enabled, and
            M_i = MODELVIEW_MATRIX, otherwise.
            
          w_i is the Vertex's associated weight for vertex unit i:

            w_i = weight_i, if MATRIX_PALETTE_OES is enabled,
                         1, if MATRIX_PALETTE_OES is disabled,

          and,
          
            n = <size> value passed into glMatrixIndexPointerOES."
          

          "The projection matrix and model-view matrices are set
          with a variety of commands. The affected matrix is
          determined by the current matrix mode. The current
          matrix mode is set with

            void MatrixMode( enum mode );
 
          which takes one of the pre-defined constants TEXTURE,
          MODELVIEW, PROJECTION, MATRIX_PALETTE_OES.
 

          In implementations supporting OES_matrix_palette,

             void CurrentPaletteMatrixOES(uint index);
              
          defines which of the palette's matrices is affected by
          subsequent matrix operations when the current matrix mode is
          MATRIX_PALETTE_OES. CurrentPaletteMatrixOES generates the
          error INVALID_VALUE if the <index> parameter is not between
          0 and MAX_PALETTE_MATRICES_OES - 1.

          In implementations supporting OES_matrix_palette,

             void LoadPaletteFromModelViewMatrixOES();

          copies the current model view matrix to a matrix in the matrix
          palette, specified by CurrentPaletteMatrixOES.

          DrawArrays and DrawElements will not render the primitive if
          the matrix palette was enabled and the weights and/or matrix
          index vertex pointers are disabled or are not valid.

          "The state required to implement transformations consists of a
          four-valued integer indicating the current matrix mode, a
          stack of at least two 4 x 4 matrices for each of PROJECTION,
          and TEXTURE with associated stack pointers, a stack of at least
          32 4 x 4 matrices with an associated stack pointer for MODELVIEW,
          and a set of MAX_PALETTE_MATRICES_OES matrices of at least 9
          4 x 4 matrices each for the matrix palette.
          
          Initially, there is only one matrix on each stack, and all
          matrices are set to the identity.  The initial matrix mode
          is MODELVIEW. 

          "When matrix palette is enabled, the normal is transformed
          to eye space by:

                                              n-1
              (nx' ny' nz') = (nx ny nz) Inv ( SUM w_i * Mu_i)
                                              i=0
          
            Alternatively implementations may choose to transform the
          normal to eye-space by:
          
                              n-1
              (nx' ny' nz') =  SUM w_i * (nx ny nz) Inv(Mu_i)
                              i=0

          where Mu_i is the upper leftmost 3x3 matrix taken from the
          modelview for vertex unit i (M_i),
         
               M_i = MatrixPalette[MatrixIndex[i]], 
                         if MATRIX_PALETTE_OES is enabled, and
               M_i = MODELVIEW_MATRIX, otherwise
         
          otherwise.

          weight_i is the vertex's associated weight for vertex unit i,

              w_i = weight_i
                        
          and

              n = <size> value passed into glMatrixIndexPointerOES."


Errors
      
      INVALID_VALUE is generated if the <size> parameter for
      MatrixIndexPointerOES or WeightPointerOES is greater
      than MAX_VERTEX_UNITS_OES.

      INVALID_VALUE is generated if the <count> parameter to
      CurrentPaletteMatrixOES is greater than MAX_PALETTE_MATRICES_OES - 1


New State

(table 6.6, p. 232)

                                       Get          Initial
Get Value                      Type    Command      Value   Description                    
---------                      ----    -------      ------- -----------                   
MATRIX_INDEX_ARRAY_OES         B       IsEnabled    False   matrix index array enable
MATRIX_INDEX_ARRAY_SIZE_OES    Z+      GetIntegerv  0       matrix indices per vertex
MATRIX_INDEX_ARRAY_TYPE_OES    Z+      GetIntegerv  UBYTE   type of matrix index data
MATRIX_INDEX_ARRAY_STRIDE_OES  Z+      GetIntegerv  0       stride between
                                                            matrix indices
MATRIX_INDEX_ARRAY_POINTER_OES Y       GetPointerv  0       pointer to matrix
                                                            index array

WEIGHT_ARRAY_OES               B       IsEnabled    False   weight array enable
WEIGHT_ARRAY_SIZE_OES          Z+      GetIntegerv  0       weights per vertex
WEIGHT_ARRAY_TYPE_OES          Z2      GetIntegerv  FLOAT   type of weight data
WEIGHT_ARRAY_STRIDE_OES        Z+      GetIntegerv  0       stride between weights
                                                            per vertex
WEIGHT_ARRAY_POINTER_OES       Y       GetPointerv  0       pointer to weight array


(table 6.7, p. 233)

                                             Get         Initial
Get Value                              Type  Command      Value  Description 
---------                              ----  -------      -----  -----------

MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES  Z+    GetIntegerv  0      matrix index array
                                                                 buffer binding

WEIGHT_ARRAY_BUFFER_BINDING_OES        Z+    GetIntegerv  0      weight array
                                                                 buffer binding

(table 6.9, p. 235)

                                  Get          Initial
Get Value                   Type  Command      Value    Description 
---------                   ----  -------      -------  -----------

MATRIX_PALETTE_OES          B     IsEnabled    False    matrix palette enable
MAX_PALETTE_MATRICES_OES    Z+    GetIntegerv  9        size of matrix palette
MAX_VERTEX_UNITS_OES        Z+    GetIntegerv  3        number of matrices per vertex
CURRENT_PALETTE_MATRIX_OES  Z+    GetIntegerv  0        transform  index of current 
                                                        modelview matrix in the palette,
                                                        as set by CurrentPaletteMatrixOES()


Revision History



Addendum: Using this extension.

    /* position viewer */
    glMatrixMode(GL_MATRIX_PALETTE_OES);
    glCurrentPaletteMatrixOES(0);
    glLoadIdentity();
    glTranslatef(0.0f, 0.0f, -7.0f);
    glRotatef(yrot, 0.0f, 1.0f, 0.0f);

    glCurrentPaletteMatrixOES(1);
    glLoadIdentity();
    glTranslatef(0.0f, 0.0f, -7.0f);

    glRotatef(yrot, 0.0f, 1.0f, 0.0f);
    glRotatef(zrot, 0.0f, 0.0f, 1.0f);

    glEnable(GL_MATRIX_PALETTE_OES);

    glEnableClientState(GL_VERTEX_ARRAY);
    glEnableClientState(GL_TEXTURE_COORD_ARRAY);
    glEnableClientState(GL_MATRIX_INDEX_ARRAY_OES);
    glEnableClientState(GL_WEIGHT_ARRAY_OES);

    glVertexPointer(3, GL_FLOAT, 7 * sizeof(GLfloat), vertexdata);
    glTexCoordPointer(2, GL_FLOAT, 7 * sizeof(GLfloat), vertexdata + 3);
    glWeightPointerOES(2, GL_FLOAT, 7 * sizeof(GLfloat),vertexdata + 5);
    glMatrixIndexPointerOES(2, GL_UNSIGNED_BYTE, 0, matrixindexdata);
        
    for(int i = 0; i < (numSegments << 2) + 2; i ++)
        glDrawArrays(GL_TRIANGLE_FAN, i << 2, 4);