1Name 2 3 OES_matrix_palette 4 5Name Strings 6 7 GL_OES_matrix_palette 8 9Contact 10 11 Aaftab Munshi (amunshi@ati.com) 12 13Notice 14 15 Copyright (c) 2004-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Ratified by the Khronos BOP, Aug 5, 2004. 31 32Version 33 34 Version 1, August 2004 35 36Number 37 38 OpenGL ES Extension #12 39 40Dependencies 41 42 OpenGL ES 1.0 is required. 43 44Overview 45 46 This extension adds the ability to support vertex skinning in OpenGL ES. 47 A simplified version of the ARB_matrix_palette extension is used to 48 define OES_matrix_palette extension. 49 50 This extension allow OpenGL ES to support a palette of matrices. The matrix 51 palette defines a set of matrices that can be used to transform a vertex. 52 The matrix palette is not part of the model view matrix stack and is enabled 53 by setting the MATRIX_MODE to MATRIX_PALETTE_OES. 54 55 The n vertex units use a palette of m modelview matrices (where n and m are 56 constrained to implementation defined maxima.) Each vertex has a set of n 57 indices into the palette, and a corresponding set of n weights. 58 Matrix indices and weights can be changed for each vertex. 59 60 When this extension is utilized, the enabled units transform each 61 vertex by the modelview matrices specified by the vertices' 62 respective indices. These results are subsequently scaled by the 63 weights of the respective units and then summed to create the 64 eyespace vertex. 65 66 A similar procedure is followed for normals. Normals, however, 67 are transformed by the inverse transpose of the modelview matrix. 68 69IP Status 70 71 Unknown, but believed to be none. 72 73Issues 74 75 Should this extension be an optional or mandatory extension 76 77 Will be an optional extension since ARB_matrix_palette didn't 78 see much usage in OpenGL. 79 80 Should we allow the ability to load the current model view matrix 81 into the matrix palette 82 83 Yes. This will be very helpful since it makes it very easy 84 to load an object heirarchy. This will also be helpful for JSR184 85 86 Should the Matrix palette be loaded with a new LoadMatrixPalette 87 command? 88 89 No, although this provides an easy way to support arbitrary 90 palette sizes, the method loses the current (MultMatrix, 91 Rotate, Translate, Scale..) matrix functionality. 92 93 Matrices will be Loaded into the palette with current 94 functions when MATRIX_MODE is MATRIX_PALETTE_OES. The current 95 palette index is set by an explicit command: 96 CurrentPaletteMatrixARB(). 97 98 99 Should the Matrix Palette have a stack? 100 101 Not required, this wastes a lot of space. 102 103 104 Should the matrix palette be gettable? 105 106 No. 107 108 Should MatrixIndexARB be changed to imply LoadMatrix calls to the 109 applicable MODELVIEW_MATRIXn stacks? 110 111 No, the MODELVIEW_MATRIXn matrices are unused when 112 MATRIX_PALETTE is enabled. 113 114 115 Should there be a way to specify that the modelview matrices 116 for two different vertex units are identical? 117 118 Not explicitly, but indexing the matrix palette provides this 119 functionality. (Both units will have the same matrix index.) 120 121 122New Procedures and Functions 123 124 void CurrentPaletteMatrixOES(uint index) 125 126 void LoadPaletteFromModelViewMatrixOES() 127 128 void MatrixIndexPointerOES(int size, enum type, sizei stride, void *pointer) 129 130 void WeightPointerOES(int size, enum type, sizei stride, void *pointer); 131 132New Tokens 133 134 Accepted by the <mode> parameter of MatrixMode, and by the 135 <cap> parameters of Enable and Disable: 136 137 MATRIX_PALETTE_OES 0x8840 138 139 Accepted by the <pname> parameters of GetIntegerv: 140 141 MAX_PALETTE_MATRICES_OES 0x8842 142 MAX_VERTEX_UNITS_OES 0x86A4 143 CURRENT_PALETTE_MATRIX_OES 0x8843 144 145 The default values for MAX_PALETTE_MATRICES_OES and MAX_VERTEX_UNITS_OES 146 are 9 and 3 resp. 147 148 Accepted by the <cap> parameters of EnableClientState and DisableClientState and 149 by the <pname> parameter of IsEnabled: 150 151 MATRIX_INDEX_ARRAY_OES 0x8844 152 WEIGHT_ARRAY_OES 0x86AD 153 154 Accepted by the <pname> parameter of GetIntegerv: 155 156 MATRIX_INDEX_ARRAY_SIZE_OES 0x8846 157 MATRIX_INDEX_ARRAY_TYPE_OES 0x8847 158 MATRIX_INDEX_ARRAY_STRIDE_OES 0x8848 159 MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES 0x8B9E 160 161 WEIGHT_ARRAY_SIZE_OES 0x86AB 162 WEIGHT_ARRAY_TYPE_OES 0x86A9 163 WEIGHT_ARRAY_STRIDE_OES 0x86AA 164 WEIGHT_ARRAY_BUFFER_BINDING_OES 0x889E 165 166 Accepted by the <pname> parameter of GetPointerv: 167 168 MATRIX_INDEX_ARRAY_POINTER_OES 0x8849 169 WEIGHT_ARRAY_POINTER_OES 0x86AC 170 171Additions to Chapter 2 of the OpenGL ES 1.0 Specification 172 173 - Added to section 2.8 174 175 void WeightPointerOES(int size, enum type, sizei stride, void *pointer); 176 177 void MatrixIndexPointerOES(int size, enum type, sizei stride, void *pointer); 178 179 WeightPointerOES & MatrixIndexPointerOES are used to describe the weights and 180 matrix indices used to blend corresponding matrices for a given vertex. 181 182 For implementations supporting matrix palette, note that <size> values for 183 WeightPointerOES & MatrixIndexPointerOES must be less than or equal to the 184 implementation defined value MAX_VERTEX_UNITS_OES. 185 186 - Added to table in section 2.8 187 188 Command Sizes Types 189 ------- ----- ----- 190 WeightPointerOES 1..MAX_VERTEX_UNITS_OES fixed, float 191 MatrixIndexPointerOES 1..MAX_VERTEX_UNITS_OES ubyte 192 193 194 - (section 2.8) Extend the cap flags passed to EnableClientState/DisableClientState 195 to include 196 197 MATRIX_INDEX_ARRAY_OES, or WEIGHT_ARRAY_OES 198 199 - (section 2.10) Add the following: 200 201 "The vertex coordinates that are presented to the GL are termed 202 object coordinates. The model-view matrix is applied to these 203 coordinates to yield eye coordinates. In implementations with 204 matrix palette, the matrices specified by the indices per vertex 205 are applied to these coordinates and the weighted sum of the 206 results are the eye coordinates. Then another matrix, called the 207 projection matrix, is applied to eye coordinates to yield clip 208 coordinates. A perspective division is carried out on clip 209 coordinates to yield normalized device coordinates. 210 211 A final viewport transformation is applied to convert these 212 coordinates into window coordinates." 213 214 "... the vertex's eye coordinates are found as: 215 216 (xe) n-1 (xo) 217 (ye) = SUM w_i * M_i * (yo) 218 (ze) i=0 (zo) 219 (we) (wo) 220 221 where M_i is the palette matrix associated with the i'th 222 Vertex unit: 223 224 M_i = MatrixPalette[MatrixIndex[i]], 225 if MATRIX_PALETTE_OES is enabled, and 226 M_i = MODELVIEW_MATRIX, otherwise. 227 228 w_i is the Vertex's associated weight for vertex unit i: 229 230 w_i = weight_i, if MATRIX_PALETTE_OES is enabled, 231 1, if MATRIX_PALETTE_OES is disabled, 232 233 and, 234 235 n = <size> value passed into glMatrixIndexPointerOES." 236 237 238 "The projection matrix and model-view matrices are set 239 with a variety of commands. The affected matrix is 240 determined by the current matrix mode. The current 241 matrix mode is set with 242 243 void MatrixMode( enum mode ); 244 245 which takes one of the pre-defined constants TEXTURE, 246 MODELVIEW, PROJECTION, MATRIX_PALETTE_OES. 247 248 249 In implementations supporting OES_matrix_palette, 250 251 void CurrentPaletteMatrixOES(uint index); 252 253 defines which of the palette's matrices is affected by 254 subsequent matrix operations when the current matrix mode is 255 MATRIX_PALETTE_OES. CurrentPaletteMatrixOES generates the 256 error INVALID_VALUE if the <index> parameter is not between 257 0 and MAX_PALETTE_MATRICES_OES - 1. 258 259 In implementations supporting OES_matrix_palette, 260 261 void LoadPaletteFromModelViewMatrixOES(); 262 263 copies the current model view matrix to a matrix in the matrix 264 palette, specified by CurrentPaletteMatrixOES. 265 266 DrawArrays and DrawElements will not render the primitive if 267 the matrix palette was enabled and the weights and/or matrix 268 index vertex pointers are disabled or are not valid. 269 270 "The state required to implement transformations consists of a 271 four-valued integer indicating the current matrix mode, a 272 stack of at least two 4 x 4 matrices for each of PROJECTION, 273 and TEXTURE with associated stack pointers, a stack of at least 274 32 4 x 4 matrices with an associated stack pointer for MODELVIEW, 275 and a set of MAX_PALETTE_MATRICES_OES matrices of at least 9 276 4 x 4 matrices each for the matrix palette. 277 278 Initially, there is only one matrix on each stack, and all 279 matrices are set to the identity. The initial matrix mode 280 is MODELVIEW. 281 282 "When matrix palette is enabled, the normal is transformed 283 to eye space by: 284 285 n-1 286 (nx' ny' nz') = (nx ny nz) Inv ( SUM w_i * Mu_i) 287 i=0 288 289 Alternatively implementations may choose to transform the 290 normal to eye-space by: 291 292 n-1 293 (nx' ny' nz') = SUM w_i * (nx ny nz) Inv(Mu_i) 294 i=0 295 296 where Mu_i is the upper leftmost 3x3 matrix taken from the 297 modelview for vertex unit i (M_i), 298 299 M_i = MatrixPalette[MatrixIndex[i]], 300 if MATRIX_PALETTE_OES is enabled, and 301 M_i = MODELVIEW_MATRIX, otherwise 302 303 otherwise. 304 305 weight_i is the vertex's associated weight for vertex unit i, 306 307 w_i = weight_i 308 309 and 310 311 n = <size> value passed into glMatrixIndexPointerOES." 312 313 314Errors 315 316 INVALID_VALUE is generated if the <size> parameter for 317 MatrixIndexPointerOES or WeightPointerOES is greater 318 than MAX_VERTEX_UNITS_OES. 319 320 INVALID_VALUE is generated if the <count> parameter to 321 CurrentPaletteMatrixOES is greater than MAX_PALETTE_MATRICES_OES - 1 322 323 324New State 325 326(table 6.6, p. 232) 327 328 Get Initial 329Get Value Type Command Value Description 330--------- ---- ------- ------- ----------- 331MATRIX_INDEX_ARRAY_OES B IsEnabled False matrix index array enable 332MATRIX_INDEX_ARRAY_SIZE_OES Z+ GetIntegerv 0 matrix indices per vertex 333MATRIX_INDEX_ARRAY_TYPE_OES Z+ GetIntegerv UBYTE type of matrix index data 334MATRIX_INDEX_ARRAY_STRIDE_OES Z+ GetIntegerv 0 stride between 335 matrix indices 336MATRIX_INDEX_ARRAY_POINTER_OES Y GetPointerv 0 pointer to matrix 337 index array 338 339WEIGHT_ARRAY_OES B IsEnabled False weight array enable 340WEIGHT_ARRAY_SIZE_OES Z+ GetIntegerv 0 weights per vertex 341WEIGHT_ARRAY_TYPE_OES Z2 GetIntegerv FLOAT type of weight data 342WEIGHT_ARRAY_STRIDE_OES Z+ GetIntegerv 0 stride between weights 343 per vertex 344WEIGHT_ARRAY_POINTER_OES Y GetPointerv 0 pointer to weight array 345 346 347(table 6.7, p. 233) 348 349 Get Initial 350Get Value Type Command Value Description 351--------- ---- ------- ----- ----------- 352 353MATRIX_INDEX_ARRAY_BUFFER_BINDING_OES Z+ GetIntegerv 0 matrix index array 354 buffer binding 355 356WEIGHT_ARRAY_BUFFER_BINDING_OES Z+ GetIntegerv 0 weight array 357 buffer binding 358 359(table 6.9, p. 235) 360 361 Get Initial 362Get Value Type Command Value Description 363--------- ---- ------- ------- ----------- 364 365MATRIX_PALETTE_OES B IsEnabled False matrix palette enable 366MAX_PALETTE_MATRICES_OES Z+ GetIntegerv 9 size of matrix palette 367MAX_VERTEX_UNITS_OES Z+ GetIntegerv 3 number of matrices per vertex 368CURRENT_PALETTE_MATRIX_OES Z+ GetIntegerv 0 transform index of current 369 modelview matrix in the palette, 370 as set by CurrentPaletteMatrixOES() 371 372 373Revision History 374 375 376 377Addendum: Using this extension. 378 379 /* position viewer */ 380 glMatrixMode(GL_MATRIX_PALETTE_OES); 381 glCurrentPaletteMatrixOES(0); 382 glLoadIdentity(); 383 glTranslatef(0.0f, 0.0f, -7.0f); 384 glRotatef(yrot, 0.0f, 1.0f, 0.0f); 385 386 glCurrentPaletteMatrixOES(1); 387 glLoadIdentity(); 388 glTranslatef(0.0f, 0.0f, -7.0f); 389 390 glRotatef(yrot, 0.0f, 1.0f, 0.0f); 391 glRotatef(zrot, 0.0f, 0.0f, 1.0f); 392 393 glEnable(GL_MATRIX_PALETTE_OES); 394 395 glEnableClientState(GL_VERTEX_ARRAY); 396 glEnableClientState(GL_TEXTURE_COORD_ARRAY); 397 glEnableClientState(GL_MATRIX_INDEX_ARRAY_OES); 398 glEnableClientState(GL_WEIGHT_ARRAY_OES); 399 400 glVertexPointer(3, GL_FLOAT, 7 * sizeof(GLfloat), vertexdata); 401 glTexCoordPointer(2, GL_FLOAT, 7 * sizeof(GLfloat), vertexdata + 3); 402 glWeightPointerOES(2, GL_FLOAT, 7 * sizeof(GLfloat),vertexdata + 5); 403 glMatrixIndexPointerOES(2, GL_UNSIGNED_BYTE, 0, matrixindexdata); 404 405 for(int i = 0; i < (numSegments << 2) + 2; i ++) 406 glDrawArrays(GL_TRIANGLE_FAN, i << 2, 4); 407 408