1Name 2 3 EXT_vertex_shader 4 5Name Strings 6 7 GL_EXT_vertex_shader 8 9Contact 10 11 Benj Lipchak, AMD (benj.lipchak 'at' amd.com) 12 Evan Hart, NVIDIA (ehart 'at' nvidia.com) 13 Dave Gosselin 14 15Version 16 17 Date: 11/04/2006 18 Revision: 1.01 19 20Number 21 22 248 23 24Dependencies 25 26 This spec is written against the 1.2.1 version of the GL spec. 27 28 ARB_imaging affects the definition of this spec. 29 30Overview 31 32 EXT_vertex_shader adds a flexible way to change the per-vertex 33 processing in the GL pipeline. It provides a method to replace 34 the fixed vertex/normal transform and lighting with a user 35 specified means of generating processed vertices, texture 36 coordinates, color, and secondary color, along with a primitive's 37 associated state. 38 39Issues 40 41 How should the user be told that their shader doesn't fit and/or 42 won't run well with the hardware? Some kind of GetError() value or 43 a return value from EndShader()? 44 45 This is accomplished using GetIntegerv, GetFloatv, and 46 GetDoubleV to return a maximum value for Instructions, 47 constants, and volatiles as well as returned the numbers 48 of these resources consumed by the current shader. 49 50 Is lighting or texture coordinate generation performed when a user 51 defined vertex shader is enabled. 52 53 No. The shader writer is responsible for generating any 54 texture coordinates and color values. 55 56 Should we have separate per-vertex calls for SetDataEXT? 57 58 Yes. Changed to SetVariant and SetShaderState. 59 60 Should SwizzleEXT and WriteMaskEXT be an op-code or possibly 61 combined into a new API call that takes enums? 62 63 No, they are different enough to have their own entry point. 64 65 Does there need to be a call to get the size of a potentially 66 optimized shader, potentially using some kind of proxy 67 mechanism? 68 69 The implementation dependent state values seem to provide 70 enough info. 71 72 Should more GL state be available for use by the shader (e.g. 73 enable/disable states for lights)? 74 75 No, enough flexibility is already provided. 76 77 Should we give the opcode enumerants data type names or leave them 78 generic? 79 80 This presents an interesting question in that the 81 trade off is a more simple, concise interface for more 82 difficult validation on the part of the implementation. 83 84 How should client-defined clip planes be handled? 85 86 Client clip-planes should be applied in the output coordinate 87 frame. When a vertex shader is invoked, the eye-space 88 clipping planes are transformed by the current projection 89 matrix and are applied after the primitive is assembled from 90 the transformed vertices. 91 92 What are better names for GenData/SetData? 93 94 These are misleading, and they should be changed. The primary 95 hurdle is devising a better set of names. 96 97 RESOLVED: New names implemented 98 99 Should the *Transform* calls be replaced with a different moniker? 100 101 Possibly, the term transform is somewhat narrow for the 102 functionality. The term shader has been suggested. It seems 103 like a good choice as it fits with the RenderMan style 104 terminology already in use. 105 106 RESOLVED: Shader will be used. 107 108 How should RasterPos be affected by this extension? 109 110 It is probably confusing to have RasterPos affected by 111 this extension, so it should be disallowed. 112 113 How should the arrays/indexing be handled? 114 115 The index operation should be more strictly defined 116 to only operate on contiguous name sets allocated by a 117 single GenSymbols call. Alternatively, it may be useful to 118 enforce that data to be used as arrays be given a special 119 designation. 120 121 Should color-index mode be included? 122 123 No, all computations are supported for RGB only. 124 125 126 127New Procedure and Functions 128 129 void BeginVertexShaderEXT( void ) 130 void EndVertexShaderEXT( void ) 131 void BindVertexShaderEXT( GLuint id ) 132 uint GenVertexShadersEXT( GLuint range ) 133 void DeleteVertexShaderEXT( GLuint id ) 134 void ShaderOp1EXT( enum op, uint res, uint arg1 ) 135 void ShaderOp2EXT( enum op, uint res, uint arg1, uint arg2 ) 136 void ShaderOp3EXT( enum op, uint res, uint arg1, uint arg2, uint arg3 ) 137 void SwizzleEXT( uint res, uint in, enum outX, enum outY, enum outZ, 138 enum outW ) 139 void WriteMaskEXT( uint res, uint in, enum outX, enum outY, enum outZ 140 enum outW ) 141 void InsertComponentEXT( uint res, uint src, uint num ) 142 void ExtractComponentEXT( uint res, uint src, uint num ) 143 uint GenSymbolsEXT( enum datatype, enum storagetype, enum range, 144 uint components ) 145 void SetInvariantEXT( uint id, enum type, void *addr ) 146 void SetLocalConstantEXT( uint id, enum type, void *addr ) 147 void Variant{bsifd ubusui}vEXT( uint id, T *addr ) 148 void VariantPointerEXT( uint id, enum type, uint stride, void *addr ) 149 void EnableVariantClientStateEXT( uint id) 150 void DisableVariantClientStateEXT( uint id) 151 uint BindLightParameterEXT( enum light, enum value) 152 uint BindMaterialParameterEXT( enum face, enum value) 153 uint BindTexGenParameterEXT( enum unit, enum coord, enum value) 154 uint BindTextureUnitParameterEXT( enum unit, enum value) 155 uint BindParameterEXT( enum value) 156 boolean IsVariantEnabledEXT( uint id, enum cap); 157 void GetVariantBooleanvEXT( uint id, enum value, boolean *data); 158 void GetVariantIntegervEXT( uint id, enum value, int *data); 159 void GetVariantFloatvEXT( uint id, enum value, float *data); 160 void GetVariantPointervEXT( uint id, enum value, void **data); 161 void GetInvariantBooleanvEXT( uint id, enum value, boolean *data); 162 void GetInvariantIntegervEXT( uint id, enum value, int *data); 163 void GetInvariantFloatvEXT( uint id, enum value, float *data); 164 void GetLocalConstantBooleanvEXT( uint id, enum value, boolean *data); 165 void GetLocalConstantIntegervEXT( uint id, enum value, int *data); 166 void GetLocalConstantFloatvEXT( uint id, enum value, float *data); 167 168New Tokens 169 170 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, 171 and by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 172 and GetDoublev: 173 174 VERTEX_SHADER_EXT 0x8780 175 176 Accepted by the <value> parameter of GetVariantBooleanv, GetVariantIntegerv, 177 and GetVariantFloatv: 178 179 VARIANT_VALUE_EXT 0x87E4 180 VARIANT_DATATYPE_EXT 0x87E5 181 VARIANT_ARRAY_STRIDE_EXT 0x87E6 182 VARIANT_ARRAY_TYPE_EXT 0x87E7 183 184 Accepted by the <cap> parameter of IsVariantEnabled: 185 186 VARIANT_ARRAY_EXT 0x87E8 187 188 Accepted by the <pname> parameter of GetVariantPointerv: 189 190 VARIANT_ARRAY_POINTER_EXT 0x87E9 191 192 Accepted by the <value> parameter of GetInvariantBooleanv, 193 GetInvariantIntegerv, and GetInvariantFloatv: 194 195 INVARIANT_VALUE_EXT 0x87EA 196 INVARIANT_DATATYPE_EXT 0x87EB 197 198 Accepted by the <value> parameter of GetLocalConstantBooleanv, 199 GetLocalConstantIntegerv, and GetLocalConstantFloatv: 200 201 LOCAL_CONSTANT_VALUE_EXT 0x87EC 202 LOCAL_CONSTANT_DATATYPE_EXT 0x87ED 203 204 Accepted by the <op> parameter of ShaderOp[1..3]EXT: 205 206 OP_INDEX_EXT 0x8782 207 OP_NEGATE_EXT 0x8783 208 OP_DOT3_EXT 0x8784 209 OP_DOT4_EXT 0x8785 210 OP_MUL_EXT 0x8786 211 OP_ADD_EXT 0x8787 212 OP_MADD_EXT 0x8788 213 OP_FRAC_EXT 0x8789 214 OP_MAX_EXT 0x878A 215 OP_MIN_EXT 0x878B 216 OP_SET_GE_EXT 0x878C 217 OP_SET_LT_EXT 0x878D 218 OP_CLAMP_EXT 0x878E 219 OP_FLOOR_EXT 0x878F 220 OP_ROUND_EXT 0x8790 221 OP_EXP_BASE_2_EXT 0x8791 222 OP_LOG_BASE_2_EXT 0x8792 223 OP_POWER_EXT 0x8793 224 OP_RECIP_EXT 0x8794 225 OP_RECIP_SQRT_EXT 0x8795 226 OP_SUB_EXT 0x8796 227 OP_CROSS_PRODUCT_EXT 0x8797 228 OP_MULTIPLY_MATRIX_EXT 0x8798 229 OP_MOV_EXT 0x8799 230 231 Accepted by the <res> parameter of ShaderOp[1..3]EXT, the <res> 232 parameter of WriteMaskEXT, or the <res> parameter of SwizzleEXT: 233 234 OUTPUT_VERTEX_EXT 0x879A 235 OUTPUT_COLOR0_EXT 0x879B 236 OUTPUT_COLOR1_EXT 0x879C 237 OUTPUT_TEXTURE_COORD0_EXT 0x879D 238 OUTPUT_TEXTURE_COORD1_EXT 0x879E 239 OUTPUT_TEXTURE_COORD2_EXT 0x879F 240 OUTPUT_TEXTURE_COORD3_EXT 0x87A0 241 OUTPUT_TEXTURE_COORD4_EXT 0x87A1 242 OUTPUT_TEXTURE_COORD5_EXT 0x87A2 243 OUTPUT_TEXTURE_COORD6_EXT 0x87A3 244 OUTPUT_TEXTURE_COORD7_EXT 0x87A4 245 OUTPUT_TEXTURE_COORD8_EXT 0x87A5 246 OUTPUT_TEXTURE_COORD9_EXT 0x87A6 247 OUTPUT_TEXTURE_COORD10_EXT 0x87A7 248 OUTPUT_TEXTURE_COORD11_EXT 0x87A8 249 OUTPUT_TEXTURE_COORD12_EXT 0x87A9 250 OUTPUT_TEXTURE_COORD13_EXT 0x87AA 251 OUTPUT_TEXTURE_COORD14_EXT 0x87AB 252 OUTPUT_TEXTURE_COORD15_EXT 0x87AC 253 OUTPUT_TEXTURE_COORD16_EXT 0x87AD 254 OUTPUT_TEXTURE_COORD17_EXT 0x87AE 255 OUTPUT_TEXTURE_COORD18_EXT 0x87AF 256 OUTPUT_TEXTURE_COORD19_EXT 0x87B0 257 OUTPUT_TEXTURE_COORD20_EXT 0x87B1 258 OUTPUT_TEXTURE_COORD21_EXT 0x87B2 259 OUTPUT_TEXTURE_COORD22_EXT 0x87B3 260 OUTPUT_TEXTURE_COORD23_EXT 0x87B4 261 OUTPUT_TEXTURE_COORD24_EXT 0x87B5 262 OUTPUT_TEXTURE_COORD25_EXT 0x87B6 263 OUTPUT_TEXTURE_COORD26_EXT 0x87B7 264 OUTPUT_TEXTURE_COORD27_EXT 0x87B8 265 OUTPUT_TEXTURE_COORD28_EXT 0x87B9 266 OUTPUT_TEXTURE_COORD29_EXT 0x87BA 267 OUTPUT_TEXTURE_COORD30_EXT 0x87BB 268 OUTPUT_TEXTURE_COORD31_EXT 0x87BC 269 OUTPUT_FOG_EXT 0x87BD 270 271 Accepted by the <datatype> parameter of GenSymbolsEXT: 272 273 SCALAR_EXT 0x87BE 274 VECTOR_EXT 0x87BF 275 MATRIX_EXT 0x87C0 276 277 Accepted by the <storagetype> parameter of GenSymbolsEXT: 278 279 VARIANT_EXT 0x87C1 280 INVARIANT_EXT 0x87C2 281 LOCAL_CONSTANT_EXT 0x87C3 282 LOCAL_EXT 0x87C4 283 284 Accepted by the <pname> parameters of GetIntegerv, GetFloatv, and 285 GetDoublev: 286 287 MAX_VERTEX_SHADER_INSTRUCTIONS_EXT 0x87C5 288 MAX_VERTEX_SHADER_VARIANTS_EXT 0x87C6 289 MAX_VERTEX_SHADER_INVARIANTS_EXT 0x87C7 290 MAX_VERTEX_SHADER_LOCAL_CONSTANTS_EXT 0x87C8 291 MAX_VERTEX_SHADER_LOCALS_EXT 0x87C9 292 MAX_OPTIMIZED_VERTEX_SHADER_INSTRUCTIONS_EXT 0x87CA 293 MAX_OPTIMIZED_VERTEX_SHADER_VARIANTS_EXT 0x87CB 294 MAX_OPTIMIZED_VERTEX_SHADER_LOCAL_CONSTANTS_EXT 0x87CC 295 MAX_OPTIMIZED_VERTEX_SHADER_INARIANTS_EXT 0x87CD 296 MAX_OPTIMIZED_VERTEX_SHADER_LOCALS_EXT 0x87CE 297 VERTEX_SHADER_INSTRUCTIONS_EXT 0x87CF 298 VERTEX_SHADER_VARIANTS_EXT 0x87D0 299 VERTEX_SHADER_INVARIANTS_EXT 0x87D1 300 VERTEX_SHADER_LOCAL_CONSTANTS_EXT 0x87D2 301 VERTEX_SHADER_LOCALS_EXT 0x87D3 302 VERTEX_SHADER_BINDING_EXT 0x8781 303 304 Accepted by the <pname> parameters of GetBooleanv: 305 306 VERTEX_SHADER_OPTIMIZED_EXT 0x87D4 307 308 Accepted by the <out[XYZW]> parameters of SwizzleEXT: 309 310 X_EXT 0x87D5 311 Y_EXT 0x87D6 312 Z_EXT 0x87D7 313 W_EXT 0x87D8 314 NEGATIVE_X_EXT 0x87D9 315 NEGATIVE_Y_EXT 0x87DA 316 NEGATIVE_Z_EXT 0x87DB 317 NEGATIVE_W_EXT 0x87DC 318 ZERO_EXT 0x87dd 319 ONE_EXT 0x87de 320 NEGATIVE_ONE_EXT 0x87DF 321 322 Accepted by the <range> parameter of GenSymbolsEXT: 323 324 NORMALIZED_RANGE_EXT 0x87E0 325 FULL_RANGE_EXT 0x87E1 326 327 Accepted by the <value> parameter of BindParameterEXT: 328 329 CURRENT_VERTEX_EXT 0x87E2 330 MVP_MATRIX_EXT 0x87E3 331 332 333 334Additions to Chapter 2 of the OpenGL 1.2.1 Specification (Operation) 335 336 - (2.6, p. 12) First paragraph changed to: 337 "In the GL, most geometric objects are drawn by enclosing a series 338 of coordinate sets that specify vertices and optionally normals, 339 texture coordinates, colors, and user defined data between 340 Begin/End pairs. There are ten geometric objects that are drawn 341 this way: points, line segments, line segment loops, separated 342 line segments, polygons, triangle strips, triangle fans, separated 343 triangles, quadrilateral strips, and separated quadrilaterals." 344 345 - (2.6, p. 13) Fourth paragraph changed to: 346 "The current values are part of GL state. Vertices and normals are 347 transformed, colors may be affected or replaced by lighting, and 348 texture coordinates are transformed and possibly affected by a 349 texture coordinate generation function. Alternatively the 350 vertices, normals, texture coordinates, and colors may be 351 transformed or replaced by a vertex shader program. In either case 352 the processing indicated for each current value is applied for 353 each vertex that is sent to the GL." 354 355 - (2.6, p. 14) 356 Should replace figure 2.2 with something showing the switch 357 between built in vertex/normal transformation and lighting and the 358 vertex shader program. 359 360 - (2.6.3, p. 19) First paragraph changed to: 361 "The only GL commands that are allowed within any Begin/End pairs 362 are the commands for specifying vertex coordinates, vertex color, 363 normal coordinates, and texture coordinates (Vertex, Color, Index, 364 Normal, TexCoord), the ArrayElement command (see section 2.8), the 365 EvalCoord and EvalPoint commands (see section 5.1), commands for 366 specifying lighting material parameters (Material commands; see 367 section 2.13.2), display list invocation commands (CallList and 368 CallLists; see section 5.4), the EdgeFlag command, and the 369 VariantEXT command (see section 2.14). Executing any other GL 370 command between the execution of Begin and the corresponding 371 execution of End results in the error INVALID_OPERATION. Executing 372 Begin after Begin has already been executed but before an End is 373 executed generates the INVALID_OPERATION error, as does executing 374 End without a previous corresponding Begin. 375 376 - (2.8, p. 23) Added after the second paragraph: 377 "In addition to the pre-defined GL vertex components, variants 378 can be supplied via the vertex array mechanism. Variant arrays are 379 specified by the call: 380 381 void VariantPointerEXT( uint id, enum type, uint stride, void *addr ) 382 383 The type and stride parameters hold the same meaning as all other 384 array calls. The size parameter is missing as in NormalPointer, 385 and the size is fixed at 4. The id parameter specifies which 386 variant this array is to be used with. Finally, variant arrays 387 are enabled and disabled by calls to: 388 389 void EnableVariantClientStateEXT( uint id) 390 void DisableVariantClientStateEXT( uint id) 391 392 The id parameter contains the id of the variant array to enable 393 or disable. 394 395 - (2.10, p. 28) First Paragraph changed to: 396 "Vertices, normals, and texture coordinates are transformed before 397 their coordinates are used to produce an image in the 398 framebuffer. This transformation can be accomplished with either 399 the OpenGL Per-Vertex operations or replaced by a vertex shader. 400 We begin with a description of how vertex coordinates are 401 transformed via the OpenGL Per-Vertex operations and how this 402 transformation is controlled. The specification of a vertex shader 403 is described in section 2.14." 404 405 - (2.10, p. 28) Second Paragraph changed to: 406 "Figure 2.6 diagrams the sequence of transformations that are 407 applied to vertices in OpenGL vertex processing. The vertex 408 coordinates that are presented to the GL are termed object 409 coordinates. The model-view matrix is applied to these coordinates 410 to yield eye coordinates. Then another matrix, called the 411 projection matrix, is applied to eye coordinates to yield clip 412 coordinates. A perspective division is carried out on clip 413 coordinates to yield normalized device coordinates. A final 414 viewport transformation is applied to convert these coordinates 415 into window coordinates." 416 417 - (2.10.2, p. 33) Eighth Paragraph changed to: 418 "There is another 4 x 4 matrix that is applied to texture 419 coordinates by the OpenGL per-vertex operations. This matrix 420 is applied as 421 | m1 m5 m9 m13 | |s| 422 | m2 m6 m10 m14 | |t|, 423 | m3 m7 m11 m15 | |r| 424 | m4 m8 m12 m16 | |q| 425 where the left matrix is the current texture matrix. The matrix is 426 applied to the coordinates resulting from texture coordinate 427 generation (which may simply be the current texture coordinates), 428 and the resulting transformed coordinates become the texture 429 coordinates associated with a vertex. Setting the matrix mode to 430 TEXTURE causes the already described matrix operations to apply to 431 the texture matrix." 432 433 - (2.11, p. 39) Added after the first paragraph" 434 "When the user defined shader is eanbeld as described in section 435 2.14, the ability to clip in eye-space is removed as eye-space is 436 now undefined. Instead, client defined clip planes are applied in 437 clip-space. The algorithm is identical, except the half-space is 438 now defined as: 439 440 (x_clip) 441 (p'1 p'2 p'3 p'4) P_inv (y_clip) >= 0 442 (z_clip) 443 (w_clip) 444 445 Where P is the projection matrix and x_clip, y_clip, z_clip, and 446 w_clip are the clip space vertex coordinates. When P is singular, 447 the result of clipping is undefined. 448 449 - (2.12, p. 41) Added after the third paragraph: 450 "The raster position is not affected by the current vertex shader 451 program, instead they are always processed by the OpenGL vertex 452 processing." 453 454 - (2.13, p. 43) Second paragraph: 455 "Next, lighting, if enabled (and vertex shaders are disabled), 456 produces either a color index or primary and secondary colors. 457 If lighting is disabled, the current color index or color is used 458 in further processing (the current color is the primary color, and 459 the secondary color is (0; 0; 0; 0)). After lighting or vertex 460 shading, RGBA colors are clamped to the range [0; 1]. A color 461 index is converted to fixed-point and then its integer portion is 462 masked (see section 2.13.6). After clamping or masking, a 463 primitive may be flatshaded, indicating that all vertices of the 464 primitive are to have the same color. Finally, if a primitive is 465 clipped, then colors (and texture coordinates) must be computed 466 at the vertices introduced or modified by clipping." 467 468 - (2.13.1, p. 44) First paragraph: 469 "GL lighting computes colors for each vertex sent to the GL. This 470 is accomplished by applying an equation defined by a 471 client-specified lighting model to a collection of parameters that 472 can include the vertex coordinates, the coordinates of one or more 473 light sources, the current normal, and parameters defining the 474 characteristics of the light sources and a current material. The 475 following discussion assumes that the GL is in RGBA mode. (Color 476 index lighting is described in section 2.13.5.) Lighting may be in 477 one of two states: 478 1. Lighting Off. In this state, the current color is assigned 479 to the vertex primary color. The secondary 480 color is (0; 0; 0; 0). Lighting is off if 481 vertex shaders are enabled." 482 2. Lighting On. In this state, the vertex primary and secondary 483 colors are computed from the current lighting 484 parameters. Lighting is turned on or off using 485 the generic Enable or Disable commands with the 486 symbolic value LIGHTING." 487 488 - (2.13.8, p. 55) First paragraph: 489 "After lighting or vertex shading, clamping or masking and possible 490 flatshading, colors are clipped. Those colors associated with a 491 vertex that lies within the clip volume are unaffected by clipping. 492 If a primitive is clipped, however, the colors assigned to vertices 493 produced by clipping are clipped colors." 494 495 - (new section 2.14) Vertex Shaders and Coloring 496 "The alternative to OpenGL per-vertex operations is defining a 497 vertex shader. This vertex shader replaces the GL per-vertex 498 processing by specifying the operations to perform on the 499 incoming vertex and associated data. A vertex shader is defined 500 between a BeginVertexShaderEXT and EndVertexShaderEXT block. These 501 commands are defined as follows: 502 503 void BeginVertexShaderEXT( void ); 504 void EndVertexShaderEXT( void ); 505 506 The only GL operations allowed between BeginShader and 507 EndShader are ShaderOp[1..3]EXT, GenSymbolsEXT, SetLocalConstantEXT, 508 SwizzleEXT, WriteMaskEXT, InsertComponentEXT, and 509 ExtractComponentEXT. Calling BeginVertexShader with a prior call to 510 BeginVertexShader and no matching prior call to EndVertexShader 511 results in the error INVALID_OPERATION. Likewise, calling 512 EndVertexShader without a matching prior call to BeginVertexShader 513 results in the error INVALID_OPERATION. 514 In addition to a default vertex shader program, named vertex 515 shaders can be created. The namespace for vertex shaders is 516 unsigned integers with zero reserved by the GL. A vertetx shader is 517 created by binding an unused name using: 518 519 void BindVertexShaderEXT( uint id ); 520 521 where id is the unused name. Once a vertex shader program has been 522 created it can be rebound as the active vertex shader program by 523 calling BindVertexShaderEXT. Calling BindShaderEXT with an argument 524 of zero binds the default vertex shader program. A vertex shader 525 program can be deleted, freeing the name, by calling 526 527 void DeleteVertexShaderEXT( uint id ); 528 529 where id is the name to be deleted. Unique names can be generated 530 using: 531 532 uint GenShadersEXT( uint range ); 533 534 where range is the number of contiguous ids that should be 535 created. It returns an integer n such that range contiguous empty 536 shader ids, with values n, n+1, ..., n+range -1, are created. 537 If range is 0, if there is no group of range contiguous names 538 available, or if any error is generated, no vertex shader names 539 are generated, and 0 is returned. The currently bound vertex 540 shader can be determined by querying VERTEX_SHADER_BINDING_EXT. 541 There are four kinds of data available from within a vertex 542 shader program: invariant data, local constant data, local data, 543 and variant data. Invariant data is data that can only be set 544 outside of a vertex shader program definition, it is set before a 545 shader is executed and does not change during vertex shader program 546 execution. Local constant data is data that is local to the vertex 547 shader program, it is set once during the context of the vertex 548 shader program definition and does not change either before or 549 during execution of the vertex shader program. Local data is data 550 that is local to the vertex shader program which can both be read 551 from and written to during the execution of the vertex shader 552 program but not prior to execution. The contents of local data are 553 undefined until the data is written to, and values do not persist 554 between executions of the vertex shader program. Variant data is 555 data which is specified per vertex, it can only be read from during 556 execution of the vertex shader program. 557 The GenSymbolsEXT, SetInvariantEXT, SetLocalConstantEXT, 558 SetVariantEXT, VariantPointerEXT, commands are used to stage 559 these various kinds of data for use in the vertex shader program. 560 This staging takes place in two parts. The first part involves 561 defining a name and giving it a data type and storage class. 562 This is done by calling 563 564 uint GenSymbolsEXT( enum datatype, enum storagetype, enum range, 565 uint components ); 566 567 where datatype can be one of SCALAR_EXT, VECTOR_EXT, MATRIX_EXT, 568 and storagetype can be one of VARIANT_EXT, INVARIANT_EXT, 569 LOCAL_CONSTANT_EXT, LOCAL_EXT, range can be NORMALIZED_RANGE_EXT 570 or FULL_RANGE_EXT, and components determines how many names should 571 be generated. It returns an integer that is the first 572 name in a contiguous block of names of size components. The three 573 datatypes available determine the size of the storage at each 574 name: Scalars being one element, vectors being 4 elements, and 575 matrices being 16 elements. These are all treated as decimals in 576 the computations performed by ShaderOp[1..3]EXT. The storagetype 577 determines where and how often a particular named piece of data 578 may be set (using SetInvariantEXT, SetLocalConstantEXT, VariantEXT, or 579 VariantPointerEXT). If this data is not set before being 580 used the values used are undetermined and may result in 581 unpredictable values being used in the calculation. The range 582 determines the mapping of the data. When specifying input data 583 with a storagetype of FULL_RANGE_EXT, the data is allowed to 584 occupy the full range of the system's floating point values. 585 When specifying input data with a storagetype of 586 NORMALIZED_RANGE_EXT, integer values are mapped according to 587 table 2.6 and floating point values are clamped to -1 to 1. 588 When a result outside the range -1 to 1 is written to a local 589 with its storagetype set to NORMALIZED_RANGE_EXT, the results 590 are undefined. 591 Assigning values to the names generated is the second part of 592 the staging process and is accomplished by calling 593 594 void SetInvariantEXT( uint id, enum type, void *addr ); 595 void SetLocalConstantEXT( uint id, enum type, void *addr ); 596 void Variant{bsifd ubusui}vEXT( uint id, T *addr ); 597 void VariantPointerEXT( uint id, enum type, uint stride, 598 void *addr ); 599 600 where id is a name returned by GenSymbolsEXT, and type is DOUBLE, 601 FLOAT, BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT, or 602 UNSIGNED_INT, and addr is a pointer to 603 the value to be assigned to the name. 604 SetInvariantEXT is used to set a single scalar, vector, 605 or matrix value. It may be used outside of the vertex shader 606 program to set invariant data. SetLocalConstantEXT may be used 607 inside the vertex shader program to set local constants. Local 608 constants may only be set once during the definition of a 609 vertex shader program. Attempts to set a local constant more than 610 once in a vertex shader program will fail and create the error 611 ILLEGAL_OPERATION. VariantEXT data is used within a Begin, End 612 pair to set per-vertex data. Alternatively a complete set of 613 variant data may specified using arrays by using VariantPointerEXT. 614 615 616 The operations to be performed on the vertex, normal, color, 617 GL state data, and the staged data in the shader are defined by 618 making a sequence of one or more calls (between BeginShader and 619 EndShader) to one or more of the following: 620 621 void ShaderOp1EXT( enum op, uint res, uint arg1 ); 622 void ShaderOp2EXT( enum op, uint res, uint arg1, uint arg2 ); 623 void ShaderOp3EXT( enum op, uint res, uint arg1, uint arg2, 624 uint arg3); 625 626 where op is one of the constants described below, and res is one 627 of OUTPUT_VERTEX_EXT, OUTPUT_COLOR#_EXT, OUTPUT_TEXTURE_COORD#_EXT, 628 OUTPUT_FOG_EXT, or a data id defined by GenSymbolsEXT (with it's 629 storage type set as LOCAL_EXT), and arg[1..3] is a data id defined 630 by GenSymbolsEXT. 631 632 It should be noted that the OUTPUT_xxx_EXT identifiers are 633 special and can only be written. The values propagated forward 634 from the vertex shader program are the last values written to 635 these identifiers. Partial writes to these identifiers can be 636 accomplished by using WriteMaskEXT. 637 638 To facilitate the use of GL state values in a vertex shader 639 program, a parameter binding mechanism is provided. Items such as 640 material properties, light positions, and matrices are bound to 641 ids. The functions for binding these parameters mirror the 642 functions for retrieving state values from GL. The bind functions 643 return an id that can be used as an arg to ShaderOpnEXT. The data 644 type and storage type of the id match the semantics of the GL state 645 and are provided below. The ids returned from the bind calls may 646 not be used with any of the set data calls. Below are the bind 647 functions and tables of their associated states: 648 649 Light Parameters: 650 651 uint BindLightParameterEXT( enum light, enum value) 652 653 Value Data Type Storage Type 654 --------------------- --------- ------------ 655 AMBIENT VECTOR INVARIANT 656 DIFFUSE VECTOR INVARIANT 657 SPECULAR VECTOR INVARIANT 658 POSITION VECTOR INVARIANT 659 CONSTANT_ATTENUATION SCALAR INVARIANT 660 LINEAR_ATTENUATION SCALAR INVARIANT 661 QUADRATIC_ATTENUATION SCALAR INVARIANT 662 SPOT_DIRECTION VECTOR INVARIANT 663 SPOT_EXPONENT SCALAR INVARIANT 664 SPOT_CUTOFF SCALAR INVARIANT 665 666 Material Parameters: 667 668 uint BindMaterialParameterEXT( enum face, enum value) 669 670 Value Data Type Storage Type 671 --------------------- --------- ------------ 672 AMBIENT VECTOR VARIANT 673 DIFFUSE VECTOR VARIANT 674 SPECULAR VECTOR VARIANT 675 EMISSION VECTOR VARIANT 676 SHININESS SCALAR VARIANT 677 678 679 TexGen Parameters: 680 681 uint BindTexGenParameterEXT( enum unit, enum coord, enum value) 682 683 Value Data Type Storage Type 684 --------------------- --------- ------------ 685 EYE_PLANE VECTOR INVARIANT 686 OBJECT_PLANE VECTOR INVARIANT 687 688 Texture Unit Parameters 689 690 uint BindTextureUnitParameterEXT( enum unit, enum value) 691 692 Value Data Type Storage Type 693 --------------------- --------- ------------ 694 CURRENT_TEXTURE_COORDS VECTOR VARIANT 695 TEXTURE_MATRIX MATRIX INVARIANT 696 697 698 Standard Parameters: 699 700 uint BindParameterEXT( enum value) 701 702 Value Data Type Storage Type 703 --------------------- --------- ------------ 704 CURRENT_VERTEX_EXT VECTOR VARIANT 705 CURRENT_NORMAL VECTOR VARIANT 706 CURRENT_COLOR VECTOR VARIANT 707 MODELVIEW_MATRIX MATRIX INVARIANT 708 PROJECTION_MATRIX MATRIX INVARIANT 709 MVP_MATRIX_EXT MATRIX INVARIANT 710 COLOR_MATRIX MATRIX INVARIANT ** Only supported under imaging subset 711 CLIP_PLANEi VECTOR INVARIANT 712 FOG_COLOR VECTOR INVARIANT 713 FOG_DENSITY SCALAR INVARIANT 714 FOG_START SCALAR INVARIANT 715 FOG_END SCALAR INVARIANT 716 LIGHT_MODEL_AMBIENT VECTOR INVARIANT 717 718 719 720 For matrices only the top value of the matrix stack may be 721 accessed. 722 Binding of the token MVP_MATRIX_EXT provides access to a 723 matrix containing the concatenation of the MODELVIEW and 724 PROJECTION matrices. Binding the token CURRENT_VERTEX_EXT 725 provides access to the coordinates of the vertex being processed. 726 A special case of the bindings is CURRENT_NORMAL as it only a 727 3-tuple natively. In this case, it is expanded as a homogeneous 728 vector with the fourth component set to 0. 729 Each operation is accepted by a particular 730 ShaderOp[1..3]EXT based on the number of arguments it 731 accepts and it's results are based on the type of arguments (as 732 bound by GenSymbolsEXT) it receives. This is described in the 733 following table. S denotes a scalar, V denotes a vector, M denotes 734 a matrix, [] denotes a particular element of the input or 735 output, a1 denotes arg1, a2 denotes arg2, a3 denotes arg3, a4 736 denotes arg4, r denotes the result, combinations of input and 737 output not shown produce ILLEGAL_OPERATION. 738 739 740 Table of operations 741 742 743Operation Number of Inputs res args Output 744------------------- ------------------ ---- ----- ----------------- 745OP_INDEX_EXT 2 S S,S special see below 746 V S,V 747 M S,M 748 749OP_NEGATE_EXT 1 S S r = -a1 750 V S r[0] = -a1 751 r[1] = -a1 752 r[2] = -a1 753 r[3] = -a1 754 V V r[0] = -a1[0] 755 r[1] = -a1[1] 756 r[2] = -a1[2] 757 r[3] = -a1[3] 758 759OP_DOT3_EXT 2 S V,V r = a1[0] * a2[0] + 760 a1[1] * a2[1] + 761 a1[2] * a2[2] 762 V V,V r[0] = a1[0] * a2[0] + 763 a1[1] * a2[1] + 764 a1[2] * a2[2] 765 r[1] = a1[0] * a2[0] + 766 a1[1] * a2[1] + 767 a1[2] * a2[2] 768 r[2] = a1[0] * a2[0] + 769 a1[1] * a2[1] + 770 a1[2] * a2[2] 771 r[3] = unchanged 772 773OP_DOT4_EXT 2 S V,V r = a1[0] * a2[0] + 774 a1[1] * a2[1] + 775 a1[2] * a2[2] + 776 a1[3] * a2[3] 777 V V,V r[0] = a1[0] * a2[0] + 778 a1[1] * a2[1] + 779 a1[2] * a2[2] + 780 a1[3] * a2[3] 781 r[1] = a1[0] * a2[0] + 782 a1[1] * a2[1] + 783 a1[2] * a2[2] + 784 a1[3] * a2[3] 785 r[2] = a1[0] * a2[0] + 786 a1[1] * a2[1] + 787 a1[2] * a2[2] + 788 a1[3] * a2[3] 789 r[3] = a1[0] * a2[0] + 790 a1[1] * a2[1] + 791 a1[2] * a2[2] + 792 a1[3] * a2[3] 793 794OP_MUL_EXT 2 S S,S r = a1 * a2 795 V S,S r[0] = r[1] = r[2] = r[3] = a1 * a2 796 r[1] = a1 * a2 797 r[2] = a1 * a2 798 r[3] = a1 * a2 799 V S,V r[0] = a1 * a2[0] 800 r[1] = a1 * a2[1] 801 r[2] = a1 * a2[2] 802 r[3] = a1 * a2[3] 803 V V,S r[0] = a1[0] * a2 804 r[1] = a1[1] * a2 805 r[2] = a1[2] * a2 806 r[3] = a1[3] * a2 807 V V,V r[0] = a1[0] * a2[0] 808 r[1] = a1[1] * a2[1] 809 r[2] = a1[2] * a2[2] 810 r[3] = a1[3] * a2[3] 811 812OP_MOV_EXT 1 S S r = a1 813 V S r[0] = a1 814 r[1] = a1 815 r[2] = a1 816 r[3] = a1 817 V V r[0] = a1[0] 818 r[1] = a1[1] 819 r[2] = a1[2] 820 r[3] = a1[3] 821 822OP_ADD_EXT 2 S S,S r = a1 + a2 823 V S,S r[0] = a1 + a2 824 r[1] = a1 + a2 825 r[2] = a1 + a2 826 r[3] = a1 + a2 827 V S,V r[0] = a1 + a2[0] 828 r[1] = a1 + a2[1] 829 r[2] = a1 + a2[2] 830 r[3] = a1 + a2[3] 831 V V,S r[0] = a1[0] + a2 832 r[1] = a1[1] + a2 833 r[2] = a1[2] + a2 834 r[3] = a1[3] + a2 835 V V,V r[0] = a1[0] + a2[0] 836 r[1] = a1[1] + a2[1] 837 r[2] = a1[2] + a2[2] 838 r[3] = a1[3] + a2[3] 839 840OP_MADD_EXT 3 S S,S,S r = a1 * a2 + a3 841 V S,S,S r[0] = a1 * a2 + a3 842 r[1] = a1 * a2 + a3 843 r[2] = a1 * a2 + a3 844 r[3] = a1 * a2 + a3 845 V S,V,V r[0] = a1 * a2[0] +a3[0] 846 r[1] = a1 * a2[1] +a3[1] 847 r[2] = a1 * a2[2] +a3[2] 848 r[3] = a1 * a2[3] +a3[3] 849 V V,S,V r[0] = a1[0] * a2 +a3[0] 850 r[1] = a1[1] * a2 +a3[1] 851 r[2] = a1[2] * a2 +a3[2] 852 r[3] = a1[3] * a2 +a3[3] 853 V S,S,V r[0] = a1 * a2 +a3[0] 854 r[1] = a1 * a2 +a3[1] 855 r[2] = a1 * a2 +a3[2] 856 r[3] = a1 * a2 +a3[3] 857 V V,V,S r[0] = a1[0] * a2[0] +a3 858 r[1] = a1[1] * a2[1] +a3 859 r[2] = a1[2] * a2[2] +a3 860 r[3] = a1[3] * a2[3] +a3 861 V V,S,S r[0] = a1[0] * a2 +a3 862 r[1] = a1[1] * a2 +a3 863 r[2] = a1[2] * a2 +a3 864 r[3] = a1[3] * a2 +a3 865 V S,V,S r[0] = a1 * a2[0] +a3 866 r[1] = a1 * a2[1] +a3 867 r[2] = a1 * a2[2] +a3 868 r[3] = a1 * a2[3] +a3 869 V V,V,V r[0] = a1[0] * a2[0] +a3[0] 870 r[1] = a1[1] * a2[1] +a3[1] 871 r[2] = a1[2] * a2[2] +a3[2] 872 r[3] = a1[3] * a2[3] +a3[3] 873 874OP_FRAC_EXT 1 S S r = a1 - FLOOR(a1) 875 V S r[0] = a1 - FLOOR(a1) 876 r[1] = a1 - FLOOR(a1) 877 r[2] = a1 - FLOOR(a1) 878 r[3] = a1 - FLOOR(a1) 879 V V r[0] = a1[0] - FLOOR(a1[0]) 880 r[1] = a1[1] - FLOOR(a1[1]) 881 r[2] = a1[2] - FLOOR(a1[2]) 882 r[3] = a1[3] - FLOOR(a1[3]) 883 884OP_MAX_EXT 2 S S,S r = MAX(a1, a2) 885 V S,S r[0] = MAX(a1, a2) 886 r[1] = MAX(a1, a2) 887 r[2] = MAX(a1, a2) 888 r[3] = MAX(a1, a2) 889 V S,V r[0] = MAX(a1, a2[0]) 890 r[1] = MAX(a1, a2[1]) 891 r[2] = MAX(a1, a2[2]) 892 r[3] = MAX(a1, a2[3]) 893 V V,S r[0] = MAX(a1[0], a2) 894 r[1] = MAX(a1[1], a2) 895 r[2] = MAX(a1[2], a2) 896 r[3] = MAX(a1[3], a2) 897 V V,V r[0] = MAX(a1[0], a2[0]) 898 r[1] = MAX(a1[1], a2[1]) 899 r[2] = MAX(a1[2], a2[2]) 900 r[3] = MAX(a1[3], a2[3]) 901 902OP_MIN_EXT 2 S S,S r = MIN(a1, a2) 903 V S,S r[0] = MIN(a1, a2) 904 r[1] = MIN(a1, a2) 905 r[2] = MIN(a1, a2) 906 r[3] = MIN(a1, a2) 907 V S,V r[0] = MIN(a1, a2[0]) 908 r[1] = MIN(a1, a2[1]) 909 r[2] = MIN(a1, a2[2]) 910 r[3] = MIN(a1, a2[3]) 911 V V,S r[0] = MIN(a1[0], a2) 912 r[1] = MIN(a1[1], a2) 913 r[2] = MIN(a1[2], a2) 914 r[3] = MIN(a1[3], a2) 915 V V,V r[0] = MIN(a1[0], a2[0]) 916 r[1] = MIN(a1[1], a2[1]) 917 r[2] = MIN(a1[2], a2[2]) 918 r[3] = MIN(a1[3], a2[3]) 919 920OP_SET_GE_EXT 2 S S,S r = (a1 >= a2) ? 1 : 0 921 V S,S r[0] = (a1 >= a2) ? 1 : 0 922 r[1] = (a1 >= a2) ? 1 : 0 923 r[2] = (a1 >= a2) ? 1 : 0 924 r[3] = (a1 >= a2) ? 1 : 0 925 V S,V r[0] = (a1 >= a2[0]) ?1 : 0 926 r[1] = (a1 >= a2[1]) ? 1: 0 927 r[2] = (a1 >= a2[2]) ? 1: 0 928 r[3] = (a1 >= a2[3]) ? 1: 0 929 V V,S r[0] = (a1[0] >= a2) ? 1: 0 930 r[1] = (a1[1] >= a2) ? 1: 0 931 r[2] = (a1[2] >= a2) ? 1: 0 932 r[3] = (a1[3] >= a2) ? 1: 0 933 V V,V r[0] =(a1[0]>=a2[0]) ?1 : 0 934 r[1] =(a1[1]>=a2[1]) ?1 : 0 935 r[2] =(a1[2]>=a2[2]) ?1 : 0 936 r[3] =(a1[3]>=a2[3]) ?1 : 0 937 938OP_SET_LT_EXT 2 S S,S r = (a1 < a2) ? 1 : 0 939 V S,S r[0] = (a1 < a2) ? 1 : 0 940 r[1] = (a1 < a2) ? 1 : 0 941 r[2] = (a1 < a2) ? 1 : 0 942 r[3] = (a1 < a2) ? 1 : 0 943 V S,V r[0] = (a1 < a2[0]) ? 1 : 0 944 r[1] = (a1 < a2[1]) ? 1 : 0 945 r[2] = (a1 < a2[2]) ? 1 : 0 946 r[3] = (a1 < a2[3]) ? 1 : 0 947 V V,S r[0] = (a1[0] < a2) ? 1 : 0 948 r[1] = (a1[1] < a2) ? 1 : 0 949 r[2] = (a1[2] < a2) ? 1 : 0 950 r[3] = (a1[3] < a2) ? 1 : 0 951 V V,V r[0] =(a1[0]< a2[0]) ?1 : 0 952 r[1] =(a1[1]< a2[1]) ?1 : 0 953 r[2] =(a1[2]< a2[2]) ?1 : 0 954 r[3] =(a1[3]< a2[3]) ?1 : 0 955 956 957OP_CLAMP_EXT 3 S S,S,S r = ( a1 <= a2) ? a2 : 958 ( (a1>=a3) ? a3 : 959 (a1 )) 960 V S,S,S r[0]= ( a1 <= a2) ? a2 : 961 ( (a1>=a3) ? a3 : 962 (a1 )) 963 r[1]= ( a1 <= a2) ? a2 : 964 ( (a1>=a3) ? a3 : 965 (a1 )) 966 r[2]= ( a1 <= a2) ? a2 : 967 ( (a1>=a3) ? a3 : 968 (a1 )) 969 r[3]= ( a1 <= a2) ? a2 : 970 ( (a1>=a3) ? a3 : 971 (a1 )) 972 V V,S,S r[0]= ( a1[0] <= a2) ? a2 : 973 ( (a1[0]>=a3) ? a3 : 974 (a1[0] )) 975 r[1]= ( a1[1] <= a2) ? a2 : 976 ( (a1[1]>=a3) ? a3 : 977 (a1[1] )) 978 r[2]= ( a1[2] <= a2) ? a2 : 979 ( (a1[2]>=a3) ? a3 : 980 (a1[2] )) 981 r[3]= ( a1[3] <= a2) ? a2 : 982 ( (a1[3]>=a3) ? a3 : 983 (a1[3] )) 984 V V,V,S r[0]= ( a1[0] <= a2[0]) ? a2[0] : 985 ( (a1[0]>=a3) ? a3 : 986 (a1[0] )) 987 r[1]= ( a1[1] <= a2[1]) ? a2[1] : 988 ( (a1[1]>=a3) ? a3 : 989 (a1[1] )) 990 r[2]= ( a1[2] <= a2[2]) ? a2[2] : 991 ( (a1[2]>=a3) ? a3 : 992 (a1[2] )) 993 r[3]= ( a1[3] <= a2[3]) ? a2[3] : 994 ( (a1[3]>=a3) ? a3 : 995 (a1[3] )) 996 V V,S,V r[0]= ( a1[0] <= a2) ? a2 : 997 ( (a1[0]>=a3[0]) ? a3[0] : 998 (a1[0] )) 999 r[1]= ( a1[1] <= a2) ? a2 : 1000 ( (a1[1]>=a3[1]) ? a3[1] : 1001 (a1[1] )) 1002 r[2]= ( a1[2] <= a2) ? a2 : 1003 ( (a1[2]>=a3[2]) ? a3[2] : 1004 (a1[2] )) 1005 r[3]= ( a1[3] <= a2) ? a2 : 1006 ( (a1[3]>=a3[3]) ? a3[3] : 1007 (a1[3] )) 1008 V V,V,V r[0]= ( a1[0] <= a2[0]) ? a2[0] : 1009 ( (a1[0]>=a3[0]) ? a3[0] : 1010 (a1[0] )) 1011 r[1]= ( a1[1] <= a2[1]) ? a2[1] : 1012 ( (a1[1]>=a3[1]) ? a3[1] : 1013 (a1[1] )) 1014 r[2]= ( a1[2] <= a2[2]) ? a2[2] : 1015 ( (a1[2]>=a3[2]) ? a3[2] : 1016 (a1[2] )) 1017 r[3]= ( a1[3] <= a2[3]) ? a2[3] : 1018 ( (a1[3]>=a3[3]) ? a3[3] : 1019 (a1[3] )) 1020 1021OP_FLOOR_EXT 1 S S r = FLOOR(a1) 1022 V S r[0] = FLOOR(a1) 1023 r[1] = FLOOR(a1) 1024 r[2] = FLOOR(a1) 1025 r[3] = FLOOR(a1) 1026 V V r[0] = FLOOR(a1[0]) 1027 r[1] = FLOOR(a1[1]) 1028 r[2] = FLOOR(a1[2]) 1029 r[3] = FLOOR(a1[3]) 1030 1031OP_ROUND_EXT 1 S S r = FLOOR(a1 + 0.5) 1032 V S r[0] = FLOOR(a1 + 0.5) 1033 r[1] = FLOOR(a1 + 0.5) 1034 r[2] = FLOOR(a1 + 0.5) 1035 r[3] = FLOOR(a1 + 0.5) 1036 V V r[0] = FLOOR(a1[0] + 0.5) 1037 r[1] = FLOOR(a1[1] + 0.5) 1038 r[2] = FLOOR(a1[2] + 0.5) 1039 r[3] = FLOOR(a1[3] + 0.5) 1040 1041OP_EXP_BASE_2_EXT 1 S S r = 2 ^ a1 1042 1043OP_LOG_BASE_2_EXT 1 S S r = (a1==0) ? MINUS_INF : 1044 LOG2(a1) 1045 r is undefined if a1 < 0 1046 1047OP_POWER_EXT 2 S S,S r = a1 ^ a2 1048 r is undefined if a1 < 0 1049 and -1 < a2 < 1 1050 1051OP_RECIP_EXT 1 S S r = (a1==0) ? INF : 1052 1.0 / a1 1053 1054OP_RECIP_SQRT_EXT 1 S S r = (a1==0) ? INF : 1055 1.0 / SQRT(a1) 1056 r is undefined if a1 < 0 1057 1058OP_SUB_EXT 2 S S,S r = a1 - a2 1059 V S,S r[0] = a1 - a2 1060 r[1] = a1 - a2 1061 r[2] = a1 - a2 1062 r[3] = a1 - a2 1063 V S,V r[0] = a1 - a2[0] 1064 r[1] = a1 - a2[1] 1065 r[2] = a1 - a2[1] 1066 r[3] = a1 - a2[3] 1067 V V,S r[0] = a1[0] - a2 1068 r[1] = a1[1] - a2 1069 r[2] = a1[2] - a2 1070 r[3] = a1[3] - a2 1071 V V,V r[0] = a1[0] - a2[0] 1072 r[1] = a1[1] - a2[1] 1073 r[2] = a1[2] - a2[2] 1074 r[3] = a1[3] - a2[3] 1075 1076OP_CROSS_PRODUCT_EXT 2 V V,V r[0] = a1[1] * a2[2] - 1077 a2[1] * a1[2] 1078 r[1] = a1[2] * a2[0] - 1079 a2[2] * a1[0] 1080 r[2] = a1[0] * a2[1] - 1081 a2[0] * a1[1] 1082 r[3] = 1 1083 1084OP_MULTIPLY_MATRIX_EXT 2 V M,V r[0] = a2[0] * a1[0] + 1085 a2[1] * a1[4] + 1086 a2[2] * a1[8] + 1087 a2[3] * a1[12] 1088 r[1] = a2[0] * a1[1] + 1089 a2[1] * a1[5] + 1090 a2[2] * a1[9] + 1091 a2[3] * a1[13] 1092 r[2] = a2[0] * a1[2] + 1093 a2[1] * a1[6] + 1094 a2[2] * a1[10] + 1095 a2[3] * a1[14] 1096 r[3] = a2[0] * a1[3] + 1097 a2[1] * a1[7] + 1098 a2[2] * a1[11] + 1099 a2[3] * a1[15] 1100 1101 1102 1103 1104 A special operation is OP_INDEX_EXT. It is special in that it 1105 indexes a contiguous block of ids generated by a single call to 1106 GenSymbolsEXT. The value placed in res is the data item 1107 represented by: 1108 1109 arg2 + int( value(arg1) ) 1110 1111 This allows data to be indexed on a per-vertex basis. The results 1112 are undefined if the offset is outside the range of the ids 1113 returned by the single call to GenSymbolsEXT. 1114 Additionally vector data can be rearranged by using the 1115 following call: 1116 1117 void SwizzleEXT( uint res, uint in, enum outX, enum outY, enum outZ 1118 enum outW ) 1119 1120 where in can be any vector value (VARIANT_EXT, 1121 GLOBAL_CONSTANT_EXT, LOCAL_CONSTANT_EXT, or LOCAL_EXT), and outX, 1122 outY, outZ, and outW may be one of X_EXT, Y_EXT, Z_EXT, W_EXT, 1123 NEGATIVE_X_EXT, NEGATIVE_Y_EXT, NEGATIVE_Z_EXT, NEGATIVE_W_EXT, 1124 ZERO_EXT, ONE_EXT, and NEGATIVE_ONE_EXT, and res is one of 1125 OUTPUT_VERTEX_EXT, OUTPUT_COLOR#_EXT, OUTPUT_TEXTURE_COORD#_EXT, 1126 or a data id defined by GenSymbolsEXT (with it's storage type 1127 set as LOCAL_EXT). The out[XYZW] parameters specify what value 1128 should be placed in the res vector. 1129 Vector data can also be masked by using the following call: 1130 1131 void WriteMaskEXT( unint res, uint in, enum outX, enum outY, 1132 enum outZ, enum outW ) 1133 1134 where in is a vector value out[XYZW] are either GL_TRUE or 1135 GL_FALSE, and res is one of OUTPUT_VERTEX_EXT, OUTPUT_COLOR#_EXT, 1136 OUTPUT_TEXTURE_COORD#_EXT, or a data id defined by GenSymbolsEXT 1137 (with it's storage type set as LOCAL_EXT). For each output 1138 component marked TRUE, the source is copied into the destination, 1139 and for all components marked FALSE, the destination component 1140 is unchanged. 1141 Individual components of vector and matrix data can be 1142 accessed and modified by the following operations: 1143 1144 void InsertComponentEXT( uint res, uint src, uint num ) 1145 void ExtractComponentEXT( uint res, uint src, uint num ) 1146 1147 InsertComponentEXT allows a scalar within a vector or a vector 1148 within a matrix to be replaced. If src is a scalar, then res must 1149 be a vector, and if src is a vector, res must be a matrix. The 1150 num parameter controls which scalar or vector will be replaced. 1151 The mappings are as follows: 1152 1153 Num Type Operation 1154 ------ ---- ------------------- 1155 0 S res[0] = src 1156 0 V res[0] = src[0] 1157 res[4] = src[1] 1158 res[8] = src[2] 1159 res[12] = src[3] 1160 1161 1 S res[1] = src 1162 1 V res[1] = src[0] 1163 res[5] = src[1] 1164 res[9] = src[2] 1165 res[13] = src[3] 1166 1167 2 S res[2] = src 1168 2 V res[2] = src[0] 1169 res[6] = src[1] 1170 res[10] = src[2] 1171 res[14] = src[3] 1172 1173 3 S res[3] = src 1174 3 V res[3] = src[0] 1175 res[7] = src[1] 1176 res[11] = src[2] 1177 res[15] = src[3] 1178 1179 If the num parameter is greater than 3, the error INVALID_VALUE is 1180 generated. The opposite capability is provided by 1181 ExtractComponentEXT. Its arguments are either a matrix src and a 1182 vector res, or a vector src and a scalar res. Other combinations 1183 result in the error ILLEGAL_OPERATION. As with InsertComponentEXT, 1184 values for num greater than 3 generate the error INVALID_VALUE. 1185 1186 There are four resources consumed when loading a vertex shader 1187 program: instruction storage, variant storage, constant storage, 1188 and local storage. The maximum values for these resources in a 1189 software implementation may be queried by calling GetIntegerv, 1190 GetFloatv, and GetDoublev with MAX_VERTEX_SHADER_INSTRUCTIONS_EXT, 1191 MAX_VERTEX_SHADER_VARIANTS_EXT, MAX_VERTEX_SHADER_INVARIANTS_EXT, 1192 MAX_VERTEX_SHADER_LOCAL_CONSTANTS_EXT, and 1193 MAX_VERTEX_SHADER_LOCALS_EXT respectively. Since a software 1194 implementation may co-exist with a hardware implementation with 1195 stricter resource limitations the resources available for a 1196 hardware implementation may be queried separately using 1197 MAX_OPTIMIZED_VERTEX_SHADER_INSTRUCTIONS_EXT, 1198 MAX_OPTIMIZED_VERTEX_SHADER_VARIANTS_EXT, 1199 MAX_OPTIMIZED_VERTEX_SHADER_INVARIANTS_EXT, 1200 MAX_OPTIMIZED_VERTEX_SHADER_LOCAL_CONSTANTS_EXT, and 1201 MAX_OPTIMIZED_VERTEX_SHADER_LOCALS_EXT. In implementations that 1202 operate purely in SW or purely in HW, these numbers may be 1203 identical to the max values. The number of these resources 1204 consumed by the current vertex shader program may be queried by 1205 calling GetIntegerv, GetFloatv, and GetDoublev with 1206 VERTEX_SHADER_INSTRUCTIONS_EXT, VERTEX_SHADER_VARIANTS_EXT, 1207 VERTEX_SHADER_LOCAL_CONSTANTS_EXT, VERTEX_SHADER_INVARIANTS_EXT, 1208 and VERTEX_SHADER_LOCALS_EXT. 1209 Additionally, an implementation reports where a vertex shader 1210 program falls within all the optimized limits by a query of 1211 VERTEX_SHADER_OPTIMIZED_EXT. This boolean value will be true 1212 if the vertex shader program consumes less than the maximum 1213 optimizable resources in all catagories. This value is provided 1214 as a convenient shortcut for a common operation. 1215 Should a vertex shader program not fit within the 1216 implementation defined limits, then the program is considered 1217 undefined. When a vertex is submitted to an undefined program 1218 vertex shaders are implicitly disabled and GL per-vertex 1219 processing applies. 1220 The methods employed for counting operations and data 1221 usage are not intended to be identical from implementation to 1222 implementation. Instead, the reported totals should be based 1223 on micro-ops. The micro-ops represent the cost of the operation 1224 or data-type for the particular implementation. As a result, 1225 certain operations may take zero or multiple micro-ops. The 1226 only requirement is that micro-ops always be reported in a 1227 consistent manner, even if the vertex shader programs can be 1228 potentially implemented by different hardware." 1229 1230 1231Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization): 1232 1233 None 1234 1235Additions to Chapter 4: 1236 1237 None 1238 1239Additions to Chapter 5: 1240 1241 None 1242 1243Additions to Chapter 6: 1244 1245 - (New section after 6.1.11) User specified vertex processing queries 1246 "The commands 1247 1248 boolean IsVariantEnabledEXT( uint id, enum cap); 1249 void GetVariantBooleanvEXT( uint id, enum value, boolean *data); 1250 void GetVariantIntegervEXT( uint id, enum value, int *data); 1251 void GetVariantFloatvEXT( uint id, enum value, float *data); 1252 void GetVariantPointervEXT( uint id, enum value, void **data); 1253 void GetInvariantBooleanvEXT( uint id, enum value, boolean *data); 1254 void GetInvariantIntegervEXT( uint id, enum value, int *data); 1255 void GetInvariantFloatvEXT( uint id, enum value, float *data); 1256 void GetLocalConstantBooleanvEXT( uint id, enum value, boolean *data); 1257 void GetLocalConstantIntegervEXT( uint id, enum value, int *data); 1258 void GetLocalConstantFloatvEXT( uint id, enum value, float *data); 1259 1260 are used to retrieve state relating to symbols used in vertex 1261 shader programs. They take the id of the symbol for which 1262 information is being queried. If the symbol is invalid in the 1263 present shader or the storage type is inconsistent with the 1264 called function the error INVALID_VALUE is generated. All 1265 values returned are in the context of the presently bound vertex 1266 shader." 1267 1268Additions to the GLX Specification 1269 1270 Unknown 1271 1272GLX Protocol 1273 1274 Unknown 1275 1276Errors 1277 1278INVALID_VALUE is generated if the <num> parameter to InsertComponentEXT or 1279ExtractComponentEXT is grater than 3. 1280 1281ILLEGAL_OPERATION is generated if the <src> parameter to InsertComponentsEXT 1282is of type VECTOR_EXT and the <res> parameter is not of type MATRIX_EXT. 1283 1284ILLEGAL_OPERATION is generated if the <src> parameter to InsertComponentsEXT 1285is of type SCALAR_EXT and the <res> parameter is not of type VECTOR_EXT. 1286 1287ILLEGAL_OPERATION is generated if the <src> parameter to ExtractComponentsEXT 1288is of type VECTOR_EXT and the <res> parameter is not of type SCALAR_EXT. 1289 1290ILLEGAL_OPERATION is generated if the <src> parameter to ExtractComponentsEXT 1291is of type MATRIX_EXT and the <res> parameter is not of type VECTOR_EXT. 1292 1293ILLEGAL_OPERATION is generated if the SetLocalConstantEXT is used multiple 1294times on a single symbol in the context of defining a shader. 1295 1296ILLEGAL_OPERATION is generated if the arguments provided to ShaderOpEXT are 1297inconsistent with the table of operations. An example would be specifying 1298a SCALAR_EXT result to the addition of 2 vectors. 1299 1300ILLEGAL_OPERATION is generated if the datatype of the <res> or <in> 1301parameters to WriteMaskEXT or SwizzleEXT is not VECTOR_EXT. 1302 1303ILLEGAL_OPERATION is generated if if the <res> parameter of ShaderOPEXT, 1304SwizzleEXT, or WriteMaskEXT does is not a local or output storage type. 1305 1306New State 1307 1308Added after Table 6.27 Vertex Shader State: 1309 1310 Get Value Get Command Type Initial Value Attribute 1311 ---------------------------- ------------- ------- --------------- -------------- 1312 VERTEX_SHADER_INSTRUCTIONS_EXT GetIntegerv Z+ 0 - 1313 VERTEX_SHADER_VARIANTS_EXT GetIntegerv Z+ 0 - 1314 VERTEX_SHADER_INVARIANTS_EXT GetIntegerv Z+ 0 - 1315 VERTEX_SHADER_LOCAL_CONSTANTS_EXT GetIntegerv Z+ 0 - 1316 VERTEX_SHADER_LOCALS_EXT GetIntegerv Z+ 0 - 1317 VERTEX_SHADER_OPTIMIZED_EXT GetBooleanv Z+ False - 1318 VERTEX_SHADER_EXT IsEnabled B False - 1319 VERTEX_SHADER_BINDING_EXT GetIntegerv Z+ 0 - 1320 1321Added new Table Vertex Shader symbol state: 1322 1323 Get Value Get Command Type Initial Value Attribute 1324 ---------------------------- ------------- ------- --------------- -------------- 1325 VARIANT_VALUE_EXT GetVariantFloatv n * R Undefined - 1326 VARIANT_DATATYPE_EXT GetVariantIntegerv Z Undefined - 1327 VARIANT_ARRAY_STRIDE_EXT GetVariantIntegerv Z 0 - 1328 VARIANT_ARRAY_TYPE_EXT GetVariantIntegerv Z8 FLOAT - 1329 VARIANT_ARRAY_POINTER_EXT GetVariantPointerv Y 0 - 1330 VARIANT_ARRAY_EXT IsEnabled B FALSE - 1331 INVARIANT_VALUE_EXT GetInvariantFloatv n * R Undefined - 1332 INVARIANT_DATATYPE_EXT GetInvariantIntegerv Z Undefined - 1333 LOCAL_CONSTANT_VALUE_EXT GetLocalConstantFloatv n * R Undefined - 1334 LOCAL_CONSTANT_DATATYPE_EXT GetLocalConstantIntegerv n * R Undefined - 1335 1336 1337New Implementation Dependent State 1338 1339 Get Value Get Command Type Minimum Value 1340 --------------------------------------- ------------- ------- --------------- 1341 MAX_VERTEX_SHADER_INSTRUCTIONS_EXT GetIntegerv Z+ 32 1342 MAX_VERTEX_SHADER_VARIANTS_EXT GetIntegerv Z+ 4 1343 MAX_VERTEX_SHADER_INVARIANTS_EXT GetIntegerv Z+ 16 1344 MAX_VERTEX_SHADER_LOCAL_CONSTANTS_EXT GetIntegerv Z+ 8 1345 MAX_VERTEX_SHADER_LOCALS_EXT GetIntegerv Z+ 4 1346 MAX_OPTIMIZED_VERTEX_SHADER_INSTRUCTIONS_EXT GetIntegerv Z+ 32 1347 MAX_OPTIMIZED_VERTEX_SHADER_VARIANTS_EXT GetIntegerv Z+ 4 1348 MAX_OPTIMIZED_VERTEX_SHADER_INVARIANTS_EXT GetIntegerv Z+ 16 1349 MAX_OPTIMIZED_VERTEX_SHADER_LOCAL_CONSTANTS_EXT GetIntegerv Z+ 8 1350 MAX_OPTIMIZED_VERTEX_SHADER_LOCALS_EXT GetIntegerv Z+ 4 1351 1352