1Name 2 3 ARB_vertex_program 4 5Name Strings 6 7 GL_ARB_vertex_program 8 9Contributors 10 11 Kurt Akeley 12 Allen Akin 13 Ben Ashbaugh 14 Bob Beretta 15 John Carmack 16 Matt Craighead 17 Ken Dyke 18 Steve Glanville 19 Michael Gold 20 Evan Hart 21 Mark Kilgard 22 Bill Licea-Kane 23 Barthold Lichtenbelt 24 Erik Lindholm 25 Benj Lipchak 26 Bill Mark 27 James McCombe 28 Jeremy Morris 29 Brian Paul 30 Bimal Poddar 31 Thomas Roell 32 Jeremy Sandmel 33 Jon Paul Schelter 34 Geoff Stahl 35 John Stauffer 36 Nick Triantos 37 38Contact 39 40 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 41 42Notice 43 44 Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at 45 http://www.khronos.org/registry/speccopyright.html 46 47Specification Update Policy 48 49 Khronos-approved extension specifications are updated in response to 50 issues and bugs prioritized by the Khronos OpenGL Working Group. For 51 extensions which have been promoted to a core Specification, fixes will 52 first appear in the latest version of that core Specification, and will 53 eventually be backported to the extension document. This policy is 54 described in more detail at 55 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 56 57IP Status 58 59 NVIDIA claims to own intellectual property related to this extension, and 60 has signed an ARB Contributor License agreement licensing this 61 intellectual property. 62 63 Microsoft claims to own intellectual property related to this extension. 64 65Status 66 67 Complete. Approved by ARB on June 18, 2002 68 69Version 70 71 Last Modified Date: 07/25/07 72 Revision: 46 73 74Number 75 76 ARB Extension #26 77 78Dependencies 79 80 Written based on the wording of the OpenGL 1.3 specification and requires 81 OpenGL 1.3. 82 83 ARB_vertex_blend and EXT_vertex_weighting affect the definition of this 84 extension. 85 86 ARB_matrix_palette affects the definition of this extension. 87 88 ARB_point_parameters and EXT_point_parameters affect the definition of 89 this extension. 90 91 EXT_secondary_color affects the definition of this extension. 92 93 EXT_fog_coord affects the definition of this extension. 94 95 ARB_transpose_matrix affects the definition of this extension. 96 97 NV_vertex_program interacts with this extension. 98 99 EXT_vertex_shader interacts with this extension. 100 101Overview 102 103 Unextended OpenGL mandates a certain set of configurable per-vertex 104 computations defining vertex transformation, texture coordinate generation 105 and transformation, and lighting. Several extensions have added further 106 per-vertex computations to OpenGL. For example, extensions have defined 107 new texture coordinate generation modes (ARB_texture_cube_map, 108 NV_texgen_reflection, NV_texgen_emboss), new vertex transformation modes 109 (ARB_vertex_blend, EXT_vertex_weighting), new lighting modes (OpenGL 1.2's 110 separate specular and rescale normal functionality), several modes for fog 111 distance generation (NV_fog_distance), and eye-distance point size 112 attenuation (EXT/ARB_point_parameters). 113 114 Each such extension adds a small set of relatively inflexible 115 per-vertex computations. 116 117 This inflexibility is in contrast to the typical flexibility provided by 118 the underlying programmable floating point engines (whether micro-coded 119 vertex engines, DSPs, or CPUs) that are traditionally used to implement 120 OpenGL's per-vertex computations. The purpose of this extension is to 121 expose to the OpenGL application writer a significant degree of per-vertex 122 programmability for computing vertex parameters. 123 124 For the purposes of discussing this extension, a vertex program is a 125 sequence of floating-point 4-component vector operations that determines 126 how a set of program parameters (defined outside of OpenGL's Begin/End 127 pair) and an input set of per-vertex parameters are transformed to a set 128 of per-vertex result parameters. 129 130 The per-vertex computations for standard OpenGL given a particular set of 131 lighting and texture coordinate generation modes (along with any state for 132 extensions defining per-vertex computations) is, in essence, a vertex 133 program. However, the sequence of operations is defined implicitly by the 134 current OpenGL state settings rather than defined explicitly as a sequence 135 of instructions. 136 137 This extension provides an explicit mechanism for defining vertex program 138 instruction sequences for application-defined vertex programs. In order 139 to define such vertex programs, this extension defines a vertex 140 programming model including a floating-point 4-component vector 141 instruction set and a relatively large set of floating-point 4-component 142 registers. 143 144 The extension's vertex programming model is designed for efficient 145 hardware implementation and to support a wide variety of vertex programs. 146 By design, the entire set of existing vertex programs defined by existing 147 OpenGL per-vertex computation extensions can be implemented using the 148 extension's vertex programming model. 149 150Issues 151 152 (1) What should this extension be called? 153 154 RESOLVED: ARB_vertex_program. DirectX 8 refers to its similar 155 functionality as "vertex shaders". This is a confusing term because 156 shaders are usually assumed to operate at the fragment or pixel level, 157 not the vertex level. 158 159 Conceptually, what the extension defines is an application-defined 160 program (admittedly limited by its sequential execution model) for 161 processing vertices so the "vertex program" term is more accurate. 162 163 Some of the API machinery in this extension for describing programs 164 should be useful for extending other OpenGL operations with programs 165 (though other types of programs may look very different from vertex 166 programs). 167 168 (2) What terms are important to this specification? 169 170 vertex program mode - When vertex program mode is enabled, vertices are 171 transformed by an application-defined vertex program. 172 173 conventional GL vertex transform mode - When vertex program mode is 174 disabled (or the extension is not supported), vertices are transformed 175 by GL's conventional texgen, lighting, and transform state. 176 177 vertex program - An application-defined program used to transform 178 vertices when vertex program mode is enabled. 179 180 program target - A type or class of program. This extension supports 181 the VERTEX_PROGRAM_ARB target. Future extensions may add other program 182 targets. 183 184 program object - An object maintained internal to OpenGL that 185 encapsulates a program and a set of associated state. Operations 186 performed on program objects include loading a program, binding, 187 generating program object names, querying state, and deleting. 188 189 program name - Each program object has an associated unsigned integer, 190 called the program name. Applications refer to a program object using 191 the program name. 192 193 current program - Each program target may have a current program object. 194 For vertex programs, the current program is executed whenever a vertex 195 is specified when vertex program mode is enabled. 196 197 default program - Each program target has a default program object, 198 referred to using a program name of zero. The current program for each 199 program target is initially the default program for that target. 200 201 program execution environment - A set of resources, instructions, and 202 semantic rules used to execute a program. Each program target may 203 support one or more execution environment -- new execution environments 204 may provide new instructions, resources, or execution rules. Program 205 strings must specify the execution environment that should be used to 206 execute the program. 207 208 program options - An optional feature that modifies the rules of the 209 execution environment. Vertex programs specify the options that they 210 require at the beginning of the program. 211 212 vertex attribute - GL state associated with vertices that can vary per 213 vertex. 214 215 conventional vertex attributes - Per-vertex attributes used in 216 conventional GL vertex transform mode, including colors, normals, 217 texture coordinate sets. 218 219 generic vertex attributes - An array of 16+ 4-component vectors added by 220 this extension. Generic vertex attributes can be used by vertex 221 programs but are unused in conventional GL vertex transform mode. 222 223 program parameter - A set of constants that are available for vertex 224 programs to use during their execution. Program parameters include 225 program environment parameters, program local parameters, conventional 226 GL state, and program constants. 227 228 program environment parameter - A set of 96+ 4-component vectors 229 belonging to the GL context that can be used as constants during the 230 execution of any vertex program. 231 232 program local parameter - A set of 96+ 4-component vectors belonging to 233 a vertex program object that can be used as constants during the 234 execution of the corresponding vertex program. Program local parameters 235 can not be used by any other vertex programs. 236 237 program constants - Constants declared in the text of a program may be 238 used during the execution of that program. 239 240 program temporaries - A set of 12+ 4-component vectors to hold temporary 241 results that can be read or written during the execution of a vertex 242 program. 243 244 program address registers - A set of 1+ 1-component integer vectors that 245 can be used to perform variable indirect accesses to program parameter 246 arrays during the execution of a vertex program. Address registers are 247 specified as vectors to allow for future extensions supporting multiple 248 address register components. 249 250 program results - A set of 4-component vectors to hold the final results 251 of a vertex program. The program results correspond closely to the set 252 of vertex attributes used during primitive assembly and rasterization. 253 254 program variables - Variable names used to identify a specific vertex 255 attribute, program parameter, temporary, address register, or result. 256 257 program binding - A program statement that declares a variable and 258 associates it with a specific vertex attribute, program parameter, or 259 program result. 260 261 implicit binding - When an executable instruction refers to a specific 262 vertex attribute, program parameter, program result, or constant by 263 name, without using an explicit program binding statement. When such 264 values are encountered, an implicit binding to an anonymous variable 265 name is created. 266 267 program invocation - The act of implicitly or explicitly kicking off 268 program execution. Vertex programs are invoked automatically when 269 vertex program mode is enabled and vertices are received. Vertex 270 programs are also invoked automatically when the current raster position 271 is specified. 272 273 (3) What part of OpenGL do vertex programs specifically bypass? 274 275 Vertex programs bypass the following OpenGL functionality: 276 277 - The modelview and projection matrix vertex transformations. 278 279 - Vertex weighting/blending (ARB_vertex_blend). 280 281 - Normal transformation, rescaling, and normalization. 282 283 - Color material. 284 285 - Per-vertex lighting. 286 287 - Texture coordinate generation and texture matrix transformations. 288 289 - Per-vertex point size computations in ARB/EXT_point_parameters 290 291 - Per-vertex fog coordinate computations in EXT_fog_coord and 292 NV_fog_distance. 293 294 - Client-defined clip planes. 295 296 - The normalization of AUTO_NORMAL evaluated normals 297 298 - All of the above, when computing the current raster position. 299 300 Operations not subsumed by vertex programs 301 302 - Clipping to the view frustum. 303 304 - Perspective divide (division by w). 305 306 - The viewport transformation. 307 308 - The depth range transformation. 309 310 - Front and back color selection (for two-sided lighting and 311 coloring). 312 313 - Clamping the primary and secondary colors to [0,1]. 314 315 - Primitive assembly and subsequent operations. 316 317 - Evaluators (except the AUTO_NORMAL normalization). 318 319 (5) This extension adds a set of generic vertex attributes to the existing 320 conventional attributes. The sum of the number of generic and 321 conventional attributes supported on a given platform may exceed the total 322 number of per-vertex attributes supported in hardware. How should this 323 situation be handled? 324 325 RESOLVED: Implementations may alias conventional and generic vertex 326 attributes, where pairs of conventional and generic vertex attributes 327 share the same storage. Such aliasing will effectively reduce the 328 number of vertex attributes a hardware platforms. While implementations 329 may alias attributes, that behavior is not required. To accommodate both 330 behaviors, changing a generic vertex attribute leaves the corresponding 331 conventional attribute undefined, and vice versa. 332 333 This undefined behavior is a compromise between the existing 334 EXT_vertex_shader extension (which does not permit aliasing) and the 335 NV_vertex_program extension (which requires aliasing). The mapping 336 between generic and conventional vertex attributes is found in Table X.1 337 below. This mapping is taken from the NV_vertex_program specification 338 and generalized to define behavior for >8 texture coordinate sets. 339 340 Applications that mix conventional and generic vertex attributes in a 341 single rendering pass should be careful to avoid using attributes that 342 may alias. To limit inadvertent use of such attributes, loading a 343 vertex program that used a pair of attributes that may alias is 344 guaranteed to fail. Applications requiring a small number of generic 345 vertex attributes can always safely use generic attributes 6 and 7, and 346 any supported attributes corresponding to unused or unsupported texture 347 units. For example, if an implementation supports only four texture 348 units, generic attributes 12 through 15 can always be used safely. 349 350 (6) Should there be a "VertexAttribs" entry point to specify multiple 351 vertex attributes in one immediate mode call. 352 353 RESOLVED: No. Not providing such functionality serves to reduce the 354 already large number of required immediate mode entry points. A 355 "VertexAttribs" command would improve the efficiency of vertex attribute 356 transfer, but vertex arrays or display lists should still be better. 357 358 (7) Should a full complement of data types (signed and unsigned bytes, 359 shorts, and ints, as well as floats and doubles) be supported for vertex 360 attributes? Should fixed-point data types be supported in both normalized 361 (map the range to [0,1] or [-1,1]) and unnormalized form? 362 363 RESOLVED: For vertex arrays, all data type combinations are supported. 364 365 For immediate mode, a smaller subset is supported, to limit the number 366 of immediate-mode entry points added by this extension. In fully 367 general form, 112 immediate-mode entry points (4 sizes x 2 368 vector/non-vector x 14 data types) would be required. 369 370 Immediate mode support is available for non-normalized shorts, floats, 371 and doubles for all component counts. Additionally, immediate mode 372 support is available for 4-component vectors of all data types 373 (normalized and unnormalized). 374 375 Note also that in immediate mode, the "N" qualifier in function names 376 like VertexAttrib4Nub will be used to indicate that fixed-point data 377 should be normalized. 378 379 (8) How should applications indicate that fixed-point generic vertex 380 attribute array components should be converted to [-1,+1] or [0,1] ranges? 381 382 RESOLVED: The function VertexAttribPointerARB takes a boolean argument 383 <normalized> that indicates whether fixed-point array data should be 384 normalized to [-1,+1] or [0,1]. 385 386 One alternate approach would have been to extend to set of enumerants to 387 include values such as NORMALIZED_UNSIGNED_BYTE_ARB. Adding such 388 enumerants in some sense implies that UNSIGNED_BYTE is not normalized, 389 even though it usually is. 390 391 (9) In unextended OpenGL, calling Vertex() specifies a vertex and causes 392 vertex transformation operations to be performed on the vertex. Should 393 there be an equivalent method to specify a vertex using generic vertex 394 attributes? If so, how should this be accomplished? 395 396 RESOLVED: Setting generic vertex attribute zero will always specify a 397 vertex. Vertex*(...) and VertexAttrib*(0,...) are specified to be 398 equivalent, whether or not vertex program mode is enabled. Allowing 399 generic vertex attribute zero to specify a vertex allows applications to 400 write vertex programs that use only generic attributes; otherwise, 401 applications would have had to use Vertex() to provoke vertex 402 processing. 403 404 (10) How is this extension different from previous vertex program 405 extensions, such as EXT_vertex_shader or NV_vertex_program? What pitfalls 406 are there in porting vertex programs to/from this extension? 407 408 RESOLVED: See "Interactions with NV_vertex_program" and "Interactions 409 with EXT_vertex_shader" sections near the end of this specification. 410 411 (11) Should program parameter variables bound to GL state be updated 412 automatically after the bound state changes? If so, when? 413 414 RESOLVED: Yes. Such variables are updated automatically prior to the 415 next vertex program invocation with no application intervention 416 required. A proposal to reduce the burden by requiring a manual "update 417 state" step was considered and rejected. 418 419 (12) How should this specification handle variable bindings to Material 420 state? Material is allowed inside a Begin/End, so material properties are 421 technically per-vertex state. 422 423 RESOLVED: Materials can be bound only as program parameters. Changes 424 to material properties inside a Begin/End will leave the bindings 425 undefined until the subsequent End command. At that point, all material 426 property bindings are guaranteed to be updated, and any material 427 property changes up to the next Begin command are guaranteed to take 428 effect immediately. 429 430 Supporting per-vertex material properties places additional pressure on 431 the number of per-vertex bindings an implementation can support, which 432 was already a problem. See issue (5). 433 434 In practice, material properties are usually not changed in this manner. 435 Applications needing to change material properties inside a Begin/End in 436 vertex program mode can work around this limitation by storing the color 437 in a conventional or generic vertex attribute and modifying the vertex 438 program accordingly. 439 440 (13) What semantic restrictions, if any, should be imposed on binding the 441 same GL state to multiple variables? The grammar permits such bindings, 442 but allowing this behavior means that single state updates must update 443 multiple variables. 444 445 RESOLVED: Cases where a single state update necessarily requires 446 updating multiple variables are disallowed. The only restriction 447 resulting from this decision is that a single state variable can not be 448 bound more than once in the collection of arrays that are accessed using 449 relative addressing (at run time). The driver can and will coalesce all 450 other bindings accessed only at fixed offsets into a single binding. 451 452 This restriction and a little driver work allows the same state variable 453 to be used multiple times without requiring that a single state change 454 update multiple variables. 455 456 (14) What semantic restrictions, if any, should be imposed on using 457 multiple vertex attributes or program parameters in the same instruction? 458 459 RESOLVED: None. If the underlying hardware implementation does not 460 support reads of multiple attributes or program parameters, the driver 461 may need to transparently insert additional instructions and/or consume 462 temporaries to perform the operation. 463 464 (15) How and when should related state be combined into a single program 465 parameter binding? Additionally, should any values derived from core GL 466 state be exposed, too? 467 468 RESOLVED: Related state should be combined when possible, as long as 469 the binding name remains somewhat sensible. Additionally, certain 470 pre-computed state items useful for performance reasons are also 471 exposed. In particular, the following GL state combinations are 472 supported: 473 474 * Light attenuation constants and the spot light exponent are combined 475 into a single vector called "state.light[n].attenuation" (spot 476 lights can attenuate the lit result). 477 478 * Spot light direction and cutoff angle cosine are called 479 "state.light[n].spot.direction" (cutoff is directional information). 480 Binding the cutoff angle itself is pretty useless, so the cosine is 481 used. 482 483 * A pre-computed half angle for lighting with infinite lights and an 484 infinite viewer is provided and called "state.light[n].half". 485 486 * Pre-computed products of ambient, diffuse, and specular light colors 487 with the corresponding front or back material colors are supported, 488 and are called "state.lightprod[n].<face>.<property>". 489 490 * Exponential fog density, linear fog start and end parameters, as 491 well as the pre-computed reciprocal of (end-start) are combined into 492 one vector called "state.fog.params". 493 494 * The core point size, minimum and maximum size clamps 495 (ARB_point_parameters), and multisample fade size threshold 496 (ARB_point_parameters) are combined into a single vector called 497 "state.point.size". 498 499 * Precomputed transpose, inverse, and inverse transpose matrices are 500 supported for each base matrix type. 501 502 (16) Should the initial values of temporaries and results be undefined? 503 504 RESOLVED: Since the underlying hardware differs, it was decided to 505 leave these values uninitalized. There are a few issues related to this 506 behavior that programs should keep in mind: 507 508 * Since any results not written by the program are undefined, programs 509 should write to all result registers that are needed during 510 rasterization. 511 512 * In particular, the initial vertex position result is undefined, and 513 will remain undefined if not written by a program. To achieve 514 proper results, vertex programs should be careful to write to all 515 four components of the vertex position. Otherwise, primitives may 516 be completely clipped or produce undefined results during 517 rasterization. There is no semantic requirement that programs must 518 write a transformed vertex position, so erroneous programs will load 519 succesfully, but will produce undefined (and probably useless) 520 results. Such a semantic requirement may be impossible to enforce 521 in future language versions that support run-time branching. 522 523 * Since vertex programs may be executed when the raster position is 524 set, any attributes not written by the program will result in 525 undefined state in the current raster position. Programs should 526 write to all result registers that would be used when rasterizing 527 pixel primitives using the current raster position. 528 529 * If conventional OpenGL texture mapping operations are performed, a 530 program should always write to the "w" coordinate of any texture 531 coordinates result registers it needs to use. Conventional OpenGL 532 texture accesses always use projective texture coordinates (e.g., 533 s/q, t/q, r/q), even though q is almost always 1.0. An undefined q 534 coordinate (coming from the "w" component of the result register) 535 may produce undefined coordinates on the texture lookup. 536 537 (17) Should vertex programs be required to have a header token and an end 538 token? 539 540 RESOLVED: Yes. The header token for this extension is named 541 "!!ARBvp1.0". The ARB may standardize future language versions which 542 would be expected to have tokens like "!!ARBvp2.0". Vertex programs 543 must end with the "END" token. 544 545 The initial header token reminds the programmer what type of program 546 they are writing. If vertex programs are ever read from disk files, the 547 header token can be used to specifically identify vertex programs. The 548 initial header tokens will also make it easier for programmers to 549 distinguish between multiple types of vertex programs and between vertex 550 programs and another future type of programs. 551 552 We expect that programs may be generated by concatenation of program 553 fragments. The "END" token will hopefully reduce bugs due to specifying 554 an incorrectly concatenated program. 555 556 (18) Should ProgramStringARB take a <program> specifier? Should 557 ProgramLocalParameterARB and GetProgramLocalParameterARB take a <program> 558 specifier? How about GetProgramivARB and GetProgramStringARB? 559 560 RESOLVED: No to all. Instead, these calls are specified to always 561 query or modify the currently bound program object. Using bound objects 562 allows GL implementations to avoid locking and name lookup overhead on 563 each such call. 564 565 This behavior does imply that applications loading a sequence of program 566 objects must bind each in turn. 567 568 (19) Should relative addressing be performed using an address register 569 (load up an integer register) or by taking a floating-point scalar? 570 571 RESOLVED: Address register. It would not be a good idea to support 572 both syntaxes simultaneously, since using a floating-point scalar may 573 consume the only available address register in the process. The current 574 address register syntax can be easily extended to allow for multiple 575 integer registers and/or enable other integer operations in a later 576 extension. 577 578 Using a floating-point index may require an extra instruction on some 579 architectures, and would require optimization work to eliminate 580 redundant loads. Using a floating-point index may consume one of a 581 small number of temporary registers. On the other hand, for 582 implementations without a dedicated address register, it may be 583 necessary to dedicate a general-purpose register (or register component) 584 to hold the address register contents. 585 586 (20) How should user-defined clipping be supported in this specification? 587 588 RESOLVED: User-defined clipping is not supported in standard vertex 589 program mode. User-defined clipping support will be provided for 590 programs that use the "position invariant" option, where all vertex 591 transformation operations are performed by the fixed-function pipeline. 592 593 It is expected that future vertex program extensions or a future 594 language standard may provide more powerful user clipping functionality. 595 596 The options considered were: 597 598 (1) Not at all. Does not work for applications requiring user clipping. 599 User clipping could be supported through a language extension. 600 601 (2) Support only through the "position_invariant" option, where vertex 602 transformation is performed by the fixed-function pipeline. 603 604 (3) Support by using the fixed-function pipeline to generate eye 605 coordinates and perform user clipping as specified for conventional 606 transformation. May not work properly if the vertex transformation 607 doesn't match the standard "multiply by modelview and projection 608 matrices" model. 609 610 (4) Project existing fixed-function clip planes into clip coordinates 611 and perform the clip test in clip space. The clip planes would be 612 transformed by the inverse of the projection matrix, which will not 613 work if the projection matrix is singular. 614 615 (5) Provide a 4-component "user clip coordinate" result that can be 616 bound by a vertex program. User clipping is performed as in 617 unextended OpenGL, using the "user clip coordinate" in place of the 618 non-existant eye coordinates. This approach allows an application 619 to do user clipping in any coordinate system. Clipping would not be 620 independent of primitive tesselation as in the conventional 621 pipeline. Additionally, the implicit transformation of specified 622 clip planes by the modelview matrix may be undesirable (e.g., 623 clipping in object coordinates). 624 625 (6) Provide one or more "clip plane distance" results that can be bound 626 by a vertex program. For conventional clipping applications, vertex 627 programs would compute the dot products normally computed by 628 fixed-function hardware. Additionally, this method would enable 629 additional unconventional clipping effects. Primitives would be 630 clipped to the portion whose interpolated clip distances are greater 631 than or equal to zero. This approach has the same issues as (5). 632 633 (21) How should future vertex program opcodes be named? 634 635 RESOLVED: Three-character names are recommended for brevity. Three 636 character names are not a hard-and-fast requirement; extra characters 637 may be needed for clarity or to disambiguate instructions. 638 639 (22) Should anything be said about the precision used for carrying out the 640 instructions? 641 642 RESOLVED: Not much; precision will vary across platforms. The minimum 643 precision requirements (1 part in 10^5 or roughly 17 bits) are spelled 644 out in section 2.1.1. In practice, implementations will generally 645 provide precision comparable to that obtained using single precision 646 floats. Documenting exact precision across implementations is 647 difficult. Additionally, it is difficult to spell out precision 648 requirements for "compound" operations such as DP4. 649 650 (23) Should this extension support evaluator maps for generic vertex 651 attributes? If so, what attribute sizes should be supported? Note that 652 such maps are not supported at all for texture units except zero. 653 654 RESOLVED: No. Evaluator support has not been consistently extended in 655 previous extensions. For example, neither ARB_multitexture nor OpenGL 656 1.3 provide support for evaluators for texture units other than unit 657 zero. Adding evaluators for generic attributes involves a large amount 658 of new state and complexity, particularly if evaluators should be 659 supported in general form (1, 2, 3, and 4 components, all supported data 660 type). 661 662 (25) The number of generic vertex attributes is implementation-dependent 663 and is at least 16. Each generic vertex attribute has a vertex array 664 enable. Should two new entry points be provided to accept an arbitrary 665 attribute number, or should we reserve a range of enumerants that is 666 "large enough"? 667 668 RESOLVED: Yes. EnableVertexAttribArrayARB and 669 DisableVertexAttribArrayARB. This allows the number of vertex 670 attributes to be unbounded, instead of using a limited range. 671 672 (26) What limits should be imposed on the constants that can be added to 673 or subtracted from the address register for relative addressing? Negative 674 offsets are sometimes useful for shifting down in an array. 675 676 RESOLVED: -64 to +63 should be sufficient for the time being. Offset 677 sizes are limited to allow offsets to be baked into device-dependent 678 instruction encodings. 679 680 (28) What level of precision should be guaranteed for the EXP and LOG 681 instructions? And for the EX2 and LG2 instructions? 682 683 RESOLVED: The low precision EXP and LOG instructions should give at 684 least 10 bits (2^-11 maximum relative error). No specific treatment 685 will be added for EX2/LG2, implying that the computations should at 686 least meet the minimal floating-point precision required by the spec. 687 688 (29) Should incremental program compilation be supported? 689 690 RESOLVED: No. Applications can compile programs just as easily using 691 string concatenation. 692 693 (30) Should the execution environment be identified by the program itself 694 or as an additional "language" parameter to ProgramStringARB? 695 696 RESOLVED: Programs should identify their execution environment in the 697 header. The header (plus any specified options) make it clear what kind 698 of program is being defined. 699 700 (31) Should this extension provide support for character sets other than 701 7-bit ASCII? 702 703 RESOLVED: Provide a <format> argument to ProgramStringARB to allow for 704 future extensions. Only ASCII will be supported by this extension; 705 additional character sets or encodings could be supported using separate 706 extensions. 707 708 (32) Support for "program object" functionality may be applicable to 709 future program targets. Should this functionality be factored out into a 710 separate extension? 711 712 RESOLVED: No, such separation is not necessary. This extension was 713 designed to allow to easily accommodate future program target types. It 714 would be straightforward to put program object functionality into a 715 separate extension, but the functionality provided by that extension 716 would be of no value by itself. 717 718 (33) Should program residency management be supported? 719 720 RESOLVED: No. This functionality can be supported in a separate 721 extension if desired. If may be desirable to address residency 722 management in a more general form, where an application may desire a 723 diverse set of objects (textures, programs) to be resident at once. 724 725 (34) Should program object management APIs (GenProgramsARB, 726 DeleteProgramsARB) work like texture objects or display lists? 727 728 RESOLVED: Texture objects. 729 730 Both approaches have their merits. Pluses for the display list model 731 include: no need to keep around multiple indices if you want to 732 allocate a group of object, contiguous indices may fall out on 733 implementations that share one block allocator for textures and display 734 lists. Pluses for the texture object model: non-contiguous indices may 735 be more optimizable -- new objects can be mapped to empty blocks in a 736 hash table to avoid collisions with existing objects, separate indices 737 are more compatible with a future handle-based object paradigm, and a 738 larger base of extensions using this model. Note that display list 739 allocations needed to be contiguous to support CallLists, but no such 740 requirement for texture or program objects exists for programs. 741 742 (35) Should there be support for a program object zero? With texture 743 objects, texture object zero is "special" because it is the default 744 texture object for each target type. Is there something like this for 745 program objects? 746 747 RESOLVED: Yes. Like texture objects, there should be a separate 748 program object zero for each program type. This allows applications to 749 use vertex programs without needing to generate and manage program 750 objects. 751 752 With texture objects, an object zero was needed for backward 753 compatibility with pre-OpenGL 1.1 applications. There is no such 754 requirement here, but providing an object zero nicely matches the 755 familiar texture object model. 756 757 (36) How should this extension provide feedback on why a program failed to 758 load? 759 760 RESOLVED: Two queries are provided. Calling GetIntegerv() with 761 PROGRAM_ERROR_POSITION_ARB provides the offset of an offending 762 instruction in the program string. An error position of -1 indicates 763 that a program loaded successfully. Calling GetString() with 764 PROGRAM_ERROR_STRING_ARB returns an implementation-dependent error 765 string explaining the reason for the failure. The error string can be 766 queried even on successful program loads to check for warning messages. 767 768 The error string may be kept in a static buffer managed by the GL 769 implementation. Implementations may reuse the same buffer on subsequent 770 calls to ProgramStringARB, so returned error strings are guaranteed to 771 be valid only until the next such call. 772 773 (37) How does ARB_vertex_blend's WEIGHT_SUM_UNITY_ARB mode interact with 774 this extension? This mode allows an application to specify N-1 weights, 775 and have the Nth weight computed by the GL. 776 777 RESOLVED: The ARB_vertex_blend spec (as of May, 2002) specifies that 778 the nth weight is automatically computed by the GL and is effectively 779 current state. In practice, ARB_vertex_blend implementations compute 780 the nth weight on the fly in the fixed-function transformation pipeline, 781 implying that the ARB_vertex_blend spec may require a fix. For the 782 purposes of this extension, the WEIGHT_SUM_UNITY_ARB enable is ignored 783 in vertex program mode. Applications performing a vertex weighting 784 operation in a vertex program are free to compute the extra weight in 785 the program. 786 787 (38) Should program environment parameters be pushed and popped? 788 789 RESOLVED: No. There is no need to push and pop this large set of 790 state, much like pixel maps. Adding a new attribute bit would have 791 complicated logistics (would the bit be included in ALL_ATTRIB_BITS?). 792 Having program local parameters provides a method for making localized 793 changes to certain state simply by switching programs. 794 795 (39) How should this extension interact with color material? 796 797 RESOLVED: When color material is enabled, any bindings of material 798 colors that track the current color should be updated when the current 799 color is updated. In this specification, material properties can be 800 bound only as program parameters, and any changes to the material 801 properties inside a Begin/End leave the bindings undefined until the 802 next End command. Similarly, any indirect changes to the material 803 properties (through ColorMaterial) will have a similar effect. 804 805 Several other options were considered here. One option was to support 806 per-vertex material property bindings and have programs that reference 807 tracked material properties should get the current color. This could be 808 handled either by broadcasting the current color to multiple vertex 809 attributes, or recompiling the vertex program so that references to a 810 tracked material property are redirected to the vertex color. Both such 811 solutions are somewhat complex. A second option would be to ignore the 812 COLOR_MATERIAL enable and instead use an "old" material color. This 813 breaks the standard color material model. Implementations can and often 814 do defer such updates (making an "old" color available), some conditions 815 may cause an implementation to update of material state at odd times. 816 817 (41) What about when the execution environment involves support for other 818 extensions? In particular, the execution environment subsumes some 819 functionality from EXT/ARB_point_parameters, EXT_fog_coord, 820 EXT_secondary_color, and ARB_multitexture. 821 822 RESOLVED: This extension assumes support for functionality that 823 includes a fog coordinate, secondary color, per-vertex point sizes, and 824 multiple texture coordinates (at least to the extent that it exposes >1 825 texture coordinate). All of these extensions are supported fairly 826 widely. On some platforms, some of this functionality may require 827 software fallbacks. 828 829 (42) How does PointSize work with vertex programs? 830 831 RESOLVED: If VERTEX_PROGRAM_POINT_SIZE_ARB is disabled, the size of 832 points is determined by the PointSize state and is not attenuated, even 833 if EXT_point_parameters is supported. If enabled, the point size is the 834 point size result value, and is clamped to implementation-dependent 835 point size limits during point rasterization. 836 837 (43) What do we say about the alpha component of the secondary color? 838 839 RESOLVED: The alpha component of the secondary color has generally been 840 treated as zero. This extension specifies that only the R, G, and B 841 components are added in the color sum operation, making the alpha 842 component of the secondary color irrelevant. Other downstream 843 extensions may allow applications to make use of this component. 844 845 (44) How are edge flags handled? 846 847 RESOLVED: Edge flags are passed through without the ability to be 848 modified by a vertex program. Applications are free to send edge flags 849 when vertex program mode is enabled. 850 851 (45) Should programs be C-style null-terminated strings? 852 853 RESOLVED: No. Programs should be specified as an array of GLubyte with 854 an explicit length parameter. OpenGL has no precedent for passing 855 null-terminated strings into the API (though GetString returns 856 null-terminated strings). Null-terminated strings may be problematic 857 for some programming languages. 858 859 (46) Should all existing OpenGL transform functionality and extensions be 860 implementable as vertex programs? 861 862 RESOLVED: Yes. Vertex programs should be a complete superset of what 863 you can do with OpenGL 1.2 and existing vertex transform extensions. To 864 implement EXT_point_parameters, the VERTEX_PROGRAM_POINT_SIZE_ARB enable 865 is introduced. To implement two-sided lighting, the 866 VERTEX_PROGRAM_TWO_SIDE_ARB enable is introduced. To implement color 867 material, applications should refer to the per-vertex color attribute in 868 their vertex programs. 869 870 (47) Should there be a plural version of ProgramEnvParameter and 871 ProgramLocalParameter, which would set multiple parameters in a single 872 call? 873 874 RESOLVED: No; not necessary. 875 876 (48) Can the currently bound vertex program object be deleted or reloaded? 877 878 RESOLVED: Yes. When ProgramStringARB is called to reload a program 879 object, subsequent program executions will use the new program. When 880 DeleteProgramsARB deletes a currently bound program object, object zero 881 becomes the new current program object. 882 883 (49) What happens if you transform vertices in vertex program mode, but 884 the current program object does not contain a valid vertex program? 885 886 RESOLVED: Begin will fail with an INVALID_OPERATION error if the 887 currently bound vertex program object does not have a valid program. 888 The same applies to RasterPos and any command (Rect, DrawArrays, 889 DrawElements) that implies a Begin. 890 891 Because Vertex is ignored outside of a Begin/End pair (without 892 generating an error) it is impossible to provoke a vertex program if the 893 current vertex program object is nonexistent or invalid. Other 894 per-vertex parameters (for examples those set by Color, Normal, and 895 VertexAttrib*ARB when the attribute number is not zero) are allowed 896 since they are legal outside of a Begin/End. 897 898 (50) Discussing matrices is confusing because of row-major versus 899 column-major issues. Can you give an example of how a matrix is bound? 900 901 RESOLVED: Assume program matrix zero were loaded with the following 902 code: 903 904 // When loaded, the first row is "1, 2, 3, 4", because of column-major 905 // (OpenGL spec) vs. row-major (C) differences. 906 GLfloat matrix[16] = { 1, 5, 9, 13, 907 2, 6, 10, 14, 908 3, 7, 11, 15, 909 4, 8, 12, 16 }; 910 glMatrixMode(GL_MATRIX0_ARB); 911 glLoadMatrixf(matrix); 912 913 Then in the program 914 915 !!ARBvp1.0 916 PARAM mat1[4] = { state.matrix.program[0] }; 917 PARAM mat2[4] = { state.matrix.program[0].transpose }; 918 919 mat1[0] would have (1,2,3,4), mat1[3] would have (13,14,15,16), mat2[0] 920 would have (1,5,9,13), and mat2[3] would have (4,8,12,16). 921 922 (51) Should the new vertex program-related enables push/pop with 923 ENABLE_BIT? 924 925 RESOLVED: Yes. Pushing and popping enable bits is easy. 926 927 (52) Should all the vertex attribute state push/pop with CURRENT_BIT? 928 929 RESOLVED: Yes. 930 931 (53) Should all the vertex attrib vertex array state push/pop with 932 CLIENT_VERTEX_ARRAY_BIT? 933 934 RESOLVED: Yes. 935 936 (55) Should we generate an INVALID_VALUE operation if updating a vertex 937 attribute greater than MAX_VERTEX_ATTRIBS_ARB? 938 939 RESOLVED: Yes. The other option would be to leave the behavior 940 undefined, as with MultiTexCoord() functions. An implementation could 941 mask or modulo the vertex attribute index with MAX_VERTEX_ATTRIB_ARB if 942 it were a power of two. This error check will be a minor performance 943 issue with VertexAttrib*ARB() and VertexAttribArrayARB() calls. There 944 will be no per-vertex overhead when using vertex arrays or display 945 lists. 946 947 (56) Should writes to program environment or local parameters during a 948 vertex program be supported? 949 950 RESOLVED. No. Writes to program parameter registers from within a 951 vertex program would require the execution of vertex programs to be 952 serialized with respect to each other. This would create a severe 953 implementation penalty for pipelined or parallel vertex program 954 execution implementations. 955 956 (58) Should program objects be shared among rendering contexts in the same 957 manner as display lists and texture objects? 958 959 RESOLVED: Yes. 960 961 (60) Should there be a MatrixMode or ActiveTexture-style selector for 962 vertex attributes? 963 964 RESOLVED: No. While this would reduce the number of enumerants used by 965 this extensions, it would create programming a hassle in lots of cases. 966 Consider having to change the vertex attribute mode to enable a set of 967 vertex arrays. 968 969 (61) How should queries of vertex attribute arrays work? 970 971 RESOLVED: Add new get commands. Using the existing calls would require 972 adding 6 sets of 16+ enumerants for current state and vertex attribute 973 array state. That's too many new enumerants. Instead, add 974 GetVertexAttribARB and GetVertexAttribPointervARB. GetVertexAttribARB 975 will be used to query vertex attribute array state and the current 976 values of the generic vertex attributes. Get and GetPointerv will not 977 return vertex attribute array state and pointers. 978 979 (63) What should be said about rendering invariances? 980 981 RESOLVED: See the Appendix A additions below. 982 983 The justification for the two rules cited is to support multi-pass 984 rendering when using vertex programs. Different rendering passes will 985 likely use different programs so there must be some means of 986 guaranteeing that two different programs can generate particular 987 identical vertex results between different passes. 988 989 In practice, this does limit the type of vertex program implementations 990 that are possible. 991 992 For example, consider a limited hardware implementation of vertex 993 programs that uses a different floating-point implementation than the 994 CPU's floating-point implementation. If the limited hardware 995 implementation can only run small vertex programs (say the hardware 996 provides on 4 temporary registers instead of the required 12), the 997 implementation is incorrect and non-conformant if programs that only 998 require 4 temporary registers use the vertex program hardware, but 999 programs that require more than 4 temporary registers are implemented by 1000 the CPU. 1001 1002 This is a very important practical requirement. Consider a multi-pass 1003 rendering algorithm where one pass uses a vertex program that uses only 1004 4 temporary registers, but a different pass uses a vertex program that 1005 uses 5 temporary registers. If two programs have instruction sequences 1006 that given the same input state compute identical resulting vertex 1007 positions, the multi-pass algorithm should generate identically 1008 positioned primitives for each pass. But given the non-conformant 1009 vertex program implementation described above, this could not be 1010 guaranteed. 1011 1012 This does not mean that schemes for splitting vertex program 1013 implementations between dedicated hardware and CPUs are impossible. If 1014 the CPU and dedicated vertex program hardware used IDENTICAL 1015 floating-point implementations and therefore generated exactly identical 1016 results, the above described could work. 1017 1018 While these invariance rules are vital for vertex programs operating 1019 correctly for multi-pass algorithms, there is no requirement that 1020 conventional OpenGL vertex transform mode will be invariant with vertex 1021 program mode. A multi-pass algorithm should not assume that one pass 1022 using vertex program mode and another pass using conventional GL vertex 1023 transform mode will generate identically positioned primitives. 1024 1025 Consider that while the conventional OpenGL vertex program mode is 1026 repeatable with itself, the exact procedure used to transform vertices 1027 is not specified nor is the procedure's precision specified. The GL 1028 specification indicates that vertex coordinates are transformed by the 1029 modelview matrix and then transformed by the projection matrix. Some 1030 implementations may perform this sequence of transformations exactly, 1031 but other implementations may transform vertex coordinates by the 1032 composite of the modelview and projection matrices (one matrix transform 1033 instead of two matrix transforms in sequence). Given this 1034 implementation flexibility, there is no way for a vertex program author 1035 to exactly duplicate the precise computations used by the conventional 1036 OpenGL vertex transform mode. 1037 1038 The guidance to OpenGL application programs is clear. If you are going 1039 to implement multi-pass rendering algorithms that require certain 1040 invariances between the multiple passes, choose either vertex program 1041 mode or the conventional OpenGL vertex transform mode for your rendering 1042 passes, but do not mix the two modes. 1043 1044 (64) Should there be a way to guarantee position invariance with respect 1045 to conventional vertex transformation? 1046 1047 RESOLVED: Yes. The "OPTION ARB_position_invariant" program option 1048 addresses this issue. This program option will be available on all 1049 implementations of this extension. 1050 1051 John Carmack advocated the need for this. 1052 1053 (65) Why must RCP of 1.0 always be 1.0? 1054 1055 RESOLVED: This is important for 3D graphics so that non-projective 1056 textures and orthogonal projections work as expected. Basically when q 1057 or w is 1.0, things should work as expected. Stronger requirements such 1058 as "RCP of -1.0 must always be -1.0" are encouraged, but there is no 1059 compelling reason to state such requirements explicitly as is the case 1060 for "RCP of 1.0 must always be 1.0". 1061 1062 (66) What happens when the source scalar value for the ARL instruction is 1063 an extremely large positive or negative floating-point value? Is there a 1064 problem mapping the value to a constrained integer range? 1065 1066 RESOLVED: In this extension, address registers are only useful for 1067 relative addressing. The range of offsets that can be added to an 1068 address register is limited (-64 to +63) and the set of valid array 1069 indices is also limited to MAX_PROGRAM_PARAMETERS_ARB. So, the set of 1070 floating-point values that needs to be handled properly is 1071 well-constrained. 1072 1073 (67) How do you perform a 3-component normalize in three instructions? 1074 1075 RESOLVED: As follows. 1076 1077 DP3 result.w, vector, vector; # result.w = nx^2+ny^2+nz^2 1078 RSQ result.w, result.w; # result.w = 1/sqrt(nx^2+ny^2+nz^2) 1079 MUL result.xyz, result.w, vector; 1080 1081 (69) How do you compute the determinant of a 3x3 matrix in three 1082 instructions? 1083 1084 RESOLVED: As follows. 1085 1086 # 1087 # Determinant of | vec0.x vec0.y vec0.z | into result. 1088 # | vec1.x vec1.y vec1.z | 1089 # | vec2.x vec2.y vec2.z | 1090 # 1091 MUL result, vec1.zxyw, vec2.yzxw; 1092 MAD result, vec1.yzxw, vec2.zxyw, -result; 1093 DP3 result, vec0, result; 1094 1095 (70) How do you transform a vertex position by a 4x4 matrix and then 1096 perform a homogeneous divide? 1097 1098 RESOLVED: As follows. 1099 1100 ATTRIB pos = vertex.position; 1101 TEMP result, temp; 1102 PARAM mat[4] = { state.matrix.modelview }; 1103 1104 DP4 result.w, pos, mat[3]; 1105 DP4 result.x, pos, mat[0]; 1106 DP4 result.y, pos, mat[1]; 1107 DP4 result.z, pos, mat[2]; 1108 RCP temp.w, result.w; 1109 MUL result, result, temp.w; 1110 1111 (71) How do you perform a vector weighting of two vectors using a single 1112 weight? 1113 1114 RESOLVED: As follows. 1115 1116 # result = a * vec0 + (1-a) * vec1 1117 # = vec1 + a * (vec0 - vec1) 1118 SUB result, vec0, vec1; 1119 MAD result, a, result, vec1; 1120 1121 (72) How do you reduce a value to some fundamental period such as 2*PI? 1122 1123 RESOLVED: As follows. 1124 1125 # result = 2*PI * fraction(in/(2*PI)) 1126 # piVec = (1/(2*PI), 2*PI, 0, 0) 1127 PARAM piVec = { 0.159154943, 6.283185307, 0, 0 }; 1128 1129 MUL result, in, piVec.x; 1130 EXP result, result.x; 1131 MUL result, result.y, piVec.y; 1132 1133 (73) How do you implement a simple ambient, specular, and diffuse infinite 1134 lighting computation with a single light and an eye-space normal? 1135 1136 RESOLVED: As follows. 1137 1138 !!ARBvp1.0 1139 ATTRIB iPos = vertex.position; 1140 ATTRIB iNormal = vertex.normal; 1141 PARAM mvinv[4] = { state.matrix.modelview.invtrans }; 1142 PARAM mvp[4] = { state.matrix.mvp }; 1143 PARAM lightDir = state.light[0].position; 1144 PARAM halfDir = state.light[0].half; 1145 PARAM specExp = state.material.shininess; 1146 PARAM ambientCol = state.lightprod[0].ambient; 1147 PARAM diffuseCol = state.lightprod[0].diffuse; 1148 PARAM specularCol = state.lightprod[0].specular; 1149 TEMP xfNormal, temp, dots; 1150 OUTPUT oPos = result.position; 1151 OUTPUT oColor = result.color; 1152 1153 # Transform the vertex to clip coordinates. 1154 DP4 oPos.x, mvp[0], iPos; 1155 DP4 oPos.y, mvp[1], iPos; 1156 DP4 oPos.z, mvp[2], iPos; 1157 DP4 oPos.w, mvp[3], iPos; 1158 1159 # Transform the normal to eye coordinates. 1160 DP3 xfNormal.x, mvinv[0], iNormal; 1161 DP3 xfNormal.y, mvinv[1], iNormal; 1162 DP3 xfNormal.z, mvinv[2], iNormal; 1163 1164 # Compute diffuse and specular dot products and use LIT to compute 1165 # lighting coefficients. 1166 DP3 dots.x, xfNormal, lightDir; 1167 DP3 dots.y, xfNormal, halfDir; 1168 MOV dots.w, specExp.x; 1169 LIT dots, dots; 1170 1171 # Accumulate color contributions. 1172 MAD temp, dots.y, diffuseCol, ambientCol; 1173 MAD oColor.xyz, dots.z, specularCol, temp; 1174 MOV oColor.w, diffuseCol.w; 1175 END 1176 1177 (75) Can you perturb transformed vertex positions with a vertex program? 1178 1179 RESOLVED: Yes. Here is an example that performs an object-space 1180 diffuse lighting computations and perturbs the vertex position based on 1181 this lighting result. Do not take this example too seriously. 1182 1183 !!ARBvp1.0 1184 # 1185 # Program environment parameters: 1186 # c[0].xyz = normalized light direction in object-space 1187 # 1188 # outputs diffuse illumination for color and perturbed position 1189 # 1190 ATTRIB iPos = vertex.position; 1191 ATTRIB iNormal = vertex.normal; 1192 PARAM mvp[4] = { state.matrix.mvp }; 1193 PARAM lightDir = program.env[0]; 1194 PARAM diffuseCol = { 1, 1, 0, 1 }; 1195 TEMP temp; 1196 OUTPUT oPos = result.position; 1197 OUTPUT oColor = result.color; 1198 1199 DP3 temp, lightDir, iNormal; 1200 MUL oColor.xyz, temp, diffuseCol; 1201 MAX temp, temp, 0; # clamp dot product to zero 1202 MUL temp, temp, iNormal; # align in direction of normal 1203 MUL temp, temp, 0.125; # scale displacement by 1/8 1204 SUB temp, temp, iPos; # perturb 1205 DP4 oPos.x, mvp[0], temp; # xform using perturbed position 1206 DP4 oPos.y, mvp[1], temp; 1207 DP4 oPos.z, mvp[2], temp; 1208 DP4 oPos.w, mvp[3], temp; 1209 END 1210 1211 (76) Should this extension provide any method for updating program 1212 parameters in a program itself? 1213 1214 RESOLVED: No. NV_vertex_program provided a special mechanism to do 1215 this using a "vertex state program" manually executed by calling 1216 ExecuteProgramNV. This capability has not proven itself particularly 1217 useful to date. 1218 1219 (78) Should there be a different ProgramStringARB call for every distinct 1220 program target? Arguably, 1D, 2D, and 3D textures each have their own 1221 TexImage command for specifying their image data. 1222 1223 RESOLVED: No. All program objects can/should be loaded with 1224 ProgramStringARB. We expect the string to be a sufficient to express 1225 any kind of programmability. 1226 1227 Moreover, the 1D, 2D, and 3D TexImage commands describe the image being 1228 specified as opposed to the texture target being updated. With cube map 1229 textures, there are six face texture targets that use the TexImage2D 1230 command but not with the TEXTURE_2D target. 1231 1232 (79) This extension introduces a collection of new matrices for use by 1233 vertex programs (and possibly other programs as well). What should these 1234 matrices be called? 1235 1236 RESOLVED: Program matrices. These matrices are referred to as 1237 "tracking matrices" in NV_vertex_program, but the functionality is 1238 equivalent. 1239 1240 (80) With ARB_vertex_blend and EXT_vertex_weighting, there are multiple 1241 modelview matrices. This extension provides a single "MVP" matrix, 1242 defined to be the product of modelview matrix 0 and the projection 1243 matrices. Should this extension instead provide one MVP matrix per 1244 modelview matrix? 1245 1246 RESOLVED: No. Providing multiple MVP matrices allows applications to 1247 do N transformations into clip space and then one weighting operation, 1248 instead of N transformations into eye space, a weighting operation, and 1249 then a single transformation into clip space. This would potentially 1250 save instructions, but this optimization would be of no value if the 1251 program did any other operations that required eye coordinates. 1252 1253 Note also that the MVP transformations are likely general 4x4 matrix 1254 multiplies (4 DP4 instructions per transform). On the other hand, 1255 object and eye coordinates are often 3D coordinates with a constant W of 1256 1.0. So each transformation to eye coordinates may require only 3 DP4 1257 instructions, in which case the comparison may be 4N instructions (clip 1258 weighting) vs. 3N+4 (eye weighting). 1259 1260 (81) Should variable declarations be allowed to be anywhere within the 1261 program body, or should they instead be required to be done at the 1262 beginning of the program? Should the possibility of branching in a future 1263 standard affect this resolution? 1264 1265 RESOLVED: Declarations will be allowed anywhere in the program text; 1266 the only ordering requirement is that the declaration of a variable must 1267 precede its use in the program text. Requiring up-front variable 1268 declarations may require multiple passes for applications that build 1269 programs on the fly. 1270 1271 While declarations can appear anywhere in the program body, they are not 1272 executable statements. Any corresponding bindings (including constant 1273 initializations) are resolved before the program executes. The bindings 1274 will be resolved even if a program were to "branch around" a 1275 declaration. 1276 1277 (82) Should address register variables be treated as vectors? If so, 1278 should a variable number of components (up to four) be supported by this 1279 extension? 1280 1281 RESOLVED: In the future, four-component address vectors may be 1282 supported, and vector notation is used for forward compatibility. Using 1283 this notation makes address registers consistent with all the other 1284 vector data types in this extension. However, support for more than one 1285 usable component will be left for future extensions, but could be added 1286 via a program option or in a new language revision (e.g., !!ARBvp2.0). 1287 1288 (83) Should program local parameters be logically connected to the program 1289 string or the program object? 1290 1291 RESOLVED: Program local parameters are properties of a program object. 1292 Their values persist even after a new program is loaded into the object. 1293 This model does allow applications to recompile the program in a given 1294 object based on certain rendering settings without having to 1295 re-initialize any state stored in the object. 1296 1297 (84) Should this extension provide a method to specify "anonymous" program 1298 local parameters and query an index into the program parameter array. 1299 1300 RESOLVED: No. It would be nice to declare a variable in a program such 1301 as 1302 1303 PARAM foo = program.local; # note no index in the array 1304 1305 after which an application could query the location of "foo" in the 1306 program local parameter array. However, given that local parameters 1307 persist even across program loads, it would be difficult to specify what 1308 program local parameter "foo" would be assigned to. 1309 1310 (85) EXT_vertex_weighting provides a single vertex blend weight. 1311 ARB_vertex_blend generalizes this concept to a weight vector. Both pieces 1312 of state are specified separately, and could be thought of as distinct. 1313 Should distinct bindings be provided in this extension? 1314 1315 RESOLVED: No. No current implementation supports both extensions, but 1316 the vendors involved in this standardization process agree that the 1317 state should not be considered distinct. If an implementation supported 1318 both extensions, the APIs would modify the same state. 1319 1320 (86) Should this extension provide functionality for variable aliasing? 1321 If so, how should it be specified and what types of variables can be 1322 aliasesed? 1323 1324 RESOLVED: Yes, for all variable types. The syntax is a simple text 1325 replacement: 1326 1327 ALIAS a = b; 1328 1329 This functionality allows applications to "share" variables, and thereby 1330 exceed implementation-dependent limits on the number of variable 1331 declarations. This may be particularly significant for temporaries, 1332 where the limit on the number of variables may be fairly low. 1333 1334 (87) How do you determine whether a given program option is supported by 1335 the GL implementation? 1336 1337 RESOLVED: Program options may be introduced in OpenGL extensions and 1338 may be added to future OpenGL specifications. An option will be 1339 supported if and only if (1) the corresponding OpenGL extension appears 1340 in the implementation-dependent EXTENSIONS string or (2) the option is 1341 documented in the OpenGL specification version corresponding to the 1342 implementation's VERSION string. 1343 1344 The ARB_position_invariant option is provided by this extension, and 1345 will always be available (provided this extension is supported). 1346 1347 (88) What's the deal with binding the alpha component of light colors, fog 1348 colors, and material colors (other than diffuse)? They don't do anything, 1349 right? 1350 1351 RESOLVED: The GL state for these different colors includes alpha 1352 components, which will be returned by queries. However, in the 1353 conventional OpenGL pipeline, most of these alpha components are 1354 effectively ignored. However, since they are present in the GL state, 1355 they will be exposed in bindings. What is done with these alpha values 1356 in program mode is completely up to the vertex program. 1357 1358 Vertex programs need to be careful to ensure that the alpha component is 1359 computed correctly when evaluating lighting equations. When 1360 accumulating light contributions, it may be necessary to use write masks 1361 to disable writes to the alpha component. 1362 1363 (89) The LOG instruction takes the logarithm of the absolute value of its 1364 operand while the LG2 instruction takes the logarithm of the operand 1365 itself. In LG2, the logarithm of negative numbers is undefined. 1366 1367 RESOLVED: The LOG instruction is present for (1) compatibility with 1368 NV_vertex_program and DirectX 8 languages and (2) because it may 1369 outperform LG2 on some platforms. For compatibility, it is defined to 1370 behave identically to existing languages. 1371 1372 (90) With vertex programs, fog coordinates and point sizes can be computed 1373 on a per-vertex basis. How are the fog coordinates and point sizes 1374 associated with vertices introduced by clipping computed? 1375 1376 RESOLVED: Fog coordinates and point sizes for clipped vertices are 1377 computed by interpolating the computed values at the original vertices 1378 in exactly the same manner as colors and texture coordinates are 1379 interpolated in section 2.13.8 of the OpenGL 1.3 specification. 1380 1381 (91) Vertex programs support only RGBA colors, but do not support color 1382 index inputs or results. What happens if an application uses vertex 1383 programs in color index mode. 1384 1385 RESOLVED: The results of vertex program execution are undefined if the 1386 GL is in color index mode. 1387 1388 (92) Should automatic normalization of evaluated normals (AUTO_NORMAL) be 1389 supported when the GL is in vertex program mode? 1390 1391 RESOLVED: Automatic normalization of normals will be disabled in vertex 1392 program mode. The current vertex program can easily normalize the 1393 normal if required. This can lead to greater efficiency if the vertex 1394 program transforms the normal to another coordinate system such as 1395 eye-space with a transform that preserves vector length. Then a single 1396 normalize after transform is more efficient than normalizing after 1397 evaluation and normalizing again after transform. Conceptually, the 1398 normalize mandated for AUTO_NORMAL in section 5.1 is just one of the 1399 many transformation operations subsumed by vertex programs. 1400 1401 (93) This extension allows applications to name their own variables. What 1402 keywords should be reserved? 1403 1404 RESOLVED: Instruction names and declaration keywords (e.g., PARAM) will 1405 be reserved. Additionally, since attribute, parameter, and result 1406 bindings are allowed in the program text, the binding prefix keywords 1407 "vertex", "state", "program", and "result" are reserved to simplify 1408 parsing. This prevents the need to distinguish between 1409 "vertex.position" ("vertex" as a binding) and "vertex.xyzw" ("vertex" as 1410 a variable). 1411 1412 (94) When counting the number of program parameter bindings, multiple 1413 constant vectors with the same components are counted only once. How is 1414 this determined? 1415 1416 RESOLVED: The implementation does a numerical comparison after the 1417 specified constants are converted to an internal floating-point 1418 representation. Due to floating-point representation limits, such 1419 conversions are not always precise. Constants specified with different 1420 text that are "equivalent" (e.g., "12" and "1.2E+01") are not guaranteed 1421 to resolve to the same value. Additionally, constants that are not 1422 "equivalent" but have only small relative differences (e.g., "200000000" 1423 and "200000001") may end up resolving to the same value. Constants 1424 specified with the same text should always be identical. 1425 1426 (95) What characters are allowed in identifier names? 1427 1428 RESOLVED: Letters ("A"-"Z", "a"-"z"), numbers ("0"-"9"), underscores 1429 ("_"), and dollar signs ("$"). 1430 1431 (96) How should future programmability extensions interact with this one? 1432 1433 RESOLVED: Future programmability extensions are expected to fall in one 1434 of two classes: (1) extensions that bring programmability to new 1435 sections and (2) extensions the extend existing programmability models. 1436 The former class should introduce a new program target; the latter class 1437 would extend the functionality of an existing target. 1438 1439 Recommendations for extensions introducing new program targets include: 1440 1441 * Re-use and reference the functionality specified in this extension 1442 (or in a future OpenGL specification incorporating this extension) 1443 as much as possible, to maintain a consistent model. 1444 1445 * Provide a program header allowing for easy identification and 1446 versioning of programs for the new target. 1447 1448 Recommendations for extensions modifying existing program targets 1449 include: 1450 1451 * The option mechanism (section 2.14.4.5) should be used to provide 1452 minor modifications to the program language. 1453 1454 * The program header/version string (section 2.14.2) should be used to 1455 provide major modifications to the language, or potentially to 1456 provide a commonly used collection of options. Program header 1457 string changes should be multi-vendor extensions as much as 1458 possible. 1459 1460 * For portability, programs should not be allowed to use extended 1461 language features without specifying the corresponding program 1462 options or program header. 1463 1464 1465New Procedures and Functions 1466 1467 void VertexAttrib1sARB(uint index, short x); 1468 void VertexAttrib1fARB(uint index, float x); 1469 void VertexAttrib1dARB(uint index, double x); 1470 void VertexAttrib2sARB(uint index, short x, short y); 1471 void VertexAttrib2fARB(uint index, float x, float y); 1472 void VertexAttrib2dARB(uint index, double x, double y); 1473 void VertexAttrib3sARB(uint index, short x, short y, short z); 1474 void VertexAttrib3fARB(uint index, float x, float y, float z); 1475 void VertexAttrib3dARB(uint index, double x, double y, double z); 1476 void VertexAttrib4sARB(uint index, short x, short y, short z, short w); 1477 void VertexAttrib4fARB(uint index, float x, float y, float z, float w); 1478 void VertexAttrib4dARB(uint index, double x, double y, double z, double w); 1479 void VertexAttrib4NubARB(uint index, ubyte x, ubyte y, ubyte z, ubyte w); 1480 1481 void VertexAttrib1svARB(uint index, const short *v); 1482 void VertexAttrib1fvARB(uint index, const float *v); 1483 void VertexAttrib1dvARB(uint index, const double *v); 1484 void VertexAttrib2svARB(uint index, const short *v); 1485 void VertexAttrib2fvARB(uint index, const float *v); 1486 void VertexAttrib2dvARB(uint index, const double *v); 1487 void VertexAttrib3svARB(uint index, const short *v); 1488 void VertexAttrib3fvARB(uint index, const float *v); 1489 void VertexAttrib3dvARB(uint index, const double *v); 1490 void VertexAttrib4bvARB(uint index, const byte *v); 1491 void VertexAttrib4svARB(uint index, const short *v); 1492 void VertexAttrib4ivARB(uint index, const int *v); 1493 void VertexAttrib4ubvARB(uint index, const ubyte *v); 1494 void VertexAttrib4usvARB(uint index, const ushort *v); 1495 void VertexAttrib4uivARB(uint index, const uint *v); 1496 void VertexAttrib4fvARB(uint index, const float *v); 1497 void VertexAttrib4dvARB(uint index, const double *v); 1498 void VertexAttrib4NbvARB(uint index, const byte *v); 1499 void VertexAttrib4NsvARB(uint index, const short *v); 1500 void VertexAttrib4NivARB(uint index, const int *v); 1501 void VertexAttrib4NubvARB(uint index, const ubyte *v); 1502 void VertexAttrib4NusvARB(uint index, const ushort *v); 1503 void VertexAttrib4NuivARB(uint index, const uint *v); 1504 1505 void VertexAttribPointerARB(uint index, int size, enum type, 1506 boolean normalized, sizei stride, 1507 const void *pointer); 1508 1509 void EnableVertexAttribArrayARB(uint index); 1510 void DisableVertexAttribArrayARB(uint index); 1511 1512 void ProgramStringARB(enum target, enum format, sizei len, 1513 const void *string); 1514 1515 void BindProgramARB(enum target, uint program); 1516 1517 void DeleteProgramsARB(sizei n, const uint *programs); 1518 1519 void GenProgramsARB(sizei n, uint *programs); 1520 1521 void ProgramEnvParameter4dARB(enum target, uint index, 1522 double x, double y, double z, double w); 1523 void ProgramEnvParameter4dvARB(enum target, uint index, 1524 const double *params); 1525 void ProgramEnvParameter4fARB(enum target, uint index, 1526 float x, float y, float z, float w); 1527 void ProgramEnvParameter4fvARB(enum target, uint index, 1528 const float *params); 1529 1530 void ProgramLocalParameter4dARB(enum target, uint index, 1531 double x, double y, double z, double w); 1532 void ProgramLocalParameter4dvARB(enum target, uint index, 1533 const double *params); 1534 void ProgramLocalParameter4fARB(enum target, uint index, 1535 float x, float y, float z, float w); 1536 void ProgramLocalParameter4fvARB(enum target, uint index, 1537 const float *params); 1538 1539 void GetProgramEnvParameterdvARB(enum target, uint index, 1540 double *params); 1541 void GetProgramEnvParameterfvARB(enum target, uint index, 1542 float *params); 1543 1544 void GetProgramLocalParameterdvARB(enum target, uint index, 1545 double *params); 1546 void GetProgramLocalParameterfvARB(enum target, uint index, 1547 float *params); 1548 1549 void GetProgramivARB(enum target, enum pname, int *params); 1550 1551 void GetProgramStringARB(enum target, enum pname, void *string); 1552 1553 void GetVertexAttribdvARB(uint index, enum pname, double *params); 1554 void GetVertexAttribfvARB(uint index, enum pname, float *params); 1555 void GetVertexAttribivARB(uint index, enum pname, int *params); 1556 1557 void GetVertexAttribPointervARB(uint index, enum pname, void **pointer); 1558 1559 boolean IsProgramARB(uint program); 1560 1561 1562New Tokens 1563 1564 Accepted by the <cap> parameter of Disable, Enable, and IsEnabled, by the 1565 <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev, 1566 and by the <target> parameter of ProgramStringARB, BindProgramARB, 1567 ProgramEnvParameter4[df][v]ARB, ProgramLocalParameter4[df][v]ARB, 1568 GetProgramEnvParameter[df]vARB, GetProgramLocalParameter[df]vARB, 1569 GetProgramivARB, and GetProgramStringARB. 1570 1571 VERTEX_PROGRAM_ARB 0x8620 1572 1573 Accepted by the <cap> parameter of Disable, Enable, and IsEnabled, and by 1574 the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and 1575 GetDoublev: 1576 1577 VERTEX_PROGRAM_POINT_SIZE_ARB 0x8642 1578 VERTEX_PROGRAM_TWO_SIDE_ARB 0x8643 1579 COLOR_SUM_ARB 0x8458 1580 1581 Accepted by the <format> parameter of ProgramStringARB: 1582 1583 PROGRAM_FORMAT_ASCII_ARB 0x8875 1584 1585 Accepted by the <pname> parameter of GetVertexAttrib[dfi]vARB: 1586 1587 VERTEX_ATTRIB_ARRAY_ENABLED_ARB 0x8622 1588 VERTEX_ATTRIB_ARRAY_SIZE_ARB 0x8623 1589 VERTEX_ATTRIB_ARRAY_STRIDE_ARB 0x8624 1590 VERTEX_ATTRIB_ARRAY_TYPE_ARB 0x8625 1591 VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB 0x886A 1592 CURRENT_VERTEX_ATTRIB_ARB 0x8626 1593 1594 Accepted by the <pname> parameter of GetVertexAttribPointervARB: 1595 1596 VERTEX_ATTRIB_ARRAY_POINTER_ARB 0x8645 1597 1598 Accepted by the <pname> parameter of GetProgramivARB: 1599 1600 PROGRAM_LENGTH_ARB 0x8627 1601 PROGRAM_FORMAT_ARB 0x8876 1602 PROGRAM_BINDING_ARB 0x8677 1603 PROGRAM_INSTRUCTIONS_ARB 0x88A0 1604 MAX_PROGRAM_INSTRUCTIONS_ARB 0x88A1 1605 PROGRAM_NATIVE_INSTRUCTIONS_ARB 0x88A2 1606 MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB 0x88A3 1607 PROGRAM_TEMPORARIES_ARB 0x88A4 1608 MAX_PROGRAM_TEMPORARIES_ARB 0x88A5 1609 PROGRAM_NATIVE_TEMPORARIES_ARB 0x88A6 1610 MAX_PROGRAM_NATIVE_TEMPORARIES_ARB 0x88A7 1611 PROGRAM_PARAMETERS_ARB 0x88A8 1612 MAX_PROGRAM_PARAMETERS_ARB 0x88A9 1613 PROGRAM_NATIVE_PARAMETERS_ARB 0x88AA 1614 MAX_PROGRAM_NATIVE_PARAMETERS_ARB 0x88AB 1615 PROGRAM_ATTRIBS_ARB 0x88AC 1616 MAX_PROGRAM_ATTRIBS_ARB 0x88AD 1617 PROGRAM_NATIVE_ATTRIBS_ARB 0x88AE 1618 MAX_PROGRAM_NATIVE_ATTRIBS_ARB 0x88AF 1619 PROGRAM_ADDRESS_REGISTERS_ARB 0x88B0 1620 MAX_PROGRAM_ADDRESS_REGISTERS_ARB 0x88B1 1621 PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 0x88B2 1622 MAX_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 0x88B3 1623 MAX_PROGRAM_LOCAL_PARAMETERS_ARB 0x88B4 1624 MAX_PROGRAM_ENV_PARAMETERS_ARB 0x88B5 1625 PROGRAM_UNDER_NATIVE_LIMITS_ARB 0x88B6 1626 1627 Accepted by the <pname> parameter of GetProgramStringARB: 1628 1629 PROGRAM_STRING_ARB 0x8628 1630 1631 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 1632 GetFloatv, and GetDoublev: 1633 1634 PROGRAM_ERROR_POSITION_ARB 0x864B 1635 CURRENT_MATRIX_ARB 0x8641 1636 TRANSPOSE_CURRENT_MATRIX_ARB 0x88B7 1637 CURRENT_MATRIX_STACK_DEPTH_ARB 0x8640 1638 MAX_VERTEX_ATTRIBS_ARB 0x8869 1639 MAX_PROGRAM_MATRICES_ARB 0x862F 1640 MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB 0x862E 1641 1642 Accepted by the <name> parameter of GetString: 1643 1644 PROGRAM_ERROR_STRING_ARB 0x8874 1645 1646 Accepted by the <mode> parameter of MatrixMode: 1647 1648 MATRIX0_ARB 0x88C0 1649 MATRIX1_ARB 0x88C1 1650 MATRIX2_ARB 0x88C2 1651 MATRIX3_ARB 0x88C3 1652 MATRIX4_ARB 0x88C4 1653 MATRIX5_ARB 0x88C5 1654 MATRIX6_ARB 0x88C6 1655 MATRIX7_ARB 0x88C7 1656 MATRIX8_ARB 0x88C8 1657 MATRIX9_ARB 0x88C9 1658 MATRIX10_ARB 0x88CA 1659 MATRIX11_ARB 0x88CB 1660 MATRIX12_ARB 0x88CC 1661 MATRIX13_ARB 0x88CD 1662 MATRIX14_ARB 0x88CE 1663 MATRIX15_ARB 0x88CF 1664 MATRIX16_ARB 0x88D0 1665 MATRIX17_ARB 0x88D1 1666 MATRIX18_ARB 0x88D2 1667 MATRIX19_ARB 0x88D3 1668 MATRIX20_ARB 0x88D4 1669 MATRIX21_ARB 0x88D5 1670 MATRIX22_ARB 0x88D6 1671 MATRIX23_ARB 0x88D7 1672 MATRIX24_ARB 0x88D8 1673 MATRIX25_ARB 0x88D9 1674 MATRIX26_ARB 0x88DA 1675 MATRIX27_ARB 0x88DB 1676 MATRIX28_ARB 0x88DC 1677 MATRIX29_ARB 0x88DD 1678 MATRIX30_ARB 0x88DE 1679 MATRIX31_ARB 0x88DF 1680 1681Additions to Chapter 2 of the OpenGL 1.3 Specification (OpenGL Operation) 1682 1683 Modify Section 2.6, Begin/End Paradigm (p. 12) 1684 1685 (modify last paragraph, p. 12) ... In addition, a current normal, a 1686 current color, multiple current texture coordinate sets, and multiple 1687 generic vertex attributes may be used in processing each vertex. Normals 1688 are used by the GL in lighting calculations; the current normal is a 1689 three-dimensional vector that may be set by sending three coordinates that 1690 specify it. Texture coordinates determine how a texture image is mapped 1691 onto a primitive. Multiple sets of texture coordinates may be used to 1692 specify how multiple texture images are mapped onto a primitive. Generic 1693 vertex attributes do not have any specific function but can be used in 1694 vertex program mode (section 2.14) to compute final values for any data 1695 associated with a vertex. 1696 1697 1698 Modify Section 2.6.3, GL Commands within Begin/End (p. 19) 1699 1700 (modify first paragraph of section, p. 19) The only GL commands that are 1701 allowed within any Begin/End pairs are the commands for specifying vertex 1702 coordinates, vertex color, normal coordinates, texture coordinates, and 1703 generic vertex attributes (Vertex, Color, Index, Normal, TexCoord, 1704 VertexAttrib*ARB), ... 1705 1706 1707 Modify Section 2.7, Vertex Specification (p. 19) 1708 1709 (remove the "Finally" from the next-to-last paragraph, p. 20) There are 1710 several ways to set the current color. The GL stores both a current 1711 single-valued color index, and a current four-valued RGBA color. One 1712 1713 (add new paragraph before last paragraph of section, p. 21) Vertex 1714 programs (section 2.14) can access an array of four-component generic 1715 current vertex attributes. The first entry of this array is numbered 1716 zero, and the number of entries in the array is given by the 1717 implementation-dependent constant MAX_VERTEX_ATTRIBS_ARB. The commands 1718 1719 void VertexAttrib{1234}{sfd}ARB(uint index, T coords); 1720 void VertexAttrib{123}{sfd}vARB(uint index, T coords); 1721 void VertexAttrib4{bsifd ubusui}vARB(uint index, T coords); 1722 1723 specify the current vertex attribute numbered <index>, whose components 1724 are named <x>, <y>, <z>, and <w>. The VertexAttrib1ARB family of commands 1725 sets the <x> coordinate to the provided single argument while setting <y> 1726 and <z> to 0 and <w> to 1. Similarly, VertexAttrib2ARB commands set <x> 1727 and <y> to the specified values, <z> to 0 and <w> to 1; VertexAttrib3ARB 1728 commands set <x>, <y>, and <z>, with <w> set to 1, and VertexAttrib4ARB 1729 commands set all four coordinates. The error INVALID_VALUE is generated 1730 if <index> is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. 1731 1732 The commands 1733 1734 void VertexAttrib4NubARB(uint index, T coords); 1735 void VertexAttrib4N{bsi ubusui}vARB(uint index, T coords); 1736 1737 also specify vertex attributes with fixed-point coordinates that are 1738 scaled to the range [0,1] or [-1,1], according to Table 2.6. 1739 1740 Setting generic vertex attribute zero specifies a vertex; the four vertex 1741 coordinates are taken from the values of attribute zero. A Vertex2, 1742 Vertex3, or Vertex4 command is completely equivalent to the corresponding 1743 VertexAttrib command with an index of zero. Setting any other generic 1744 vertex attribute updates the current values of the attribute. There are 1745 no current values for vertex attribute zero. 1746 1747 Implementations may, but do not necessarily, use the same storage for the 1748 current values of generic and certain conventional vertex attributes. 1749 When any generic vertex attribute other than zero is specified, the 1750 current values for the corresponding conventional attribute in Table X.1 1751 become undefined. Additionally, when a conventional vertex attribute is 1752 specified, the current values for the corresponding generic vertex 1753 attribute in Table X.1 become undefined. For example, setting the current 1754 normal will leave generic vertex attribute 2 undefined, and vice versa. 1755 1756 Generic 1757 Attribute Conventional Attribute Conventional Attribute Command 1758 --------- ------------------------ ------------------------------ 1759 0 vertex position Vertex 1760 1 vertex weights 0-3 WeightARB, VertexWeightEXT 1761 2 normal Normal 1762 3 primary color Color 1763 4 secondary color SecondaryColorEXT 1764 5 fog coordinate FogCoordEXT 1765 6 - - 1766 7 - - 1767 8 texture coordinate set 0 MultiTexCoord(TEXTURE0, ...) 1768 9 texture coordinate set 1 MultiTexCoord(TEXTURE1, ...) 1769 10 texture coordinate set 2 MultiTexCoord(TEXTURE2, ...) 1770 11 texture coordinate set 3 MultiTexCoord(TEXTURE3, ...) 1771 12 texture coordinate set 4 MultiTexCoord(TEXTURE4, ...) 1772 13 texture coordinate set 5 MultiTexCoord(TEXTURE5, ...) 1773 14 texture coordinate set 6 MultiTexCoord(TEXTURE6, ...) 1774 15 texture coordinate set 7 MultiTexCoord(TEXTURE7, ...) 1775 8+n texture coordinate set n MultiTexCoord(TEXTURE0+n, ...) 1776 1777 Table X.1, Generic and Conventional Vertex Attribute Mappings. For each 1778 row, the current value of the conventional attribute becomes undefined 1779 when the corresponding generic attribute is set, and vice versa. 1780 Attribute zero corresponds to the vertex position and has no current 1781 state. 1782 1783 Setting any conventional vertex attribute not listed in Table X.1 1784 (including vertex weights 4 and above, if supported) will not cause any 1785 generic vertex attribute to become undefined, and such attributes will not 1786 become undefined when any generic vertex attribute is set. 1787 1788 1789 1790 (modify the last paragraph in the section, p.21) The state required to 1791 support vertex specification consists of four floating-point numbers per 1792 texture unit to store the current texture coordinates s, t, r, and q, 1793 three floating-point numbers to store the three coordinates of the current 1794 normal, four floating-point values to store the current RGBA color, one 1795 floating-point value to store the current color index, and 1796 MAX_VERTEX_ATTRIBS_ARB-1 four-component floating-point vectors for generic 1797 vertex attributes. There is no notion of a current vertex, so no state is 1798 devoted to vertex coordinates or vertex attribute zero. The initial 1799 texture coordinates are (S,T,R,Q) = (0,0,0,1) for each texture unit. The 1800 initial current normal has coordinates (0,0,1). The initial RGBA color is 1801 (R,G,B,A) = (1,1,1,1). The initial color index is 1. The initial values 1802 for all generic vertex attributes are undefined. 1803 1804 1805 Modify Section 2.8, Vertex Arrays (p. 21) 1806 1807 (modify first paragraph of section, p.21) The vertex specification 1808 commands described in section 2.7 accept data in almost any format, but 1809 their use requires many command executions to specify even simple 1810 geometry. Vertex data may also be placed into arrays that are stored in 1811 the client's address space. Blocks of data in these arrays may then be 1812 used to specify multiple geometric primitives through the execution of a 1813 single GL command. The client may specify up to 5 plus the values of 1814 MAX_TEXTURE_UNITS and MAX_VERTEX_ATTRIBS_ARB arrays: one each to store 1815 vertex coordinates, edge flags, colors, color indices, normals, one or 1816 more texture coordinate sets, and one or more generic vertex attributes. 1817 The commands 1818 1819 ... 1820 1821 void VertexAttribPointerARB(uint index, int size, enum type, 1822 boolean normalized, sizei stride, 1823 const void *pointer); 1824 1825 describe the locations and organizations... 1826 1827 (add after the first paragraph, p.22) The <index> parameter in the 1828 VertexAttribPointer command identifies the generic vertex attribute array 1829 being described. The error INVALID_VALUE is generated if <index> is 1830 greater than or equal to MAX_VERTEX_ATTRIBS_ARB. The <normalized> 1831 parameter in the VertexAttribPointer command identifies whether 1832 fixed-point types should be normalized when converted to floating-point. 1833 If <normalized> is TRUE, fixed-point data are converted as specified in 1834 Table 2.6; otherwise, the fixed-point values are converted directly. 1835 1836 (add after first paragraph, p.23) An individual generic vertex attribute 1837 array is enabled or disabled by calling one of 1838 1839 void EnableVertexAttribArrayARB(uint index); 1840 void DisableVertexAttribArrayARB(uint index); 1841 1842 where <index> identifies the generic vertex attribute array to enable or 1843 disable. The error INVALID_VALUE is generated if <index> is greater than 1844 or equal to MAX_VERTEX_ATTRIBS_ARB. 1845 1846 (modify Table 2.4, p.23) 1847 1848 Normal 1849 Command Sizes ized? Types 1850 ---------------------- ------- ------ -------------------------------- 1851 VertexPointer 2,3,4 no short, int, float, double 1852 NormalPointer 3 yes byte, short, int, float, double 1853 ColorPointer 3,4 yes byte, ubyte, short, ushort, 1854 int, uint, float, double 1855 IndexPointer 1 no ubyte, short, int, float, double 1856 TexCoordPointer 1,2,3,4 no short, int, float, double 1857 EdgeFlagPointer 1 no boolean 1858 VertexAttribPointerARB 1,2,3,4 flag byte, ubyte, short, ushort, 1859 int, uint, float, double 1860 WeightPointerARB >=1 yes byte, ubyte, short, ushort, 1861 int, uint, float, double 1862 VertexWeightPointerEXT 1 n/a float 1863 SecondaryColor- 3 yes byte, ubyte, short, ushort, 1864 PointerEXT int, uint, float, double 1865 FogCoordPointerEXT 1 n/a float, double 1866 MatrixIndexPointerARB >=1 no ubyte, ushort, uint 1867 1868 Table 2.4: Vertex array sizes (values per vertex) and data types. The 1869 "normalized" column indicates whether fixed-point types are accepted 1870 directly or normalized to [0,1] (for unsigned types) or [-1,1] (for 1871 singed types). For generic vertex attributes, fixed-point data are 1872 normalized if and only if the <normalized> flag is set. 1873 1874 (modify last paragraph, p.23) The command 1875 1876 void ArrayElement(int i); 1877 1878 transfers the ith element of every enabled array to the GL. The effect of 1879 ArrayElement(i) is the same as the effect of the command sequence 1880 1881 if (ARB_vertex_blend vertex weight array enabled) { 1882 Weight[type]vARB(vertex weight array size, 1883 vertex weight array element i); 1884 } 1885 if (EXT_vertex_weighting vertex weight array enabled) { 1886 VertexWeight[type]vARB(vertex weight array element i); 1887 } 1888 if (normal array enabled) { 1889 Normal3[type]v(normal array element i); 1890 } 1891 if (color array enabled) { 1892 Color[size][type]v(color array element i); 1893 } 1894 if (secondary color array enabled) { 1895 SecondaryColor3[type]vEXT(secondary color array element i); 1896 } 1897 if (fog coordinate array enabled) { 1898 FogCoord[type]vEXT(fog coordinate array element i); 1899 } 1900 if (matrix index array enabled) { 1901 MatrixIndex[type]vARB(matrix index array size, 1902 matrix index array element i); 1903 } 1904 for (j = 0; j < textureUnits; j++) { 1905 if (texture coordinate set j array enabled) { 1906 MultiTexCoord[size][type]v(TEXTURE0 + j, 1907 texture coordinate set j 1908 array element i); 1909 } 1910 if (color index array enabled) { 1911 Index[type]v(color index array element i); 1912 } 1913 if (edge flag array enabled) { 1914 EdgeFlagv(edge flag array element i); 1915 } 1916 for (j = 1; j < genericAttributes; j++) { 1917 if (generic vertex attribute j array enabled) { 1918 if (generic vertex attribute j array normalization flag 1919 is set, and type is not FLOAT or DOUBLE) { 1920 VertexAttrib[size]N[type]vARB(j, generic vertex attribute j 1921 array element i); 1922 } else { 1923 VertexAttrib[size][type]vARB(j, generic vertex attribute j 1924 array element i); 1925 } 1926 } 1927 } 1928 if (generic attribute array 0 enabled) { 1929 if (generic vertex attribute j array normalization flag 1930 is set, and type is not FLOAT or DOUBLE) { 1931 VertexAttrib[size]N[type]vARB(0, generic vertex attribute 0 1932 array element i); 1933 } else { 1934 VertexAttrib[size][type]vARB(0, generic vertex attribute 0 1935 array element i); 1936 } 1937 } else if (vertex array enabled) { 1938 Vertex[size][type]vARB(vertex array element i); 1939 } 1940 1941 where <textureUnits> and <genericAttributes> give the number of texture 1942 units and generic vertex attributes supported by the implementation, 1943 respectively. "[size]" and "[type]" correspond to the size and type of 1944 the corresponding array. For generic vertex attributes, it is assumed 1945 that a complete set of vertex attribute commands exists, even though not 1946 all such functions are provided by the GL. Both generic attribute array 1947 zero and the vertex array can specify a vertex if enabled, but only one 1948 such array is used. As described in section 2.7, setting a generic vertex 1949 attributes listed in Table X.1 will leave the corresponding conventional 1950 vertex attribute undefined, and vice versa. 1951 1952 1953 (modify last paragraph of section, p.28) If the number of supported 1954 texture units (the value of MAX TEXTURE UNITS) is m and the number of 1955 supported generic vertex attributes (MAX_VERTEX_ATTRIBS_ARB) is n, then 1956 the client state required to implement vertex arrays consists of 5+m+n 1957 boolean enables, 5+m+n memory pointers, 5+m+n integer stride values, 4+m+n 1958 symbolic constants representing array types, 2+m+n integers representing 1959 values per element, and n boolean normalization flags. In the initial 1960 state, the enable values are each disabled, the memory pointers are each 1961 null, the strides are each zero, the array types are each FLOAT, the 1962 integers representing values per element are each four, and the 1963 normalization flags are disabled.. 1964 1965 1966 Modify Section 2.10, Coordinate Transformations (p. 29) 1967 1968 (add new paragraphs) Vertex attributes are transformed before the vertex 1969 is used to generate primitives for rasterization, establish a raster 1970 position, or generate vertices for selection or feedback. The attributes 1971 of each vertex are transformed using one of two vertex transformation 1972 modes. The first mode, described in this and subsequent sections, is GL's 1973 conventional vertex transformation model. The second mode, known as 1974 vertex program mode and described in section 2.14, transforms vertex 1975 attributes as specified in an application-supplied vertex program. 1976 1977 Vertex program mode is enabled and disabled, respectively, by 1978 1979 void Enable(enum target); 1980 1981 and 1982 1983 void Disable(enum target); 1984 1985 with <target> equal to VERTEX_PROGRAM_ARB. When vertex program mode is 1986 enabled, vertices are transformed by the currently bound vertex program as 1987 discussed in section 2.14. 1988 1989 When vertex program mode is disabled, vertices, normals, and texture 1990 coordinates are transformed before their coordinates are used to produce 1991 an image in the framebuffer. We begin with a description of how vertex 1992 coordinates are transformed and how the transformation is controlled in 1993 this case. The discussion that continues through section 2.13 applies 1994 when vertex program mode is disabled. 1995 1996 1997 Modify Section 2.10.2, Matrices (p. 31) 1998 1999 (modify 1st paragraph) The projection matrix and model-view matrix are set 2000 and modified with a variety of commands. The affected matrix is 2001 determined by the current matrix mode. The current matrix mode is set 2002 with 2003 2004 void MatrixMode(enum mode); 2005 2006 which takes one of the pre-defined constants TEXTURE, MODELVIEW, COLOR, 2007 PROJECTION, or MATRIX<i>_ARB as the argument. In the case of 2008 MATRIX<i>_ARB, <i> is an integer between 0 and <n>-1 indicating one of <n> 2009 program matrices where <n> is the value of the implementation defined 2010 constant MAX_PROGRAM_MATRICES_ARB. Such program matrices are described in 2011 section 2.14.6. TEXTURE is described later in section 2.10.2, and COLOR 2012 is described in section 3.6.3. If the current matrix mode is MODELVIEW, 2013 then matrix operations apply to the model-view matrix; if PROJECTION, then 2014 they apply to the projection matrix. 2015 2016 (modify last paragraph of section) The state required to implement 2017 transformations consists of a <n>-value integer indicating the current 2018 matrix mode (where <n> is 4 + the number of supported texture and program 2019 matrices), a stack of at least two 4x4 matrices for each of COLOR, 2020 PROJECTION, and TEXTURE with associated stack pointers, <n> stacks (where 2021 <n> is at least 8) of at least one 4x4 matrix for each MATRIX<i>_ARB with 2022 associated stack pointers, and a stack of at least 32 4x4 matrices with an 2023 associated stack pointer for MODELVIEW. Initially, there is only one 2024 matrix on each stack, and all matrices are set to the identity. The 2025 initial matrix mode is MODELVIEW. The initial value of ACTIVE_TEXTURE is 2026 TEXTURE0. 2027 2028 2029 Modify Section 2.11, Clipping (p. 39) 2030 2031 (add to end of next-to-last paragraph, p. 40) ... User clipping is not 2032 supported in vertex program mode if the current program is not 2033 position-invariant (section 2.14.4.5.1). In this case, client-defined 2034 clip planes are always treated as disabled. 2035 2036 2037 Modify Section 2.12, Current Raster Position (p. 42) 2038 2039 (modify fourth paragraph, p.42) The coordinates are treated as if they 2040 were specified in a Vertex command. If vertex program mode is enabled, 2041 the currently bound vertex program is executed, using the x, y, z, and w 2042 coordinates as the object coordinates of the vertex. Otherwise, the x, y, 2043 z, and w coordinates are transformed by the current model-view and 2044 projection matrices. These coordinates, along with current values, are 2045 used to generate a color and texture coordinates just as is done for a 2046 vertex. The color and texture coordinates produced using either method 2047 replace the color and texture coordinates stored in the current raster 2048 position's associated data. When in vertex program mode, the "x" 2049 component of the fog coordinate result replaces the current raster 2050 distance; otherwise, the distance from the origin of the eye coordinate 2051 system to the vertex as transformed by only the current model-view matrix 2052 replaces the current raster distance. The latter distance can be 2053 approximated (see section 3.10). 2054 2055 Rename and Modify Section 2.13.8, Color and Vertex Data Clipping (p.56) 2056 2057 (modify second paragraph, p.57) Texture coordinates, as well as fog 2058 coordinates and point sizes computed on a per-vertex basis, must also be 2059 clipped when a primitive is clipped. The method is exactly analogous to 2060 that used for color clipping. 2061 2062 2063 Add New Section 2.14 and subsections (p. 57). 2064 2065 Section 2.14, Vertex Programs 2066 2067 The conventional GL vertex transformation model described in sections 2.10 2068 through 2.13 is a configurable but essentially hard-wired sequence of 2069 per-vertex computations based on a canonical set of per-vertex parameters 2070 and vertex transformation related state such as transformation matrices, 2071 lighting parameters, and texture coordinate generation parameters. The 2072 general success and utility of the conventional GL vertex transformation 2073 model reflects its basic correspondence to the typical vertex 2074 transformation requirements of 3D applications. 2075 2076 However when the conventional GL vertex transformation model is not 2077 sufficient, the vertex program mode provides a substantially more flexible 2078 model for vertex transformation. The vertex program mode permits 2079 applications to define their own vertex programs. 2080 2081 A vertex program is a character string that specifies a sequence of 2082 operations to perform. Vertex program instructions are typically 2083 4-component vector operations that operate on per-vertex attributes and 2084 program parameters. Vertex programs execute on a per-vertex basis and 2085 operate on each vertex completely independently from any other vertices. 2086 Vertex programs execute a finite fixed sequence of instructions with no 2087 branching or looping. Vertex programs execute without data hazards so 2088 results computed in one instruction can be used immediately afterwards. 2089 The result of a vertex program is a set of vertex result registers that 2090 becomes the set of transformed vertex attributes used during clipping and 2091 primitive assembly. 2092 2093 Vertex programs are defined to operate only in RGBA mode. The results of 2094 vertex program execution are undefined if the GL is in color index mode. 2095 2096 2097 Section 2.14.1, Program Objects 2098 2099 The GL provides one or more program targets, each identifying a portion of 2100 the GL that can be controlled through application-specified programs. The 2101 program target for vertex programs is VERTEX_PROGRAM_ARB. Each program 2102 target has an associated program object, called the current program 2103 object. Each program target also has a default program object, which is 2104 initially the current program object. 2105 2106 Each program object has an associated program string. The command 2107 2108 ProgramStringARB(enum target, enum format, sizei len, 2109 const void *string); 2110 2111 updates the program string for the current program object for <target>. 2112 <format> describes the format of the program string, which must currently 2113 be PROGRAM_FORMAT_ASCII_ARB. <string> is a pointer to the array of bytes 2114 representing the program string being loaded, which need not be 2115 null-terminated. The length of the array is given by <len>. If <string> 2116 is null-terminated, <len> should not include the terminator. 2117 2118 When a program string is loaded, it is interpreted according to syntactic 2119 and semantic rules corresponding to the program target specified by 2120 <target>. If a program violates the syntactic or semantic restrictions of 2121 the program target, ProgramStringARB generates the error 2122 INVALID_OPERATION. 2123 2124 Additionally, ProgramString will update the program error position 2125 (PROGRAM_ERROR_POSITION_ARB) and error string (PROGRAM_ERROR_STRING_ARB). 2126 If a program fails to load, the value of the program error position is set 2127 to the ubyte offset into the specified program string indicating where the 2128 first program error was detected. If the program fails to load because of 2129 a semantic restriction that is not detected until the program is fully 2130 scanned, the error position is set to the value of <len>. If a program 2131 loads successfully, the error position is set to the value negative one. 2132 The implementation-dependent program error string contains one or more 2133 error or warning messages. If a program loads succesfully, the error 2134 string may either contain warning messages or be empty. 2135 2136 Each program object has an associated array of program local parameters. 2137 The number and type of program local parameters is target- and 2138 implementation-dependent. For vertex programs, program local parameters 2139 are four-component floating-point vectors. The number of vectors is given 2140 by the implementation-dependent constant MAX_PROGRAM_LOCAL_PARAMETERS_ARB, 2141 which must be at least 96. The commands 2142 2143 void ProgramLocalParameter4fARB(enum target, uint index, 2144 float x, float y, float z, float w); 2145 void ProgramLocalParameter4fvARB(enum target, uint index, 2146 const float *params); 2147 void ProgramLocalParameter4dARB(enum target, uint index, 2148 double x, double y, double z, double w); 2149 void ProgramLocalParameter4dvARB(enum target, uint index, 2150 const double *params); 2151 2152 update the values of the program local parameter numbered <index> 2153 belonging to the program object currently bound to <target>. For 2154 ProgramLocalParameter4fARB and ProgramLocalParameter4dARB, the four 2155 components of the parameter are updated with the values of <x>, <y>, <z>, 2156 and <w>, respectively. For ProgramLocalParameter4fvARB and 2157 ProgramLocalParameter4dvARB, the four components of the parameter are 2158 updated with the array of four values pointed to by <params>. The error 2159 INVALID_VALUE is generated if <index> is greater than or equal to the 2160 number of program local parameters supported by <target>. 2161 2162 Additionally, each program target has an associated array of program 2163 environment parameters. Unlike program local parameters, program 2164 environment parameters are shared by all program objects of a given 2165 target. The number and type of program environment parameters is target- 2166 and implementation-dependent. For vertex programs, program environment 2167 parameters are four-component floating-point vectors. The number of 2168 vectors is given by the implementation-dependent constant 2169 MAX_PROGRAM_ENV_PARAMETERS_ARB, which must be at least 96. The commands 2170 2171 void ProgramEnvParameter4fARB(enum target, uint index, 2172 float x, float y, float z, float w); 2173 void ProgramEnvParameter4fvARB(enum target, uint index, 2174 const float *params); 2175 void ProgramEnvParameter4dARB(enum target, uint index, 2176 double x, double y, double z, double w); 2177 void ProgramEnvParameter4dvARB(enum target, uint index, 2178 const double *params); 2179 2180 update the values of the program environment parameter numbered <index> 2181 for the given program target <target>. For ProgramEnvParameter4fARB and 2182 ProgramEnvParameter4dARB, the four components of the parameter are updated 2183 with the values of <x>, <y>, <z>, and <w>, respectively. For 2184 ProgramEnvParameter4fvARB and ProgramEnvParameter4dvARB, the four 2185 components of the parameter are updated with the array of four values 2186 pointed to by <params>. The error INVALID_VALUE is generated if <index> 2187 is greater than or equal to the number of program environment parameters 2188 supported by <target>. 2189 2190 Each program target has a default program object. Additionally, named 2191 program objects can be created and operated upon. The name space for 2192 program objects is the positive integers and is shared by programs of all 2193 targets. The name zero is reserved by the GL. 2194 2195 A named program object is created by binding an unused program object name 2196 to a valid program target. The binding is effected by calling 2197 2198 BindProgramARB(enum target, uint program); 2199 2200 with <target> set to the desired program target and <program> set to the 2201 unused program name. The resulting program object has a program target 2202 given by <target> and is assigned target-specific default values (see 2203 section 2.14.7 for vertex programs). BindProgramARB may also be used to 2204 bind an existing program object to a program target. If <program> is 2205 zero, the default program object for <target> is bound. If <program> is 2206 the name of an existing program object whose associated program target is 2207 <target>, the named program object is bound. The error INVALID_OPERATION 2208 is generated if <program> names an existing program object whose 2209 associated program target is anything other than <target>. 2210 2211 Programs objects are deleted by calling 2212 2213 void DeleteProgramsARB(sizei n, const uint *programs); 2214 2215 <programs> contains <n> names of programs to be deleted. After a program 2216 object is deleted, its name is again unused. If a program object that is 2217 bound to any target is deleted, it is as though BindProgramARB is first 2218 executed with same target and a <program> of zero. Unused names in 2219 <programs> are silently ignored, as is the value zero. 2220 2221 The command 2222 2223 void GenProgramsARB(sizei n, uint *programs); 2224 2225 returns <n> currently unused program names in <programs>. These names are 2226 marked as used, for the purposes of GenProgramsARB only, but objects are 2227 created only when they are first bound using BindProgramARB. 2228 2229 2230 Section 2.14.2, Vertex Program Grammar and Semantic Restrictions 2231 2232 Vertex program strings are specified as an array of ASCII characters 2233 containing the program text. When a vertex program is loaded by a call to 2234 ProgramStringARB, the program string is parsed into a set of tokens 2235 possibly separated by whitespace. Spaces, tabs, newlines, carriage 2236 returns, and comments are considered whitespace. Comments begin with the 2237 character "#" and are terminated by a newline, a carriage return, or the 2238 end of the program array. 2239 2240 The Backus-Naur Form (BNF) grammar below specifies the syntactically valid 2241 sequences for vertex programs. The set of valid tokens can be inferred 2242 from the grammar. The token "" represents an empty string and is used to 2243 indicate optional rules. A program is invalid if it contains any 2244 undefined tokens or characters. 2245 2246 A vertex program is required to begin with the header string "!!ARBvp1.0", 2247 without any preceding whitespace. This string identifies the subsequent 2248 program text as a vertex program (version 1.0) that should be parsed 2249 according to the following grammar and semantic rules. Program string 2250 parsing begins with the character immediately following the header string. 2251 2252 <program> ::= <optionSequence> <statementSequence> "END" 2253 2254 <optionSequence> ::= <optionSequence> <option> 2255 | "" 2256 2257 <option> ::= "OPTION" <identifier> ";" 2258 2259 <statementSequence> ::= <statementSequence> <statement> 2260 | "" 2261 2262 <statement> ::= <instruction> ";" 2263 | <namingStatement> ";" 2264 2265 <instruction> ::= <ARL_instruction> 2266 | <VECTORop_instruction> 2267 | <SCALARop_instruction> 2268 | <BINSCop_instruction> 2269 | <BINop_instruction> 2270 | <TRIop_instruction> 2271 | <SWZ_instruction> 2272 2273 <ARL_instruction> ::= "ARL" <maskedAddrReg> "," <scalarSrcReg> 2274 2275 <VECTORop_instruction> ::= <VECTORop> <maskedDstReg> "," <swizzleSrcReg> 2276 2277 <VECTORop> ::= "ABS" 2278 | "FLR" 2279 | "FRC" 2280 | "LIT" 2281 | "MOV" 2282 2283 <SCALARop_instruction> ::= <SCALARop> <maskedDstReg> "," <scalarSrcReg> 2284 2285 <SCALARop> ::= "EX2" 2286 | "EXP" 2287 | "LG2" 2288 | "LOG" 2289 | "RCP" 2290 | "RSQ" 2291 2292 <BINSCop_instruction> ::= <BINSCop> <maskedDstReg> "," <scalarSrcReg> "," 2293 <scalarSrcReg> 2294 2295 <BINSCop> ::= "POW" 2296 2297 <BINop_instruction> ::= <BINop> <maskedDstReg> "," 2298 <swizzleSrcReg> "," <swizzleSrcReg> 2299 2300 <BINop> ::= "ADD" 2301 | "DP3" 2302 | "DP4" 2303 | "DPH" 2304 | "DST" 2305 | "MAX" 2306 | "MIN" 2307 | "MUL" 2308 | "SGE" 2309 | "SLT" 2310 | "SUB" 2311 | "XPD" 2312 2313 <TRIop_instruction> ::= <TRIop> <maskedDstReg> "," 2314 <swizzleSrcReg> "," <swizzleSrcReg> "," 2315 <swizzleSrcReg> 2316 2317 <TRIop> ::= "MAD" 2318 2319 <SWZ_instruction> ::= "SWZ" <maskedDstReg> "," <srcReg> "," 2320 <extendedSwizzle> 2321 2322 <scalarSrcReg> ::= <optionalSign> <srcReg> <scalarSuffix> 2323 2324 <swizzleSrcReg> ::= <optionalSign> <srcReg> <swizzleSuffix> 2325 2326 <maskedDstReg> ::= <dstReg> <optionalMask> 2327 2328 <maskedAddrReg> ::= <addrReg> <addrWriteMask> 2329 2330 <extendedSwizzle> ::= <extSwizComp> "," <extSwizComp> "," 2331 <extSwizComp> "," <extSwizComp> 2332 2333 <extSwizComp> ::= <optionalSign> <extSwizSel> 2334 2335 <extSwizSel> ::= "0" 2336 | "1" 2337 | <component> 2338 2339 <srcReg> ::= <vertexAttribReg> 2340 | <temporaryReg> 2341 | <progParamReg> 2342 2343 <dstReg> ::= <temporaryReg> 2344 | <vertexResultReg> 2345 2346 <vertexAttribReg> ::= <establishedName> 2347 | <vtxAttribBinding> 2348 2349 <temporaryReg> ::= <establishedName> 2350 2351 <progParamReg> ::= <progParamSingle> 2352 | <progParamArray> "[" <progParamArrayMem> "]" 2353 | <paramSingleItemUse> 2354 2355 <progParamSingle> ::= <establishedName> 2356 2357 <progParamArray> ::= <establishedName> 2358 2359 <progParamArrayMem> ::= <progParamArrayAbs> 2360 | <progParamArrayRel> 2361 2362 <progParamArrayAbs> ::= <integer> 2363 2364 <progParamArrayRel> ::= <addrReg> <addrComponent> <addrRegRelOffset> 2365 2366 <addrRegRelOffset> ::= "" 2367 | "+" <addrRegPosOffset> 2368 | "-" <addrRegNegOffset> 2369 2370 <addrRegPosOffset> ::= <integer> from 0 to 63 2371 2372 <addrRegNegOffset> ::= <integer> from 0 to 64 2373 2374 <vertexResultReg> ::= <establishedName> 2375 | <resultBinding> 2376 2377 <addrReg> ::= <establishedName> 2378 2379 <addrComponent> ::= "." "x" 2380 2381 <addrWriteMask> ::= "." "x" 2382 2383 <scalarSuffix> ::= "." <component> 2384 2385 <swizzleSuffix> ::= "" 2386 | "." <component> 2387 | "." <component> <component> 2388 <component> <component> 2389 2390 <component> ::= "x" 2391 | "y" 2392 | "z" 2393 | "w" 2394 2395 <optionalMask> ::= "" 2396 | "." "x" 2397 | "." "y" 2398 | "." "xy" 2399 | "." "z" 2400 | "." "xz" 2401 | "." "yz" 2402 | "." "xyz" 2403 | "." "w" 2404 | "." "xw" 2405 | "." "yw" 2406 | "." "xyw" 2407 | "." "zw" 2408 | "." "xzw" 2409 | "." "yzw" 2410 | "." "xyzw" 2411 2412 <namingStatement> ::= <ATTRIB_statement> 2413 | <PARAM_statement> 2414 | <TEMP_statement> 2415 | <ADDRESS_statement> 2416 | <OUTPUT_statement> 2417 | <ALIAS_statement> 2418 2419 <ATTRIB_statement> ::= "ATTRIB" <establishName> "=" 2420 <vtxAttribBinding> 2421 2422 <vtxAttribBinding> ::= "vertex" "." <vtxAttribItem> 2423 2424 <vtxAttribItem> ::= "position" 2425 | "weight" <vtxOptWeightNum> 2426 | "normal" 2427 | "color" <optColorType> 2428 | "fogcoord" 2429 | "texcoord" <optTexCoordNum> 2430 | "matrixindex" "[" <vtxWeightNum> "]" 2431 | "attrib" "[" <vtxAttribNum> "]" 2432 2433 <vtxAttribNum> ::= <integer> from 0 to MAX_VERTEX_ATTRIBS_ARB-1 2434 2435 <vtxOptWeightNum> ::= "" 2436 | "[" <vtxWeightNum> "]" 2437 2438 <vtxWeightNum> ::= <integer> from 0 to MAX_VERTEX_UNITS_ARB-1, 2439 must be divisible by four 2440 2441 <PARAM_statement> ::= <PARAM_singleStmt> 2442 | <PARAM_multipleStmt> 2443 2444 <PARAM_singleStmt> ::= "PARAM" <establishName> <paramSingleInit> 2445 2446 <PARAM_multipleStmt> ::= "PARAM" <establishName> "[" <optArraySize> "]" 2447 <paramMultipleInit> 2448 2449 <optArraySize> ::= "" 2450 | <integer> from 1 to MAX_PROGRAM_PARAMETERS_ARB 2451 (maximum number of allowed program 2452 parameter bindings) 2453 2454 <paramSingleInit> ::= "=" <paramSingleItemDecl> 2455 2456 <paramMultipleInit> ::= "=" "{" <paramMultInitList> "}" 2457 2458 <paramMultInitList> ::= <paramMultipleItem> 2459 | <paramMultipleItem> "," <paramMultiInitList> 2460 2461 <paramSingleItemDecl> ::= <stateSingleItem> 2462 | <programSingleItem> 2463 | <paramConstDecl> 2464 2465 <paramSingleItemUse> ::= <stateSingleItem> 2466 | <programSingleItem> 2467 | <paramConstUse> 2468 2469 <paramMultipleItem> ::= <stateMultipleItem> 2470 | <programMultipleItem> 2471 | <paramConstDecl> 2472 2473 <stateMultipleItem> ::= <stateSingleItem> 2474 | "state" "." <stateMatrixRows> 2475 2476 <stateSingleItem> ::= "state" "." <stateMaterialItem> 2477 | "state" "." <stateLightItem> 2478 | "state" "." <stateLightModelItem> 2479 | "state" "." <stateLightProdItem> 2480 | "state" "." <stateTexGenItem> 2481 | "state" "." <stateFogItem> 2482 | "state" "." <stateClipPlaneItem> 2483 | "state" "." <statePointItem> 2484 | "state" "." <stateMatrixRow> 2485 2486 <stateMaterialItem> ::= "material" <optFaceType> "." <stateMatProperty> 2487 2488 <stateMatProperty> ::= "ambient" 2489 | "diffuse" 2490 | "specular" 2491 | "emission" 2492 | "shininess" 2493 2494 <stateLightItem> ::= "light" "[" <stateLightNumber> "]" "." 2495 <stateLightProperty> 2496 2497 <stateLightProperty> ::= "ambient" 2498 | "diffuse" 2499 | "specular" 2500 | "position" 2501 | "attenuation" 2502 | "spot" "." <stateSpotProperty> 2503 | "half" 2504 2505 <stateSpotProperty> ::= "direction" 2506 2507 <stateLightModelItem> ::= "lightmodel" <stateLModProperty> 2508 2509 <stateLModProperty> ::= "." "ambient" 2510 | <optFaceType> "." "scenecolor" 2511 2512 <stateLightProdItem> ::= "lightprod" "[" <stateLightNumber> "]" 2513 <optFaceType> "." <stateLProdProperty> 2514 2515 <stateLProdProperty> ::= "ambient" 2516 | "diffuse" 2517 | "specular" 2518 2519 <stateLightNumber> ::= <integer> from 0 to MAX_LIGHTS-1 2520 2521 <stateTexGenItem> ::= "texgen" <optTexCoordNum> "." 2522 <stateTexGenType> "." <stateTexGenCoord> 2523 2524 <stateTexGenType> ::= "eye" 2525 | "object" 2526 2527 <stateTexGenCoord> ::= "s" 2528 | "t" 2529 | "r" 2530 | "q" 2531 2532 <stateFogItem> ::= "fog" "." <stateFogProperty> 2533 2534 <stateFogProperty> ::= "color" 2535 | "params" 2536 2537 <stateClipPlaneItem> ::= "clip" "[" <stateClipPlaneNum> "]" "." "plane" 2538 2539 <stateClipPlaneNum> ::= <integer> from 0 to MAX_CLIP_PLANES-1 2540 2541 <statePointItem> ::= "point" "." <statePointProperty> 2542 2543 <statePointProperty> ::= "size" 2544 | "attenuation" 2545 2546 <stateMatrixRow> ::= <stateMatrixItem> "." "row" "[" 2547 <stateMatrixRowNum> "]" 2548 2549 <stateMatrixRows> ::= <stateMatrixItem> <optMatrixRows> 2550 2551 <optMatrixRows> ::= "" 2552 | "." "row" "[" <stateMatrixRowNum> ".." 2553 <stateMatrixRowNum> "]" 2554 2555 <stateMatrixItem> ::= "matrix" "." <stateMatrixName> 2556 <stateOptMatModifier> 2557 2558 <stateOptMatModifier> ::= "" 2559 | "." <stateMatModifier> 2560 2561 <stateMatModifier> ::= "inverse" 2562 | "transpose" 2563 | "invtrans" 2564 2565 <stateMatrixRowNum> ::= <integer> from 0 to 3 2566 2567 <stateMatrixName> ::= "modelview" <stateOptModMatNum> 2568 | "projection" 2569 | "mvp" 2570 | "texture" <optTexCoordNum> 2571 | "palette" "[" <statePaletteMatNum> "]" 2572 | "program" "[" <stateProgramMatNum> "]" 2573 2574 <stateOptModMatNum> ::= "" 2575 | "[" <stateModMatNum> "]" 2576 2577 <stateModMatNum> ::= <integer> from 0 to MAX_VERTEX_UNITS_ARB-1 2578 2579 <statePaletteMatNum> ::= <integer> from 0 to MAX_PALETTE_MATRICES_ARB-1 2580 2581 <stateProgramMatNum> ::= <integer> from 0 to MAX_PROGRAM_MATRICES_ARB-1 2582 2583 <programSingleItem> ::= <progEnvParam> 2584 | <progLocalParam> 2585 2586 <programMultipleItem> ::= <progEnvParams> 2587 | <progLocalParams> 2588 2589 <progEnvParams> ::= "program" "." "env" 2590 "[" <progEnvParamNums> "]" 2591 2592 <progEnvParamNums> ::= <progEnvParamNum> 2593 | <progEnvParamNum> ".." <progEnvParamNum> 2594 2595 <progEnvParam> ::= "program" "." "env" 2596 "[" <progEnvParamNum> "]" 2597 2598 <progLocalParams> ::= "program" "." "local" 2599 "[" <progLocalParamNums> "]" 2600 2601 <progLocalParamNums> ::= <progLocalParamNum> 2602 | <progLocalParamNum> ".." <progLocalParamNum> 2603 2604 <progLocalParam> ::= "program" "." "local" 2605 "[" <progLocalParamNum> "]" 2606 2607 <progEnvParamNum> ::= <integer> from 0 to 2608 MAX_PROGRAM_ENV_PARAMETERS_ARB - 1 2609 2610 <progLocalParamNum> ::= <integer> from 0 to 2611 MAX_PROGRAM_LOCAL_PARAMETERS_ARB - 1 2612 2613 <paramConstDecl> ::= <paramConstScalarDecl> 2614 | <paramConstVector> 2615 2616 <paramConstUse> ::= <paramConstScalarUse> 2617 | <paramConstVector> 2618 2619 <paramConstScalarDecl> ::= <signedFloatConstant> 2620 2621 <paramConstScalarUse> ::= <floatConstant> 2622 2623 <paramConstVector> ::= "{" <signedFloatConstant> "}" 2624 | "{" <signedFloatConstant> "," 2625 <signedFloatConstant> "}" 2626 | "{" <signedFloatConstant> "," 2627 <signedFloatConstant> "," 2628 <signedFloatConstant> "}" 2629 | "{" <signedFloatConstant> "," 2630 <signedFloatConstant> "," 2631 <signedFloatConstant> "," 2632 <signedFloatConstant> "}" 2633 2634 <signedFloatConstant> ::= <optionalSign> <floatConstant> 2635 2636 <floatConstant> ::= see text 2637 2638 <optionalSign> ::= "" 2639 | "-" 2640 | "+" 2641 2642 <TEMP_statement> ::= "TEMP" <varNameList> 2643 2644 <ADDRESS_statement> ::= "ADDRESS" <varNameList> 2645 2646 <varNameList> ::= <establishName> 2647 | <establishName> "," <varNameList> 2648 2649 <OUTPUT_statement> ::= "OUTPUT" <establishName> "=" 2650 <resultBinding> 2651 2652 <resultBinding> ::= "result" "." "position" 2653 | "result" "." <resultColBinding> 2654 | "result" "." "fogcoord" 2655 | "result" "." "pointsize" 2656 | "result" "." "texcoord" <optTexCoordNum> 2657 2658 <resultColBinding> ::= "color" <optFaceType> <optColorType> 2659 2660 <optFaceType> ::= "" 2661 | "." "front" 2662 | "." "back" 2663 2664 <optColorType> ::= "" 2665 | "." "primary" 2666 | "." "secondary" 2667 2668 <optTexCoordNum> ::= "" 2669 | "[" <texCoordNum> "]" 2670 2671 <texCoordNum> ::= <integer> from 0 to MAX_TEXTURE_UNITS-1 2672 2673 <ALIAS_statement> ::= "ALIAS" <establishName> "=" 2674 <establishedName> 2675 2676 <establishName> ::= <identifier> 2677 2678 <establishedName> ::= <identifier> 2679 2680 <identifier> ::= see text 2681 2682 The <integer> rule matches an integer constant. The integer consists 2683 of a sequence of one or more digits ("0" through "9"). 2684 2685 The <floatConstant> rule matches a floating-point constant consisting 2686 of an integer part, a decimal point, a fraction part, an "e" or 2687 "E", and an optionally signed integer exponent. The integer and 2688 fraction parts both consist of a sequence of one or more digits ("0" 2689 through "9"). Either the integer part or the fraction parts (not 2690 both) may be missing; either the decimal point or the "e" (or "E") 2691 and the exponent (not both) may be missing. 2692 2693 The <identifier> rule matches a sequence of one or more letters ("A" 2694 through "Z", "a" through "z"), digits ("0" through "9), underscores ("_"), 2695 or dollar signs ("$"); the first character must not be a number. Upper 2696 and lower case letters are considered different (names are 2697 case-sensitive). The following strings are reserved keywords and may not 2698 be used as identifiers: 2699 2700 ABS, ADD, ADDRESS, ALIAS, ARL, ATTRIB, DP3, DP4, DPH, DST, END, EX2, 2701 EXP, FLR, FRC, LG2, LIT, LOG, MAD, MAX, MIN, MOV, MUL, OPTION, OUTPUT, 2702 PARAM, POW, RCP, RSQ, SGE, SLT, SUB, SWZ, TEMP, XPD, program, result, 2703 state, and vertex. 2704 2705 The error INVALID_OPERATION is generated if a vertex program fails to load 2706 because it is not syntactically correct or for one of the semantic 2707 restrictions described in the following sections. 2708 2709 A successfully loaded vertex program is parsed into a sequence of 2710 instructions. Each instruction is identified by its tokenized name. The 2711 operation of these instructions when executed is defined in section 2712 2.14.5. A successfully loaded program string replaces the program string 2713 previously loaded into the specified program object. If the OUT_OF_MEMORY 2714 error is generated by ProgramStringARB, no change is made to the previous 2715 contents of the current program object. 2716 2717 2718 Section 2.14.3, Vertex Program Variables 2719 2720 Vertex programs may access a number of different variables during their 2721 execution. The following sections define the variables that can be 2722 declared and used by a vertex program. 2723 2724 Explicit variable declarations allow a vertex program to establish a 2725 variable name that can be used to refer to a specified resource in 2726 subsequent instructions. A vertex program will fail to load if it 2727 declares the same variable name more than once or if it refers to a 2728 variable name that has not been previously declared in the program string. 2729 2730 Implicit variable declarations allow a vertex program to use the name of 2731 certain available resources by name. 2732 2733 Section 2.14.3.1, Vertex Attributes 2734 2735 Vertex program attribute variables are a set of four-component 2736 floating-point vectors holding the attributes of the vertex being 2737 processed. Vertex attribute variables are read-only during vertex program 2738 execution. 2739 2740 Vertex attribute variables can be declared explicitly using the 2741 <ATTRIB_statement> grammar rule, or implicitly using the 2742 <vtxAttribBinding> grammar rule in an executable instruction. 2743 2744 Each vertex attribute variable is bound to a single item of vertex state 2745 according to the <vtxAttrBinding> grammar rule. The set of GL state that 2746 can be bound to a vertex attribute variable is given in Table X.2. Vertex 2747 attribute variables are initialized at each vertex program invocation with 2748 the current values of the bound state. 2749 2750 Vertex Attribute Binding Components Underlying State 2751 ------------------------ ---------- ------------------------------ 2752 vertex.position (x,y,z,w) object coordinates 2753 vertex.weight (w,w,w,w) vertex weights 0-3 2754 vertex.weight[n] (w,w,w,w) vertex weights n-n+3 2755 vertex.normal (x,y,z,1) normal 2756 vertex.color (r,g,b,a) primary color 2757 vertex.color.primary (r,g,b,a) primary color 2758 vertex.color.secondary (r,g,b,a) secondary color 2759 vertex.fogcoord (f,0,0,1) fog coordinate 2760 vertex.texcoord (s,t,r,q) texture coordinate, unit 0 2761 vertex.texcoord[n] (s,t,r,q) texture coordinate, unit n 2762 vertex.matrixindex (i,i,i,i) vertex matrix indices 0-3 2763 vertex.matrixindex[n] (i,i,i,i) vertex matrix indices n-n+3 2764 vertex.attrib[n] (x,y,z,w) generic vertex attribute n 2765 2766 Table X.2: Vertex Attribute Bindings. The "Components" column 2767 indicates the mapping of the state in the "Underlying State" column. 2768 Values of "0" or "1" in the "Components" column indicate the constants 2769 0.0 and 1.0, respectively. Bindings containing "[n]" require an integer 2770 value of <n> to select an individual item. 2771 2772 If a vertex attribute binding matches "vertex.position", the "x", "y", "z" 2773 and "w" components of the vertex attribute variable are filled with the 2774 "x", "y", "z", and "w" components, respectively, of the vertex position. 2775 2776 If a vertex attribute binding matches "vertex.normal", the "x", "y", and 2777 "z" components of the vertex attribute variable are filled with the "x", 2778 "y", and "z" components, respectively, of the vertex normal. The "w" 2779 component is filled with 1. 2780 2781 If a vertex attribute binding matches "vertex.color" or 2782 "vertex.color.primary", the "x", "y", "z", and "w" components of the 2783 vertex attribute variable are filled with the "r", "g", "b", and "a" 2784 components, respectively, of the vertex color. 2785 2786 If a vertex attribute binding matches "vertex.color.secondary", the "x", 2787 "y", "z", and "w" components of the vertex attribute variable are filled 2788 with the "r", "g", "b", and "a" components, respectively, of the vertex 2789 secondary color. 2790 2791 If a vertex attribute binding matches "vertex.fogcoord", the "x" component 2792 of the vertex attribute variable is filled with the vertex fog coordinate. 2793 The "y", "z", and "w" coordinates are filled with 0, 0, and 1, 2794 respectively. 2795 2796 If a vertex attribute binding matches "vertex.texcoord" or 2797 "vertex.texcoord[n]", the "x", "y", "z", and "w" components of the vertex 2798 attribute variable are filled with the "s", "t", "r", and "q" components, 2799 respectively, of the vertex texture coordinates for texture unit <n>. If 2800 "[n]" is omitted, texture unit zero is used. 2801 2802 If a vertex attribute binding matches "vertex.weight" or 2803 "vertex.weight[n]", the "x", "y", "z", and "w" components of the vertex 2804 attribute variable are filled with vertex weights <n> through <n>+3, 2805 respectively. If "[n]" is omitted, weights zero through three are used. 2806 For the purposes of this binding, all weights supported by the 2807 implementation but not set by the application are set to zero, including 2808 the extra derived weight corresponding to the fixed-function 2809 WEIGHT_SUM_UNITY_ARB enable. For components whose corresponding weight is 2810 not supported by the implementation (i.e., numbered MAX_VERTEX_UNITS_ARB 2811 or larger), "y" and "z" components are set to 0.0 and "w" components are 2812 set to 1.0. A vertex program will fail to load if a vertex attribute 2813 binding specifies a weight number <n> that is greater than or equal to 2814 MAX_VERTEX_UNITS_ARB or is not divisible by four. 2815 2816 If a vertex attribute binding matches "vertex.matrixindex" or 2817 "vertex.matrixindex[n]", the "x", "y", "z", and "w" components of the 2818 vertex attribute variable are filled with matrix indices <n> through <n>+3 2819 of the vertex, respectively. If "[n]" is omitted, matrix indices zero 2820 through three are used. For components whose corresponding matrix index 2821 is not supported by the implementation (i.e., numbered 2822 MAX_VERTEX_UNITS_ARB or larger), "y", and "z" components are set to 0.0 2823 and "w" components are set to 1.0. A vertex program will fail to load if 2824 an attribute binding specifies a matrix index number <n> that is greater 2825 than or equal MAX_VERTEX_UNITS_ARB or is not divisible by four. 2826 2827 If a vertex attribute binding matches "vertex.attrib[n]", the "x", "y", 2828 "z" and "w" components of the vertex attribute variable are filled with 2829 the "x", "y", "z", and "w" components, respectively, of generic vertex 2830 attribute <n>. Note that "vertex.attrib[0]" and "vertex.position" are 2831 equivalent. 2832 2833 As described in section 2.7, setting a generic vertex attribute may leave 2834 a corresponding conventional vertex attribute undefined, and vice versa. 2835 To prevent inadvertent use of attribute pairs with undefined attributes, a 2836 vertex program will fail to load if it binds both a conventional vertex 2837 attribute and a generic vertex attribute listed in the same row of Table 2838 X.2.1. 2839 2840 Conventional Attribute Binding Generic Attribute Binding 2841 ------------------------------ ------------------------- 2842 vertex.position vertex.attrib[0] 2843 vertex.weight vertex.attrib[1] 2844 vertex.weight[0] vertex.attrib[1] 2845 vertex.normal vertex.attrib[2] 2846 vertex.color vertex.attrib[3] 2847 vertex.color.primary vertex.attrib[3] 2848 vertex.color.secondary vertex.attrib[4] 2849 vertex.fogcoord vertex.attrib[5] 2850 vertex.texcoord vertex.attrib[8] 2851 vertex.texcoord[0] vertex.attrib[8] 2852 vertex.texcoord[1] vertex.attrib[9] 2853 vertex.texcoord[2] vertex.attrib[10] 2854 vertex.texcoord[3] vertex.attrib[11] 2855 vertex.texcoord[4] vertex.attrib[12] 2856 vertex.texcoord[5] vertex.attrib[13] 2857 vertex.texcoord[6] vertex.attrib[14] 2858 vertex.texcoord[7] vertex.attrib[15] 2859 vertex.texcoord[n] vertex.attrib[8+n] 2860 2861 Table X.2.1: Invalid Vertex Attribute Binding Pairs. Vertex programs 2862 may not bind both attributes listed in any row. The <n> in the last row 2863 matches the number of any valid texture unit. 2864 2865 2866 Section 2.14.3.2, Vertex Program Parameters 2867 2868 Vertex program parameter variables are a set of four-component 2869 floating-point vectors used as constants during vertex program execution. 2870 Vertex program parameters retain their values across vertex program 2871 invocations, although their values can change between invocations due to 2872 GL state changes. 2873 2874 Single program parameter variables and arrays of program parameter 2875 variables can be declared explicitly using the <PARAM_statement> grammar 2876 rule. Single program parameter variables can also be declared implicitly 2877 using the <paramSingleItemUse> grammar rule in an executable instruction. 2878 2879 Each single program parameter variable is bound to a constant vector or to 2880 a GL state vector according to the <paramSingleInit> grammar rule. 2881 Individual items of a program parameter array are bound to constant 2882 vectors or GL state vectors according to the <programMultipleInit> grammar 2883 rule. The set of GL state that can be bound to program parameter 2884 variables are given in Tables X.3.1 through X.3.8. 2885 2886 2887 Constant Bindings 2888 2889 A program parameter variable can be bound to a scalar or vector constant 2890 using the <paramConstDecl> grammar rule (explicit declarations) or the 2891 <paramConstUse> grammar rule (implicit declarations). 2892 2893 If a program parameter binding matches the <paramConstScalarDecl> or 2894 <paramConstScalarUse> grammar rules, the corresponding program parameter 2895 variable is bound to the vector (X,X,X,X), where X is the value of the 2896 specified constant. Note that the <paramConstScalarUse> grammar rule, 2897 used only in implicit declarations, allows only non-negative constants. 2898 This disambiguates cases like "-2", which could conceivably be taken to 2899 mean either the vector "(2,2,2,2)" with all components negated or 2900 "(-2,-2,-2,-2)" without negation. Only the former interpretation is 2901 allowed by the grammar. 2902 2903 If a program parameter binding matches <paramConstVector>, the 2904 corresponding program parameter variable is bound to the vector (X,Y,Z,W), 2905 where X, Y, Z, and W are the values corresponding to the first, second, 2906 third, and fourth match of <signedFloatConstant>. If fewer than four 2907 constants are specified, Y, Z, and W assume the values 0.0, 0.0, and 1.0, 2908 if their respective constants are not specified. 2909 2910 Program parameter variables initialized to constant values can never be 2911 modified. 2912 2913 2914 Program Environment/Local Parameter Bindings 2915 2916 Binding Components Underlying State 2917 ----------------------------- ---------- ---------------------------- 2918 program.env[a] (x,y,z,w) program environment 2919 parameter a 2920 program.local[a] (x,y,z,w) program local parameter a 2921 program.env[a..b] (x,y,z,w) program environment 2922 parameters a through b 2923 program.local[a..b] (x,y,z,w) program local parameters 2924 a through b 2925 2926 Table X.3.1: Program Environment/Local Parameter Bindings. <a> and <b> 2927 indicate parameter numbers, where <a> must be less than or equal to <b>. 2928 2929 If a program parameter binding matches "program.env[a]" or 2930 "program.local[a]", the four components of the program parameter variable 2931 are filled with the four components of program environment parameter <a> 2932 or program local parameter <a>, respectively. 2933 2934 Additionally, for program parameter array bindings, "program.env[a..b]" 2935 and "program.local[a..b]" are equivalent to specifying program environment 2936 parameters <a> through <b> in order or program local parameters <a> 2937 through <b> in order, respectively. In either case, a program will fail 2938 to load if <a> is greater than <b>. 2939 2940 2941 Material Property Bindings 2942 2943 Binding Components Underlying State 2944 ----------------------------- ---------- ---------------------------- 2945 state.material.ambient (r,g,b,a) front ambient material color 2946 state.material.diffuse (r,g,b,a) front diffuse material color 2947 state.material.specular (r,g,b,a) front specular material color 2948 state.material.emission (r,g,b,a) front emissive material color 2949 state.material.shininess (s,0,0,1) front material shininess 2950 state.material.front.ambient (r,g,b,a) front ambient material color 2951 state.material.front.diffuse (r,g,b,a) front diffuse material color 2952 state.material.front.specular (r,g,b,a) front specular material color 2953 state.material.front.emission (r,g,b,a) front emissive material color 2954 state.material.front.shininess (s,0,0,1) front material shininess 2955 state.material.back.ambient (r,g,b,a) back ambient material color 2956 state.material.back.diffuse (r,g,b,a) back diffuse material color 2957 state.material.back.specular (r,g,b,a) back specular material color 2958 state.material.back.emission (r,g,b,a) back emissive material color 2959 state.material.back.shininess (s,0,0,1) back material shininess 2960 2961 Table X.3.2: Material Property Bindings. If a material face is not 2962 specified in the binding, the front property is used. 2963 2964 If a program parameter binding matches any of the material properties 2965 listed in Table X.3.2, the program parameter variable is filled according 2966 to the table. For ambient, diffuse, specular, or emissive colors, the 2967 "x", "y", "z", and "w" components are filled with the "r", "g", "b", and 2968 "a" components, respectively, of the corresponding material color. For 2969 material shininess, the "x" component is filled with the material's 2970 specular exponent, and the "y", "z", and "w" components are filled with 0, 2971 0, and 1, respectively. Bindings containing ".back" refer to the back 2972 material; all other bindings refer to the front material. 2973 2974 Material properties can be changed inside a Begin/End pair, either 2975 directly by calling Material, or indirectly through color material. 2976 However, such property changes are not guaranteed to update program 2977 parameter bindings until the following End command. Program parameter 2978 variables bound to material properties changed inside a Begin/End pair are 2979 undefined until the following End command. 2980 2981 2982 Light Property Bindings 2983 2984 Binding Components Underlying State 2985 ----------------------------- ---------- ---------------------------- 2986 state.light[n].ambient (r,g,b,a) light n ambient color 2987 state.light[n].diffuse (r,g,b,a) light n diffuse color 2988 state.light[n].specular (r,g,b,a) light n specular color 2989 state.light[n].position (x,y,z,w) light n position 2990 state.light[n].attenuation (a,b,c,e) light n attenuation constants 2991 and spot light exponent 2992 state.light[n].spot.direction (x,y,z,c) light n spot direction and 2993 cutoff angle cosine 2994 state.light[n].half (x,y,z,1) light n infinite half-angle 2995 state.lightmodel.ambient (r,g,b,a) light model ambient color 2996 state.lightmodel.scenecolor (r,g,b,a) light model front scene color 2997 state.lightmodel. (r,g,b,a) light model front scene color 2998 front.scenecolor 2999 state.lightmodel. (r,g,b,a) light model back scene color 3000 back.scenecolor 3001 state.lightprod[n].ambient (r,g,b,a) light n / front material 3002 ambient color product 3003 state.lightprod[n].diffuse (r,g,b,a) light n / front material 3004 diffuse color product 3005 state.lightprod[n].specular (r,g,b,a) light n / front material 3006 specular color product 3007 state.lightprod[n]. (r,g,b,a) light n / front material 3008 front.ambient ambient color product 3009 state.lightprod[n]. (r,g,b,a) light n / front material 3010 front.diffuse diffuse color product 3011 state.lightprod[n]. (r,g,b,a) light n / front material 3012 front.specular specular color product 3013 state.lightprod[n]. (r,g,b,a) light n / back material 3014 back.ambient ambient color product 3015 state.lightprod[n]. (r,g,b,a) light n / back material 3016 back.diffuse diffuse color product 3017 state.lightprod[n]. (r,g,b,a) light n / back material 3018 back.specular specular color product 3019 3020 Table X.3.3: Light Property Bindings. <n> indicates a light number. 3021 3022 If a program parameter binding matches "state.light[n].ambient", 3023 "state.light[n].diffuse", or "state.light[n].specular", the "x", "y", "z", 3024 and "w" components of the program parameter variable are filled with the 3025 "r", "g", "b", and "a" components, respectively, of the corresponding 3026 light color. 3027 3028 If a program parameter binding matches "state.light[n].position", the "x", 3029 "y", "z", and "w" components of the program parameter variable are filled 3030 with the "x", "y", "z", and "w" components, respectively, of the light 3031 position. 3032 3033 If a program parameter binding matches "state.light[n].attenuation", the 3034 "x", "y", and "z" components of the program parameter variable are filled 3035 with the constant, linear, and quadratic attenuation parameters of the 3036 specified light, respectively (section 2.13.1). The "w" component of the 3037 program parameter variable is filled with the spot light exponent of the 3038 specified light. 3039 3040 If a program parameter binding matches "state.light[n].spot.direction", 3041 the "x", "y", and "z" components of the program parameter variable are 3042 filled with the "x", "y", and "z" components of the spot light direction 3043 of the specified light, respectively (section 2.13.1). The "w" component 3044 of the program parameter variable is filled with the cosine of the spot 3045 light cutoff angle of the specified light. 3046 3047 If a program parameter binding matches "state.light[n].half", the "x", 3048 "y", and "z" components of the program parameter variable are filled with 3049 the x, y, and z components, respectively, of the normalized infinite 3050 half-angle vector 3051 3052 h_inf = || P + (0, 0, 1) ||. 3053 3054 The "w" component is filled with 1. In the computation of h_inf, P 3055 consists of the x, y, and z coordinates of the normalized vector from the 3056 eye position P_e to the eye-space light position P_pli (section 2.13.1). 3057 h_inf is defined to correspond to the normalized half-angle vector when 3058 using an infinite light (w coordinate of the position is zero) and an 3059 infinite viewer (v_bs is FALSE). For local lights or a local viewer, 3060 h_inf is well-defined but does not match the normalized half-angle vector, 3061 which will vary depending on the vertex position. 3062 3063 If a program parameter binding matches "state.lightmodel.ambient", the 3064 "x", "y", "z", and "w" components of the program parameter variable are 3065 filled with the "r", "g", "b", and "a" components of the light model 3066 ambient color, respectively. 3067 3068 If a program parameter binding matches "state.lightmodel.scenecolor" or 3069 "state.lightmodel.front.scenecolor", the "x", "y", and "z" components of 3070 the program parameter variable are filled with the "r", "g", and "b" 3071 components respectively of the "front scene color" 3072 3073 c_scene = a_cs * a_cm + e_cm, 3074 3075 where a_cs is the light model ambient color, a_cm is the front ambient 3076 material color, and e_cm is the front emissive material color. The "w" 3077 component of the program parameter variable is filled with the alpha 3078 component of the front diffuse material color. If a program parameter 3079 binding matches "state.lightmodel.back.scenecolor", a similar back scene 3080 color, computed using back-facing material properties, is used. The front 3081 and back scene colors match the values that would be assigned to vertices 3082 using conventional lighting if all lights were disabled. 3083 3084 If a program parameter binding matches anything beginning with 3085 "state.lightprod[n]", the "x", "y", and "z" components of the program 3086 parameter variable are filled with the "r", "g", and "b" components, 3087 respectively, of the corresponding light product. The three light product 3088 components are the products of the corresponding color components of the 3089 specified material property and the light color of the specified light 3090 (see Table X.3.3). The "w" component of the program parameter variable is 3091 filled with the alpha component of the specified material property. 3092 3093 Light products depend on material properties, which can be changed inside 3094 a Begin/End pair. Such property changes are not guaranteed to take effect 3095 until the following End command. Program parameter variables bound to 3096 light products whose corresponding material property changes inside a 3097 Begin/End pair are undefined until the following End command. 3098 3099 3100 Texture Coordinate Generation Property Bindings 3101 3102 Binding Components Underlying State 3103 ------------------------- ---------- ---------------------------- 3104 state.texgen[n].eye.s (a,b,c,d) TexGen eye linear plane 3105 coefficients, s coord, unit n 3106 state.texgen[n].eye.t (a,b,c,d) TexGen eye linear plane 3107 coefficients, t coord, unit n 3108 state.texgen[n].eye.r (a,b,c,d) TexGen eye linear plane 3109 coefficients, r coord, unit n 3110 state.texgen[n].eye.q (a,b,c,d) TexGen eye linear plane 3111 coefficients, q coord, unit n 3112 state.texgen[n].object.s (a,b,c,d) TexGen object linear plane 3113 coefficients, s coord, unit n 3114 state.texgen[n].object.t (a,b,c,d) TexGen object linear plane 3115 coefficients, t coord, unit n 3116 state.texgen[n].object.r (a,b,c,d) TexGen object linear plane 3117 coefficients, r coord, unit n 3118 state.texgen[n].object.q (a,b,c,d) TexGen object linear plane 3119 coefficients, q coord, unit n 3120 3121 Table X.3.4: Texture Coordinate Generation Property Bindings. "[n]" is 3122 optional -- texture unit <n> is used if specified; texture unit 0 is 3123 used otherwise. 3124 3125 If a program parameter binding matches a set of TexGen plane coefficients, 3126 the "x", "y", "z", and "w" components of the program parameter variable 3127 are filled with the coefficients p1, p2, p3, and p4, respectively, for 3128 object linear coefficients, and the coefficents p1', p2', p3', and p4', 3129 respectively, for eye linear coefficients (section 2.10.4). 3130 3131 3132 Fog Property Bindings 3133 3134 Binding Components Underlying State 3135 ----------------------------- ---------- ---------------------------- 3136 state.fog.color (r,g,b,a) RGB fog color (section 3.10) 3137 state.fog.params (d,s,e,r) fog density, linear start 3138 and end, and 1/(end-start) 3139 (section 3.10) 3140 3141 Table X.3.5: Fog Property Bindings 3142 3143 If a program parameter binding matches "state.fog.color", the "x", "y", 3144 "z", and "w" components of the program parameter variable are filled with 3145 the "r", "g", "b", and "a" components, respectively, of the fog color 3146 (section 3.10). 3147 3148 If a program parameter binding matches "state.fog.params", the "x", "y", 3149 and "z" components of the program parameter variable are filled with the 3150 fog density, linear fog start, and linear fog end parameters (section 3151 3.10), respectively. The "w" component is filled with 1/(end-start), 3152 where end and start are the linear fog end and start parameters, 3153 respectively. 3154 3155 3156 Clip Plane Property Bindings 3157 3158 Binding Components Underlying State 3159 ----------------------------- ---------- ---------------------------- 3160 state.clip[n].plane (a,b,c,d) clip plane n coefficients 3161 3162 Table X.3.6: Clip Plane Property Bindings. <n> specifies the clip 3163 plane number, and is required. 3164 3165 If a program parameter binding matches "state.clip[n].plane", the "x", 3166 "y", "z", and "w" components of the program parameter variable are filled 3167 with the coefficients p1', p2', p3', and p4', respectively, of clip plane 3168 <n> (section 2.11). 3169 3170 3171 Point Property Bindings 3172 3173 Binding Components Underlying State 3174 ----------------------------- ---------- ---------------------------- 3175 state.point.size (s,n,x,f) point size, min and max size 3176 clamps, and fade threshold 3177 (section 3.3) 3178 state.point.attenuation (a,b,c,1) point size attenuation consts 3179 3180 Table X.3.7: Point Property Bindings 3181 3182 If a program parameter binding matches "state.point.size", the "x", "y", 3183 "z", and "w" components of the program parameter variable are filled with 3184 the point size, minimum point size, maximum point size, and fade 3185 threshold, respectively (section 3.3). 3186 3187 If a program parameter binding matches "state.point.attenuation", the "x", 3188 "y", and "z" components of the program parameter variable are filled with 3189 the constant, linear, and quadratic point size attenuation parameters (a, 3190 b, and c), respectively (section 3.3). The "w" component is filled with 3191 1. 3192 3193 3194 Matrix Property Bindings 3195 3196 Binding Underlying State 3197 ------------------------------------ --------------------------- 3198 * state.matrix.modelview[n] modelview matrix n 3199 state.matrix.projection projection matrix 3200 state.matrix.mvp modelview-projection matrix 3201 * state.matrix.texture[n] texture matrix n 3202 state.matrix.palette[n] modelview palette matrix n 3203 state.matrix.program[n] program matrix n 3204 3205 Table X.3.8: Base Matrix Property Bindings. The "[n]" syntax indicates 3206 a specific matrix number. For modelview and texture matrices, a matrix 3207 number is optional, and matrix zero will be used if the matrix number is 3208 omitted. These base bindings may further be modified by a 3209 inverse/transpose selector and a row selector. 3210 3211 If the beginning of a program parameter binding matches any of the matrix 3212 binding names listed in Table X.3.8, the binding corresponds to a 4x4 3213 matrix. If the parameter binding is followed by ".inverse", ".transpose", 3214 or ".invtrans" (<stateMatModifier> grammar rule), the inverse, transpose, 3215 or transpose of the inverse, respectively, of the matrix specified in 3216 Table X.3.8 is selected. Otherwise, the matrix specified in Table X.3.8 3217 is selected. If the specified matrix is poorly-conditioned (singular or 3218 nearly so), its inverse matrix is undefined. The binding name 3219 "state.matrix.mvp" refers to the product of modelview matrix zero and the 3220 projection matrix, defined as 3221 3222 MVP = P * M0, 3223 3224 where P is the projection matrix and M0 is modelview matrix zero. 3225 3226 If the selected matrix is followed by ".row[<a>]" (matching the 3227 <stateMatrixRow> grammar rule), the "x", "y", "z", and "w" components of 3228 the program parameter variable are filled with the four entries of row <a> 3229 of the selected matrix. In the example, 3230 3231 PARAM m0 = state.matrix.modelview[1].row[0]; 3232 PARAM m1 = state.matrix.projection.transpose.row[3]; 3233 3234 the variable "m0" is set to the first row (row 0) of modelview matrix 1 3235 and "m1" is set to the last row (row 3) of the transpose of the projection 3236 matrix. 3237 3238 For program parameter array bindings, multiple rows of the selected matrix 3239 can be bound via the <stateMatrixRows> grammar rule. If the selected 3240 matrix binding is followed by ".row[<a>..<b>]", the result is equivalent 3241 to specifying matrix rows <a> through <b>, in order. A program will fail 3242 to load if <a> is greater than <b>. If no row selection is specified 3243 (<optMatrixRows> matches ""), matrix rows 0 through 3 are bound in order. 3244 In the example, 3245 3246 PARAM m2[] = { state.matrix.program[0].row[1..2] }; 3247 PARAM m3[] = { state.matrix.program[0].transpose }; 3248 3249 the array "m2" has two entries, containing rows 1 and 2 of program matrix 3250 zero, and "m3" has four entries, containing all four rows of the transpose 3251 of program matrix zero. 3252 3253 3254 Program Parameter Arrays 3255 3256 A program parameter array variable can be declared explicitly by matching 3257 the <PARAM_multipleStmt> grammar rule. Programs can optionally specify 3258 the number of individual program parameters in the array, using the 3259 <optArraySize> grammar rule. Program parameter arrays may not be declared 3260 implicity. 3261 3262 Individual parameter variables in a program parameter array are bound to 3263 GL state vectors or constant vectors as specified by the grammar rule 3264 <paramMultInitList>. Each individual parameter in the array is bound in 3265 turn as described above. 3266 3267 The total number of entries in the array is equal to the number of 3268 parameters bound in the initializer list. A vertex program that specifies 3269 an array size (<optArraySize> matches <integer>) that does not match the 3270 number of parameter bindings in the initialization list will fail to load. 3271 3272 Program parameter array variables may be accessed using absolute 3273 addressing by matching the <progParamArrayAbs> grammar rule, or relative 3274 addressing by matching the <progParamArrayRel> grammar rule. 3275 3276 Array accesses using absolute addressing are checked against the limits of 3277 the array. If any vertex program instruction accesses a program parameter 3278 array using absolute addressing with an out-of-range index (greater than 3279 or equal to the size of the array), the vertex program will fail to load. 3280 3281 Individual state vectors can have no more than one unique binding in any 3282 given program. The GL will automatically combine multiple bindings of the 3283 same state vector into a single unique binding, except for the case where 3284 a state vector is bound multiple times in program parameter arrays 3285 accessed using relative addressing. A vertex program will fail to load if 3286 any GL state vector is bound multiple times in a single array accessed 3287 using relative addressing or bound once in two or more arrays accessed 3288 using relative addressing. 3289 3290 3291 Section 2.14.3.3, Vertex Program Temporaries 3292 3293 Vertex program temporary variables are a set of four-component 3294 floating-point vectors used to hold temporary results during vertex 3295 program execution. Temporaries do not persist between program 3296 invocations, and are undefined at the beginning of each vertex program 3297 invocation. 3298 3299 Vertex program temporary variables can be declared explicitly using the 3300 <TEMP_statement> grammar rule. Each such statement can declare one or 3301 more temporaries. Vertex program temporary variables can not be declared 3302 implicitly. 3303 3304 3305 Section 2.14.3.4, Vertex Program Results 3306 3307 Vertex program result variables are a set of four-component floating-point 3308 vectors used to hold the final results of a vertex program. Vertex 3309 program result variables are write-only during vertex program execution. 3310 3311 Vertex program result variables can be declared explicitly using the 3312 <OUTPUT_statement> grammar rule, or implicitly using the <resultBinding> 3313 grammar rule in an executable instruction. Each vertex program result 3314 variable is bound to a transformed vertex attribute used during primitive 3315 assembly and rasterization. The set of vertex program result variable 3316 bindings is given in Table X.4. 3317 3318 Binding Components Description 3319 ----------------------------- ---------- ---------------------------- 3320 result.position (x,y,z,w) position in clip coordinates 3321 result.color (r,g,b,a) front-facing primary color 3322 result.color.primary (r,g,b,a) front-facing primary color 3323 result.color.secondary (r,g,b,a) front-facing secondary color 3324 result.color.front (r,g,b,a) front-facing primary color 3325 result.color.front.primary (r,g,b,a) front-facing primary color 3326 result.color.front.secondary (r,g,b,a) front-facing secondary color 3327 result.color.back (r,g,b,a) back-facing primary color 3328 result.color.back.primary (r,g,b,a) back-facing primary color 3329 result.color.back.secondary (r,g,b,a) back-facing secondary color 3330 result.fogcoord (f,*,*,*) fog coordinate 3331 result.pointsize (s,*,*,*) point size 3332 result.texcoord (s,t,r,q) texture coordinate, unit 0 3333 result.texcoord[n] (s,t,r,q) texture coordinate, unit n 3334 3335 Table X.4: Vertex Result Variable Bindings. Components labeled "*" are 3336 unused. 3337 3338 If a result variable binding matches "result.position", updates to the 3339 "x", "y", "z", and "w" components of the result variable modify the "x", 3340 "y", "z", and "w" components, respectively, of the transformed vertex's 3341 clip coordinates. Final window coordinates will be generated for the 3342 vertex as described in section 2.14.4.4. 3343 3344 If a result variable binding match begins with "result.color", updates to 3345 the "x", "y", "z", and "w" components of the result variable modify the 3346 "r", "g", "b", and "a" components, respectively, of the corresponding 3347 vertex color attribute in Table X.4. Color bindings that do not specify 3348 "front" or "back" are consided to refer to front-facing colors. Color 3349 bindings that do not specify "primary" or "secondary" are considered to 3350 refer to primary colors. 3351 3352 If a result variable binding matches "result.fogcoord", updates to the "x" 3353 component of the result variable set the transformed vertex's fog 3354 coordinate. Updates to the "y", "z", and "w" components of the result 3355 variable have no effect. 3356 3357 If a result variable binding matches "result.pointsize", updates to the 3358 "x" component of the result variable set the transformed vertex's point 3359 size. Updates to the "y", "z", and "w" components of the result variable 3360 have no effect. 3361 3362 If a result variable binding matches "result.texcoord" or 3363 "result.texcoord[n]", updates to the "x", "y", "z", and "w" components of 3364 the result variable set the "s", "t", "r" and "q" components, 3365 respectively, of the transformed vertex's texture coordinates for texture 3366 unit <n>. If "[n]" is omitted, texture unit zero is selected. 3367 3368 When in vertex program mode, all attributes of a transformed vertex are 3369 undefined at each vertex program invocation. Any results, or even 3370 individual components of results, that are not written to during vertex 3371 program execution remain undefined. 3372 3373 3374 Section 2.14.3.5, Vertex Program Address Registers 3375 3376 Vertex program address register variables are a set of four-component 3377 signed integer vectors where only the "x" component of the address 3378 registers is currently accessible. Address registers are used as indices 3379 when performing relative addressing in program parameter arrays (section 3380 2.14.4.2). 3381 3382 Vertex program address registers can be declared explicitly using the 3383 <ADDRESS_statement> grammar rule. Each such statement can declare one or 3384 more address registers. Vertex program address registers can not be 3385 declared implicitly. 3386 3387 Vertex program address register variables are undefined at each vertex 3388 program invocation. Address registers can be written by the ARL 3389 instruction (section 2.14.5.3), and will be read when a program uses 3390 relative addressing in program parameter arrays. 3391 3392 3393 Section 2.14.3.6, Vertex Program Aliases 3394 3395 Vertex programs can create aliases by matching the <ALIAS_statement> 3396 grammar rule. Aliases allow programs to use multiple variable names to 3397 refer to a single underlying variable. For example, the statement 3398 3399 ALIAS var1 = var0 3400 3401 establishes a variable name named "var1". Subsequent references to "var1" 3402 in the program text are treated as references to "var0". The left hand 3403 side of an ALIAS statement must be a new variable name, and the right hand 3404 side must be an established variable name. 3405 3406 Aliases are not considered variable declarations, so do not count against 3407 the limits on the number of variable declarations allowed in the program 3408 text. 3409 3410 3411 Section 2.14.3.7, Vertex Program Resource Limits 3412 3413 The vertex program execution environment provides implementation-dependent 3414 resource limits on the number of instructions, temporary variable 3415 declarations, vertex attribute bindings, address register declarations, 3416 and program parameter bindings. A program that exceeds any of these 3417 resource limits will fail to load. The resource limits for vertex 3418 programs can be queried by calling GetProgramiv (section 6.1.12) with a 3419 target of VERTEX_PROGRAM_ARB. 3420 3421 The limit on vertex program instructions can be queried with a <pname> of 3422 MAX_PROGRAM_INSTRUCTIONS_ARB, and must be at least 128. Each instruction 3423 in the program (matching the <instruction> grammar rule) counts against 3424 this limit. 3425 3426 The limit on vertex program temporary variable declarations can be queried 3427 with a <pname> of MAX_PROGRAM_TEMPORARIES_ARB, and must be at least 12. 3428 Each temporary declared in the program, using the <TEMP_statement> grammar 3429 rule, counts against this limit. Aliases of declared temporaries do not. 3430 3431 The limit on vertex program attribute bindings can be queried with a 3432 <pname> of MAX_PROGRAM_ATTRIBS_ARB and must be at least 16. Each distinct 3433 vertex attribute bound explicitly or implicitly in the program counts 3434 against this limit; vertex attributes bound multiple times count only 3435 once. 3436 3437 The limit on vertex program address register declarations can be queried 3438 with a <pname> of MAX_PROGRAM_ADDRESS_REGISTERS_ARB, and must be at least 3439 1. Each address register declared in the program, using the 3440 <ADDRESS_statement> grammar rule, counts against this limit. 3441 3442 The limit on vertex program parameter bindings can be queried with a 3443 <pname> of MAX_PROGRAM_PARAMETERS_ARB, and must be at least 96. Each 3444 distinct GL state vector bound explicitly or implicitly in the program 3445 counts against this limit; GL state vectors bound multiple times count 3446 only once. Each constant vector bound to an array accessed using relative 3447 addressing counts against this limit, even if the same constant vector is 3448 bound multiple times or in multiple arrays. Every other constant vector 3449 bound in the program is counted if and only if an identical constant 3450 vector has not already been counted. Two constant vectors are considered 3451 identical if the four component values are numerically equivalent. Recall 3452 that scalar constants bound in a program are treated as vector constants 3453 with the scalar value replicated. In the following code 3454 3455 PARAM arr1[4] = { {1,2,3,4}, {1,2,3,4}, {4,4,4,4}, {5,6,7,8} }; 3456 PARAM arr2[3] = { {1,2,3,4}, {5,6,7,8}, {0,1,2,3} }; 3457 PARAM x = {4,3,2,1}; 3458 PARAM y = {1,2,3,4}; 3459 PARAM z = 4; 3460 PARAM r = {4,3,2,1}; 3461 3462 assume that arr1 is accessed using relative addressing but arr2 is not. 3463 The four constants in arr1 all count against the limit. Only two other 3464 constants, {0,1,2,3} in arr2, and {4,3,2,1} in x, are counted; the other 3465 constants are identical to constants that had been previously counted. 3466 3467 In addition to the limits described above, the GL provides a similar set 3468 of implementation-dependent native resource limits. These limits, 3469 specified in section 6.1.12, provide guidance as to whether the program is 3470 small enough to use a "native" mode where vertex programs may be executed 3471 with higher performance. The native resource limits and usage counts are 3472 implementation-dependent and may not exactly correspond to limits and 3473 counts described above. In particular, native resource consumption may be 3474 reduced by program optimizations performed by the GL, or increased due to 3475 emulation of non-native instructions. Programs that satisfy the program 3476 resource limits described above, but whose native resource usage exceeds 3477 one or more native resource limits, are guaranteed to load but may execute 3478 suboptimally. 3479 3480 To assist in resource counting, the GL additionally provides GetProgram 3481 queries to determine the resource usage and native resource usage of the 3482 currently bound program, and to determine whether the bound program 3483 exceeds any native resource limit. 3484 3485 3486 Section 2.14.4, Vertex Program Execution Environment 3487 3488 If vertex program mode is enabled, the currently bound vertex program is 3489 executed when a vertex is specified directly through the Vertex command, 3490 indirectly through vertex arrays or evaluators (section 5.1), or when the 3491 current raster position is updated. 3492 3493 If vertex program mode is enabled and the currently bound program object 3494 does not contain a valid vertex program, the error INVALID_OPERATION will 3495 be generated by Begin, RasterPos, and any command that implicitly calls 3496 Begin (e.g., DrawArrays). 3497 3498 Vertex programs execute a sequence of instructions without 3499 branching. Vertex programs begin by executing the first instruction in 3500 the program, and execute instructions in the order specified in the 3501 program until the last instruction is completed. 3502 3503 There are twenty-seven vertex program instructions. The instructions and 3504 their respective input and output parameters are summarized in Table X.5. 3505 3506 Instruction Inputs Output Description 3507 ----------- ------ ------ -------------------------------- 3508 ABS v v absolute value 3509 ADD v,v v add 3510 ARL s a address register load 3511 DP3 v,v ssss 3-component dot product 3512 DP4 v,v ssss 4-component dot product 3513 DPH v,v ssss homogeneous dot product 3514 DST v,v v distance vector 3515 EX2 s ssss exponential base 2 3516 EXP s v exponential base 2 (approximate) 3517 FLR v v floor 3518 FRC v v fraction 3519 LG2 s ssss logarithm base 2 3520 LIT v v compute light coefficients 3521 LOG s v logarithm base 2 (approximate) 3522 MAD v,v,v v multiply and add 3523 MAX v,v v maximum 3524 MIN v,v v minimum 3525 MOV v v move 3526 MUL v,v v multiply 3527 POW s,s ssss exponentiate 3528 RCP s ssss reciprocal 3529 RSQ s ssss reciprocal square root 3530 SGE v,v v set on greater than or equal 3531 SLT v,v v set on less than 3532 SUB v,v v subtract 3533 SWZ v v extended swizzle 3534 XPD v,v v cross product 3535 3536 Table X.5: Summary of vertex program instructions. "v" indicates a 3537 floating-point vector input or output, "s" indicates a floating-point 3538 scalar input, "ssss" indicates a scalar output replicated across a 3539 4-component result vector, and "a" indicates a single address register 3540 component. 3541 3542 3543 Section 2.14.4.1, Vertex Program Operands 3544 3545 Most vertex program instructions operate on floating-point vectors or 3546 scalars, as indicated by the grammar rules <swizzleSrcReg> and 3547 <scalarSrcReg>, respectively. 3548 3549 Vector and scalar operands can be obtained from vertex attribute, program 3550 parameter, or temporary registers, as indicated by the <srcReg> rule. For 3551 scalar operands, a single vector component is selected by the 3552 <scalarSuffix> rule, where the characters "x", "y", "z", and "w" select 3553 the x, y, z, and w components, respectively, of the vector. 3554 3555 Vector operands can be swizzled according to the <swizzleSuffix> rule. In 3556 its most general form, the <swizzleSuffix> rule matches the pattern 3557 ".????" where each question mark is replaced with one of "x", "y", "z", or 3558 "w". For such patterns, the x, y, z, and w components of the operand are 3559 taken from the vector components named by the first, second, third, and 3560 fourth character of the pattern, respectively. For example, if the 3561 swizzle suffix is ".yzzx" and the specified source contains {2,8,9,0}, the 3562 swizzled operand used by the instruction is {8,9,9,2}. 3563 3564 If the <swizzleSuffix> rule matches "", it is treated as though it were 3565 ".xyzw". If the <swizzleSuffix> rule matches (ignoring whitespace) ".x", 3566 ".y", ".z", or ".w", these are treated the same as ".xxxx", ".yyyy", 3567 ".zzzz", and ".wwww" respectively. 3568 3569 Floating-point scalar or vector operands can optionally be negated 3570 according to the <optionalSign> rule in <scalarSrcReg> and 3571 <swizzleSrcReg>. If the <optionalSign> matches "-", each operand or 3572 operand component is negated. 3573 3574 The following pseudo-code spells out the operand generation process. In 3575 the example, "float" is a floating-point scalar type, while "floatVec" is 3576 a four-component vector. "source" refers to the register used for the 3577 operand, matching the <srcReg> rule. "negate" is TRUE if the 3578 <optionalSign> rule in <scalarSrcReg> or <swizzleSrcReg> matches "-" and 3579 FALSE otherwise. The ".c***", ".*c**", ".**c*", ".***c" modifiers refer 3580 to the x, y, z, and w components obtained by the swizzle operation; the 3581 ".c" modifier refers to the single component selected for a scalar load. 3582 3583 floatVec VectorLoad(floatVec source) 3584 { 3585 floatVec operand; 3586 3587 operand.x = source.c***; 3588 operand.y = source.*c**; 3589 operand.z = source.**c*; 3590 operand.w = source.***c; 3591 if (negate) { 3592 operand.x = -operand.x; 3593 operand.y = -operand.y; 3594 operand.z = -operand.z; 3595 operand.w = -operand.w; 3596 } 3597 3598 return operand; 3599 } 3600 3601 float ScalarLoad(floatVec source) 3602 { 3603 float operand; 3604 3605 operand = source.c; 3606 if (negate) { 3607 operand = -operand; 3608 } 3609 3610 return operand; 3611 } 3612 3613 Section 2.14.4.2, Vertex Program Parameter Arrays 3614 3615 A vertex program can load a single element of a program parameter array 3616 using either absolute or relative addressing. Program parameter arrays 3617 are accessed when the <progParamArray> rule is matched. 3618 3619 Absolute addressing is used when the <progParamArrayMem> grammar rule 3620 matches <progParamArrayAbs>. When using absolute addressing, the offset 3621 of the selected entry in the array is given by the number matching 3622 <progParamRegNum>. 3623 3624 Relative addressing is used when the <progParamArrayMem> grammar rule 3625 matches <progParamArrayRel>. When using relative addressing, the offset 3626 of the selected entry in the array is computed by adding the address 3627 register component specified by the <addrReg> and <addrComponent> rules to 3628 the positive or negative offset specified by the <addrRegRelOffset> rule. 3629 If <addrRegRelOffset> matches "", no fixed offset is added to the address 3630 register component. If the computed offset is negative or exceeds the 3631 size of the array, the results of the access are undefined, but may not 3632 lead to program or GL termination. 3633 3634 The following pseudo-code spells out the process of loading a program 3635 parameter from an array. "addrReg" refers to the address register 3636 component used for relative addressing, "absolute" is TRUE if the operand 3637 uses absolute addressing and FALSE otherwise. "paramNumber" is the 3638 program parameter number for absolute addressing; "paramOffset" is the 3639 constant program parameter offset for relative addressing. "paramArray" 3640 is the parameter array that matches the <progParamArray> rule. 3641 3642 floatVec ProgramParameterLoad(int addrReg) 3643 { 3644 int index; 3645 3646 if (absolute) { 3647 index = paramNumber; 3648 } else { 3649 index = addrReg + paramOffset 3650 } 3651 3652 return paramArray[index]; 3653 } 3654 3655 Relative addressing can only be used for accessing program parameter 3656 arrays. 3657 3658 3659 Section 2.14.4.3, Vertex Program Destination Register Update 3660 3661 Most vertex program instructions write a 4-component result vector to a 3662 single temporary or vertex result register. Writes to individual 3663 components of the destination register are controlled by individual 3664 component write masks specified as part of the instruction. 3665 3666 The component write mask is specified by the <optionalMask> rule found in 3667 the <maskedDstReg> rule. If the optional mask is "", all components are 3668 enabled. Otherwise, the optional mask names the individual components to 3669 enable. The characters "x", "y", "z", and "w" match the x, y, z, and w 3670 components respectively. For example, an optional mask of ".xzw" 3671 indicates that the x, z, and w components should be enabled for writing 3672 but the y component should not. The grammar requires that the destination 3673 register mask components must be listed in "xyzw" order. 3674 3675 Each component of the destination register is updated with the result of 3676 the vertex program instruction if and only if the component is enabled for 3677 writes by the component write mask. Otherwise, the component of the 3678 destination register remains unchanged. 3679 3680 The following pseudocode illustrates the process of writing a result 3681 vector to the destination register. In the pseudocode, "instrmask" refers 3682 to the component write mask given by the <optionalMask> rule. "result" 3683 and "destination" refer to the result vector and the register selected by 3684 <dstReg>, respectively. 3685 3686 void UpdateDestination(floatVec destination, floatVec result) 3687 { 3688 floatVec merged; 3689 3690 // Merge the converted result into the destination register, under 3691 // control of the compile-time write mask. 3692 merged = destination; 3693 if (instrMask.x) { 3694 merged.x = result.x; 3695 } 3696 if (instrMask.y) { 3697 merged.y = result.y; 3698 } 3699 if (instrMask.z) { 3700 merged.z = result.z; 3701 } 3702 if (instrMask.w) { 3703 merged.w = result.w; 3704 } 3705 3706 // Write out the new destination register. 3707 destination = merged; 3708 } 3709 3710 The "ARL" instruction updates the single address register component 3711 similarly; the grammar is designed so that it writes to only the "x" 3712 component of an address register variable. 3713 3714 3715 Section 2.14.4.4, Vertex Program Result Processing 3716 3717 As a vertex program executes, it will write to one or more result 3718 registers that are mapped to transformed vertex attributes. When a vertex 3719 program completes, the transformed vertex attributes are used to generate 3720 primitives. 3721 3722 The clip coordinates written to "result.position" are used to generate 3723 normalized device coordinates and window coordinates for the vertex in the 3724 manner described section 2.10. 3725 3726 Transformed vertices are then assembled into primitives and clipped as 3727 described in section 2.11. 3728 3729 The selection between front-facing and back-facing color attributes 3730 depends on the primitive to which the vertex belongs. If the primitive is 3731 a point or a line segment, or if vertex program two-sided color mode is 3732 disabled, the front-facing colors are always selected. If it is a polygon 3733 and two-sided color mode is enabled, then the selection is performed in 3734 exactly the same way as in two-sided lighting mode (section 2.13.1). 3735 Vertex program two-sided color mode is enabled and disabled by calling 3736 Enable or Disable with the symbolic value VERTEX_PROGRAM_TWO_SIDE_ARB. 3737 3738 Finally, as primitives are assembled, color clamping (section 2.13.6), 3739 flatshading (section 2.13.7), color, attribute clipping (section 2.13.8), 3740 and final color processing (section 2.13.9) operations are applied to the 3741 transformed vertices. 3742 3743 3744 Section 2.14.4.5, Vertex Program Options 3745 3746 The <optionSequence> grammar rule provides a mechanism for programs to 3747 indicate that one or more extended language features are used by the 3748 program. All program options used by the program must be declared at the 3749 beginning of the program string. Each program option specified in a 3750 program string will modify the syntactic or semantic rules used to 3751 interpet the program and the execution environment used to execute the 3752 program. Program options not present in the program string are ignored, 3753 even if they are supported by the GL. 3754 3755 The <identifier> token in the <option> rule must match the name of a 3756 program option supported by the implementation. To avoid option name 3757 conflicts, option identifiers are required to begin with a vendor prefix. 3758 A program will fail to load if it specifies a program option not supported 3759 by the GL. 3760 3761 Vertex program options should confine their semantic changes to the domain 3762 of vertex programs. Support for a vertex program option should not change 3763 the specification and behavior of vertex programs not requesting use of 3764 that option. 3765 3766 2.14.4.5.1, Position-Invariant Vertex Program Option 3767 3768 If a vertex program specifies the "ARB_position_invariant" option, the 3769 program is used to generate all transformed vertex attributes except for 3770 position. Instead, clip coordinates are computed as specified in section 3771 2.10. Additionally, user clipping is performed as described in section 3772 2.11. Use of position-invariant vertex programs should generally 3773 guarantee that the transformed position of a vertex should be the same 3774 whether vertex program mode is enabled or disabled, allowing for correct 3775 mixed multi-pass rendering semantics. 3776 3777 When the position-invariant option is specified in a vertex program, 3778 vertex programs can no longer produced a transformed position. The 3779 <resultBinding> rule is modified to remove "result.position" from the list 3780 of token sequences matching the rule. A semantic restriction is added to 3781 indicate that a vertex program will fail to load if the number of 3782 instructions it contains exceeds the implementation-dependent limit minus 3783 four. 3784 3785 3786 Section 2.14.5, Vertex Program Instruction Set 3787 3788 The following sections describe the set of supported vertex program 3789 instructions. Each section contains pseudocode describing the 3790 instruction. Instructions will have up to three operands, referred to as 3791 "op0", "op1", and "op2". The operands are loaded using the mechanisms 3792 specified in section 2.14.4.1. The variables "tmp", "tmp0", "tmp1", and 3793 "tmp2" describe scalars or vectors used to hold intermediate results in 3794 the instruction. Most instructions will generate a result vector called 3795 "result". The result vector is then written to the destination register 3796 specified in the instruction as described in section 2.14.4.3. 3797 3798 3799 Section 2.14.5.1, ABS: Absolute Value 3800 3801 The ABS instruction performs a component-wise absolute value operation on 3802 the single operand to yield a result vector. 3803 3804 tmp = VectorLoad(op0); 3805 result.x = fabs(tmp.x); 3806 result.y = fabs(tmp.y); 3807 result.z = fabs(tmp.z); 3808 result.w = fabs(tmp.w); 3809 3810 3811 Section 2.14.5.2, ADD: Add 3812 3813 The ADD instruction performs a component-wise add of the two operands to 3814 yield a result vector. 3815 3816 tmp0 = VectorLoad(op0); 3817 tmp1 = VectorLoad(op1); 3818 result.x = tmp0.x + tmp1.x; 3819 result.y = tmp0.y + tmp1.y; 3820 result.z = tmp0.z + tmp1.z; 3821 result.w = tmp0.w + tmp1.w; 3822 3823 The following rules apply to addition: 3824 3825 1. <x> + <y> == <y> + <x>, for all <x> and <y>. 3826 2. <x> + 0.0 == <x>, for all <x>. 3827 3828 3829 Section 2.14.5.3, ARL: Address Register Load 3830 3831 The ARL instruction loads a single scalar operand and performs a floor 3832 operation to generate a signed integer scalar result: 3833 3834 result = floor(ScalarLoad(op0)); 3835 3836 The floor operation returns the largest integer less than or equal to the 3837 operand. For example floor(-1.7) = -2.0, floor(+1.0) = +1.0, and 3838 floor(+3.7) = +3.0. 3839 3840 3841 Section 2.14.5.4, DP3: Three-Component Dot Product 3842 3843 The DP3 instruction computes a three-component dot product of the two 3844 operands (using the x, y, and z components) and replicates the dot product 3845 to all four components of the result vector. 3846 3847 tmp0 = VectorLoad(op0); 3848 tmp1 = VectorLoad(op1); 3849 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + 3850 (tmp0.z * tmp1.z); 3851 result.x = dot; 3852 result.y = dot; 3853 result.z = dot; 3854 result.w = dot; 3855 3856 3857 Section 2.14.5.5, DP4: Four-Component Dot Product 3858 3859 The DP4 instruction computes a four-component dot product of the two 3860 operands and replicates the dot product to all four components of the 3861 result vector. 3862 3863 tmp0 = VectorLoad(op0); 3864 tmp1 = VectorLoad(op1): 3865 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + 3866 (tmp0.z * tmp1.z) + (tmp0.w * tmp1.w); 3867 result.x = dot; 3868 result.y = dot; 3869 result.z = dot; 3870 result.w = dot; 3871 3872 3873 Section 2.14.5.6, DPH: Homogeneous Dot Product 3874 3875 The DPH instruction computes a three-component dot product of the two 3876 operands (using the x, y, and z components), adds the w component of the 3877 second operand, and replicates the sum to all four components of the 3878 result vector. This is equivalent to a four-component dot product where 3879 the w component of the first operand is forced to 1.0. 3880 3881 tmp0 = VectorLoad(op0); 3882 tmp1 = VectorLoad(op1): 3883 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + 3884 (tmp0.z * tmp1.z) + tmp1.w; 3885 result.x = dot; 3886 result.y = dot; 3887 result.z = dot; 3888 result.w = dot; 3889 3890 3891 Section 2.14.5.7, DST: Distance Vector 3892 3893 The DST instruction computes a distance vector from two specially- 3894 formatted operands. The first operand should be of the form [NA, d^2, 3895 d^2, NA] and the second operand should be of the form [NA, 1/d, NA, 1/d], 3896 where NA values are not relevant to the calculation and d is a vector 3897 length. If both vectors satisfy these conditions, the result vector will 3898 be of the form [1.0, d, d^2, 1/d]. 3899 3900 The exact behavior is specified in the following pseudo-code: 3901 3902 tmp0 = VectorLoad(op0); 3903 tmp1 = VectorLoad(op1); 3904 result.x = 1.0; 3905 result.y = tmp0.y * tmp1.y; 3906 result.z = tmp0.z; 3907 result.w = tmp1.w; 3908 3909 Given an arbitrary vector, d^2 can be obtained using the DP3 instruction 3910 (using the same vector for both operands) and 1/d can be obtained from d^2 3911 using the RSQ instruction. 3912 3913 This distance vector is useful for per-vertex light attenuation 3914 calculations: a DP3 operation using the distance vector and an 3915 attenuation constants vector as operands will yield the attenuation 3916 factor. 3917 3918 3919 Section 2.14.5.8, EX2: Exponential Base 2 3920 3921 The EX2 instruction approximates 2 raised to the power of the scalar 3922 operand and replicates the approximation to all four components of the 3923 result vector. 3924 3925 tmp = ScalarLoad(op0); 3926 result.x = Approx2ToX(tmp); 3927 result.y = Approx2ToX(tmp); 3928 result.z = Approx2ToX(tmp); 3929 result.w = Approx2ToX(tmp); 3930 3931 3932 Section 2.14.5.9, EXP: Exponential Base 2 (approximate) 3933 3934 The EXP instruction computes a rough approximation of 2 raised to the 3935 power of the scalar operand. The approximation is returned in the "z" 3936 component of the result vector. A vertex program can also use the "x" and 3937 "y" components of the result vector to generate a more accurate 3938 approximation by evaluating 3939 3940 result.x * f(result.y), 3941 3942 where f(x) is a user-defined function that approximates 2^x over the 3943 domain [0.0, 1.0). The "w" component of the result vector is always 1.0. 3944 3945 The exact behavior is specified in the following pseudo-code: 3946 3947 tmp = ScalarLoad(op0); 3948 result.x = 2^floor(tmp); 3949 result.y = tmp - floor(tmp); 3950 result.z = RoughApprox2ToX(tmp); 3951 result.w = 1.0; 3952 3953 The approximation function is accurate to at least 10 bits: 3954 3955 | RoughApprox2ToX(x) - 2^x | < 1.0 / 2^11, if 0.0 <= x < 1.0, 3956 3957 and, in general, 3958 3959 | RoughApprox2ToX(x) - 2^x | < (1.0 / 2^11) * (2^floor(x)). 3960 3961 3962 Section 2.14.5.10, FLR: Floor 3963 3964 The FLR instruction performs a component-wise floor operation on the 3965 operand to generate a result vector. The floor of a value is defined as 3966 the largest integer less than or equal to the value. The floor of 2.3 is 3967 2.0; the floor of -3.6 is -4.0. 3968 3969 tmp = VectorLoad(op0); 3970 result.x = floor(tmp.x); 3971 result.y = floor(tmp.y); 3972 result.z = floor(tmp.z); 3973 result.w = floor(tmp.w); 3974 3975 3976 Section 2.14.5.11, FRC: Fraction 3977 3978 The FRC instruction extracts the fractional portion of each component of 3979 the operand to generate a result vector. The fractional portion of a 3980 component is defined as the result after subtracting off the floor of the 3981 component (see FLR), and is always in the range [0.0, 1.0). 3982 3983 For negative values, the fractional portion is NOT the number written to 3984 the right of the decimal point -- the fractional portion of -1.7 is not 3985 0.7 -- it is 0.3. 0.3 is produced by subtracting the floor of -1.7 (-2.0) 3986 from -1.7. 3987 3988 tmp = VectorLoad(op0); 3989 result.x = fraction(tmp.x); 3990 result.y = fraction(tmp.y); 3991 result.z = fraction(tmp.z); 3992 result.w = fraction(tmp.w); 3993 3994 3995 Section 2.14.5.12, LG2: Logarithm Base 2 3996 3997 The LG2 instruction approximates the base 2 logarithm of the scalar 3998 operand and replicates it to all four components of the result vector. 3999 4000 tmp = ScalarLoad(op0); 4001 result.x = ApproxLog2(tmp); 4002 result.y = ApproxLog2(tmp); 4003 result.z = ApproxLog2(tmp); 4004 result.w = ApproxLog2(tmp); 4005 4006 If the scalar operand is zero or negative, the result is undefined. 4007 4008 4009 Section 2.14.5.13, LIT: Light Coefficients 4010 4011 The LIT instruction accelerates per-vertex lighting by computing lighting 4012 coefficients for ambient, diffuse, and specular light contributions. The 4013 "x" component of the single operand is assumed to hold a diffuse dot 4014 product (n dot VP_pli, as in the vertex lighting equations in Section 4015 2.13.1). The "y" component of the operand is assumed to hold a specular 4016 dot product (n dot h_i). The "w" component of the operand is assumed to 4017 hold the specular exponent of the material (s_rm), and is clamped to the 4018 range (-128, +128) exclusive. 4019 4020 The "x" component of the result vector receives the value that should be 4021 multiplied by the ambient light/material product (always 1.0). The "y" 4022 component of the result vector receives the value that should be 4023 multiplied by the diffuse light/material product (n dot VP_pli). The "z" 4024 component of the result vector receives the value that should be 4025 multiplied by the specular light/material product (f_i * (n dot h_i) ^ 4026 s_rm). The "w" component of the result is the constant 1.0. 4027 4028 Negative diffuse and specular dot products are clamped to 0.0, as is done 4029 in the standard per-vertex lighting operations. In addition, if the 4030 diffuse dot product is zero or negative, the specular coefficient is 4031 forced to zero. 4032 4033 tmp = VectorLoad(op0); 4034 if (tmp.x < 0) tmp.x = 0; 4035 if (tmp.y < 0) tmp.y = 0; 4036 if (tmp.w < -(128.0-epsilon)) tmp.w = -(128.0-epsilon); 4037 else if (tmp.w > 128-epsilon) tmp.w = 128-epsilon; 4038 result.x = 1.0; 4039 result.y = tmp.x; 4040 result.z = (tmp.x > 0) ? RoughApproxPower(tmp.y, tmp.w) : 0.0; 4041 result.w = 1.0; 4042 4043 The exponentiation approximation function may be defined in terms of the 4044 base 2 exponentiation and logarithm approximation operations in the EXP 4045 and LOG instructions, where 4046 4047 RoughApproxPower(a,b) = RoughApproxExp2(b * RoughApproxLog2(a)). 4048 4049 In particular, the approximation may not be any more accurate than the 4050 underlying EXP and LOG operations. 4051 4052 Also, since 0^0 is defined to be 1, RoughApproxPower(0.0, 0.0) will 4053 produce 1.0. 4054 4055 4056 Section 2.14.5.14, LOG: Logarithm Base 2 (approximate) 4057 4058 The LOG instruction computes a rough approximation of the base 2 logarithm 4059 of the absolute value of the scalar operand. The approximation is 4060 returned in the "z" component of the result vector. A vertex program can 4061 also use the "x" and "y" components of the result vector to generate a 4062 more accurate approximation by evaluating 4063 4064 result.x + f(result.y), 4065 4066 where f(x) is a user-defined function that approximates 2^x over the 4067 domain [1.0, 2.0). The "w" component of the result vector is always 1.0. 4068 4069 The exact behavior is specified in the following pseudo-code: 4070 4071 tmp = fabs(ScalarLoad(op0)); 4072 result.x = floor(log2(tmp)); 4073 result.y = tmp / 2^(floor(log2(tmp))); 4074 result.z = RoughApproxLog2(tmp); 4075 result.w = 1.0; 4076 4077 Here, "floor(log2(tmp))" refers to the floor of the exact logarithm, which 4078 can be easily computed for standard floating-point representations. The 4079 approximation function is accurate to at least 10 bits: 4080 4081 | RoughApproxLog2(x) - log_2(x) | < 1.0 / 2^11. 4082 4083 4084 Section 2.14.5.15, MAD: Multiply and Add 4085 4086 The MAD instruction performs a component-wise multiply of the first two 4087 operands, and then does a component-wise add of the product to the third 4088 operand to yield a result vector. 4089 4090 tmp0 = VectorLoad(op0); 4091 tmp1 = VectorLoad(op1); 4092 tmp2 = VectorLoad(op2); 4093 result.x = tmp0.x * tmp1.x + tmp2.x; 4094 result.y = tmp0.y * tmp1.y + tmp2.y; 4095 result.z = tmp0.z * tmp1.z + tmp2.z; 4096 result.w = tmp0.w * tmp1.w + tmp2.w; 4097 4098 The multiplication and addition operations in this instruction are subject 4099 to the same rules as described for the MUL and ADD instructions. 4100 4101 4102 Section 2.14.5.16, MAX: Maximum 4103 4104 The MAX instruction computes component-wise maximums of the values in the 4105 two operands to yield a result vector. 4106 4107 tmp0 = VectorLoad(op0); 4108 tmp1 = VectorLoad(op1); 4109 result.x = (tmp0.x > tmp1.x) ? tmp0.x : tmp1.x; 4110 result.y = (tmp0.y > tmp1.y) ? tmp0.y : tmp1.y; 4111 result.z = (tmp0.z > tmp1.z) ? tmp0.z : tmp1.z; 4112 result.w = (tmp0.w > tmp1.w) ? tmp0.w : tmp1.w; 4113 4114 4115 Section 2.14.5.17, MIN: Minimum 4116 4117 The MIN instruction computes component-wise minimums of the values in the 4118 two operands to yield a result vector. 4119 4120 tmp0 = VectorLoad(op0); 4121 tmp1 = VectorLoad(op1); 4122 result.x = (tmp0.x > tmp1.x) ? tmp1.x : tmp0.x; 4123 result.y = (tmp0.y > tmp1.y) ? tmp1.y : tmp0.y; 4124 result.z = (tmp0.z > tmp1.z) ? tmp1.z : tmp0.z; 4125 result.w = (tmp0.w > tmp1.w) ? tmp1.w : tmp0.w; 4126 4127 4128 Section 2.14.5.18, MOV: Move 4129 4130 The MOV instruction copies the value of the operand to yield a result 4131 vector. 4132 4133 result = VectorLoad(op0); 4134 4135 4136 Section 2.14.5.19, MUL: Multiply 4137 4138 The MUL instruction performs a component-wise multiply of the two operands 4139 to yield a result vector. 4140 4141 tmp0 = VectorLoad(op0); 4142 tmp1 = VectorLoad(op1); 4143 result.x = tmp0.x * tmp1.x; 4144 result.y = tmp0.y * tmp1.y; 4145 result.z = tmp0.z * tmp1.z; 4146 result.w = tmp0.w * tmp1.w; 4147 4148 The following rules apply to multiplication: 4149 4150 1. <x> * <y> == <y> * <x>, for all <x> and <y>. 4151 2. +/-0.0 * <x> = +/-0.0, at least for all <x> that correspond to 4152 representable numbers (IEEE "not a number" and "infinity" encodings 4153 may be exceptions). 4154 3. +1.0 * <x> = <x>, for all <x>. 4155 4156 Multiplication by zero and one should be invariant, as it may be used to 4157 evaluate conditional expressions without branching. 4158 4159 4160 Section 2.14.5.20, POW: Exponentiate 4161 4162 The POW instruction approximates the value of the first scalar operand 4163 raised to the power of the second scalar operand and replicates it to all 4164 four components of the result vector. 4165 4166 tmp0 = ScalarLoad(op0); 4167 tmp1 = ScalarLoad(op1); 4168 result.x = ApproxPower(tmp0, tmp1); 4169 result.y = ApproxPower(tmp0, tmp1); 4170 result.z = ApproxPower(tmp0, tmp1); 4171 result.w = ApproxPower(tmp0, tmp1); 4172 4173 The exponentiation approximation function may be implemented using the 4174 base 2 exponentiation and logarithm approximation operations in the EX2 4175 and LG2 instructions. In particular, 4176 4177 ApproxPower(a,b) = ApproxExp2(b * ApproxLog2(a)). 4178 4179 Note that a logarithm may be involved even for cases where the exponent is 4180 an integer. This means that it may not be possible to exponentiate 4181 correctly with a negative base. In constrast, it is possible in a 4182 "normal" mathematical formulation to raise negative numbers to integral 4183 powers (e.g., (-3)^2== 9, and (-0.5)^-2==4). 4184 4185 4186 Section 2.14.5.21, RCP: Reciprocal 4187 4188 The RCP instruction approximates the reciprocal of the scalar operand and 4189 replicates it to all four components of the result vector. 4190 4191 tmp = ScalarLoad(op0); 4192 result.x = ApproxReciprocal(tmp); 4193 result.y = ApproxReciprocal(tmp); 4194 result.z = ApproxReciprocal(tmp); 4195 result.w = ApproxReciprocal(tmp); 4196 4197 The following rule applies to reciprocation: 4198 4199 1. ApproxReciprocal(+1.0) = +1.0. 4200 4201 4202 Section 2.14.5.22, RSQ: Reciprocal Square Root 4203 4204 The RSQ instruction approximates the reciprocal of the square root of the 4205 absolute value of the scalar operand and replicates it to all four 4206 components of the result vector. 4207 4208 tmp = fabs(ScalarLoad(op0)); 4209 result.x = ApproxRSQRT(tmp); 4210 result.y = ApproxRSQRT(tmp); 4211 result.z = ApproxRSQRT(tmp); 4212 result.w = ApproxRSQRT(tmp); 4213 4214 4215 Section 2.14.5.23, SGE: Set On Greater or Equal Than 4216 4217 The SGE instruction performs a component-wise comparison of the two 4218 operands. Each component of the result vector is 1.0 if the corresponding 4219 component of the first operands is greater than or equal that of the 4220 second, and 0.0 otherwise. 4221 4222 tmp0 = VectorLoad(op0); 4223 tmp1 = VectorLoad(op1); 4224 result.x = (tmp0.x >= tmp1.x) ? 1.0 : 0.0; 4225 result.y = (tmp0.y >= tmp1.y) ? 1.0 : 0.0; 4226 result.z = (tmp0.z >= tmp1.z) ? 1.0 : 0.0; 4227 result.w = (tmp0.w >= tmp1.w) ? 1.0 : 0.0; 4228 4229 4230 Section 2.14.5.24, SLT: Set On Less Than 4231 4232 The SLT instruction performs a component-wise comparison of the two 4233 operands. Each component of the result vector is 1.0 if the corresponding 4234 component of the first operand is less than that of the second, and 0.0 4235 otherwise. 4236 4237 tmp0 = VectorLoad(op0); 4238 tmp1 = VectorLoad(op1); 4239 result.x = (tmp0.x < tmp1.x) ? 1.0 : 0.0; 4240 result.y = (tmp0.y < tmp1.y) ? 1.0 : 0.0; 4241 result.z = (tmp0.z < tmp1.z) ? 1.0 : 0.0; 4242 result.w = (tmp0.w < tmp1.w) ? 1.0 : 0.0; 4243 4244 4245 Section 2.14.5.25, SUB: Subtract 4246 4247 The SUB instruction performs a component-wise subtraction of the second 4248 operand from the first to yield a result vector. 4249 4250 tmp0 = VectorLoad(op0); 4251 tmp1 = VectorLoad(op1); 4252 result.x = tmp0.x - tmp1.x; 4253 result.y = tmp0.y - tmp1.y; 4254 result.z = tmp0.z - tmp1.z; 4255 result.w = tmp0.w - tmp1.w; 4256 4257 4258 Section 2.14.5.26, SWZ: Extended Swizzle 4259 4260 The SWZ instruction loads the single vector operand, and performs a 4261 swizzle operation more powerful than that provided for loading normal 4262 vector operands to yield an instruction vector. 4263 4264 After the operand is loaded, the "x", "y", "z", and "w" components of the 4265 result vector are selected by the first, second, third, and fourth matches 4266 of the <extSwizComp> pattern in the <extendedSwizzle> rule. 4267 4268 A result component can be selected from any of the four components of the 4269 operand or the constants 0.0 and 1.0. The result component can also be 4270 optionally negated. The following pseudocode describes the component 4271 selection method. "operand" refers to the vector operand, "select" is an 4272 enumerant where the values ZERO, ONE, X, Y, Z, and W correspond to the 4273 <extSwizSel> rule matching "0", "1", "x", "y", "z", and "w", respectively. 4274 "negate" is TRUE if and only if the <optionalSign> rule in <extSwizComp> 4275 matches "-". 4276 4277 float ExtSwizComponent(floatVec operand, enum select, boolean negate) 4278 { 4279 float result; 4280 switch (select) { 4281 case ZERO: result = 0.0; break; 4282 case ONE: result = 1.0; break; 4283 case X: result = operand.x; break; 4284 case Y: result = operand.y; break; 4285 case Z: result = operand.z; break; 4286 case W: result = operand.w; break; 4287 } 4288 if (negate) { 4289 result = -result; 4290 } 4291 return result; 4292 } 4293 4294 The entire extended swizzle operation is then defined using the following 4295 pseudocode: 4296 4297 tmp = VectorLoad(op0); 4298 result.x = ExtSwizComponent(tmp, xSelect, xNegate); 4299 result.y = ExtSwizComponent(tmp, ySelect, yNegate); 4300 result.z = ExtSwizComponent(tmp, zSelect, zNegate); 4301 result.w = ExtSwizComponent(tmp, wSelect, wNegate); 4302 4303 "xSelect", "xNegate", "ySelect", "yNegate", "zSelect", "zNegate", 4304 "wSelect", and "wNegate" correspond to the "select" and "negate" values 4305 above for the four <extSwizComp> matches. 4306 4307 Since this instruction allows for component selection and negation for 4308 each individual component, the grammar does not allow the use of the 4309 normal swizzle and negation operations allowed for vector operands in 4310 other instructions. 4311 4312 4313 Section 2.14.5.27, XPD: Cross Product 4314 4315 The XPD instruction computes the cross product using the first three 4316 components of its two vector operands to generate the x, y, and z 4317 components of the result vector. The w component of the result vector is 4318 undefined. 4319 4320 tmp0 = VectorLoad(op0); 4321 tmp1 = VectorLoad(op1); 4322 result.x = tmp0.y * tmp1.z - tmp0.z * tmp1.y; 4323 result.y = tmp0.z * tmp1.x - tmp0.x * tmp1.z; 4324 result.z = tmp0.x * tmp1.y - tmp0.y * tmp1.x; 4325 4326 4327 Section 2.14.6, Program Matrices 4328 4329 In addition to GL's conventional matrices, several additional program 4330 matrices are available for use as program parameters. These matrices have 4331 names of the form MATRIX<i>_ARB where <i> is between zero and <n>-1 where 4332 <n> is the value of the implementation-dependent constant 4333 MAX_PROGRAM_MATRICES_ARB. The MATRIX<i>_ARB constants obey MATRIX<i>_ARB 4334 = MATRIX0_ARB + <i>. The value of MAX_PROGRAM_MATRICES_ARB must be at 4335 least eight. The maximum stack depth for program matrices is defined by 4336 the MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB and must be at least 1. 4337 4338 4339 Section 2.14.7 Required Vertex Program State 4340 4341 The state required to support program objects of all targets consists of: 4342 4343 an integer for the program error position, initially -1; 4344 4345 an array of ubytes for the program error string, initially empty; 4346 4347 and the state that must be maintained to indicate which integers are 4348 currently in use as program object names. 4349 4350 The state required to support the vertex program target consists of: 4351 4352 a bit indicating whether or not program mode is enabled, initially 4353 disabled; 4354 4355 a bit indicating whether or not vertex program two-sided color mode is 4356 enabled, initially disabled; 4357 4358 a bit indicating whether or not vertex program point size mode is 4359 enabled, initially disabled; 4360 4361 a set of MAX_PROGRAM_ENV_PARAMETERS_ARB four-component floating-point 4362 program environment parameters, initially set to (0,0,0,0); 4363 4364 and an unsigned integer naming the currently bound vertex program, 4365 initially zero. 4366 4367 The state required for each vertex program object consists of: 4368 4369 an unsigned integer indicating the program object name; 4370 4371 an array of type ubyte containing the program string, initially empty; 4372 4373 an unsigned integer holding the length of the program string, initially 4374 zero; 4375 4376 an enum indicating the program string format, initially 4377 PROGRAM_FORMAT_ASCII_ARB; 4378 4379 five unsigned integers holding the number of instruction, temporary 4380 variable, vertex attribute binding, address register, and program 4381 parameter binding resources used by the program, initially all zero; 4382 4383 five unsigned integers holding the number of native instruction, 4384 temporary variable, vertex attribute binding, address register, and 4385 program parameter binding resources used by the program, initially all 4386 zero; 4387 4388 and a set of MAX_PROGRAM_LOCAL_PARAMETERS_ARB four-component 4389 floating-point program local parameters, initially set to (0,0,0,0). 4390 4391 Initially, no vertex program objects exist. 4392 4393 4394Additions to Chapter 3 of the OpenGL 1.3 Specification (Rasterization) 4395 4396 Modify Section 3.3, Points (p. 63) 4397 4398 (replace the first paragraph) When vertex program mode and vertex progam 4399 point size mode are both enabled, the point size used for point 4400 rasterization is taken from the transformed vertex's point size attribute. 4401 Otherwise, it is controlled with 4402 4403 void PointSize(float size); 4404 4405 size specifies the width or diameter of a point. The initial point size 4406 value is 1.0. A value less than or equal to zero results in the error 4407 INVALID_VALUE. 4408 4409 Vertex program point size mode is enabled and disabled by calling Enable 4410 or Disable with the symbolic value VERTEX_PROGRAM_POINT_SIZE_ARB. 4411 4412 4413 Modify Section 3.9, Color Sum (p. 154) 4414 4415 After texturing, a fragment has two RGBA colors: a primary color c_pri 4416 (which texturing, if enabled, may have modified) and a secondary color 4417 c_sec. If color sum is enabled, the R, G, and B components of these two 4418 colors are summed, and with the A component of the primary color produce a 4419 single post-texturing RGBA color c. The components of c are then clamped 4420 to the range [0,1]. If color sum is disabled, then c_pri is assigned to 4421 the post-texturing color. 4422 4423 Color sum is enabled or disabled using the generic Enable and Disable 4424 commands, respectively, with the symbolic constant COLOR_SUM_ARB. If 4425 vertex program mode is disabled and lighting is enabled, the color sum 4426 stage is always applied, ignoring the value of COLOR_SUM_ARB. 4427 4428 The state required is a single bit indicating whether color sum is enabled 4429 or disabled. In the initial state, color sum is disabled. 4430 4431 4432 Modify Section 3.10, Fog (p. 154) 4433 4434 (modify second paragraph) This factor f may be computed according to one 4435 of three equations: 4436 4437 f = exp(-d*c), (3.24) 4438 f = exp(-(d*c)^2), or (3.25) 4439 f = (e-c)/(e-s) (3.26) 4440 4441 If vertex program mode is enabled or if the fog source (as defined below) 4442 is FOG_COORDINATE_EXT, then c is the fragment's fog coordinate. 4443 Otherwise, the c is the eye-coordinate distance from the eye, (0,0,0,1) in 4444 eye-coordinates, to the fragment center. ... 4445 4446Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment 4447Operations and the Framebuffer) 4448 4449 None 4450 4451Additions to Chapter 5 of the OpenGL 1.3 Specification (Special Functions) 4452 4453 Modify Section 5.1, Evaluators (p. 181) 4454 4455 (modify next-to-last paragraph, p. 184) For MAP VERTEX 3, let q = p. For 4456 MAP VERTEX 4, let q=(x/w,y/w,z/w), where (x; y; z;w) = p. Then let 4457 4458 dq dq 4459 m = -- x --. 4460 du dv 4461 4462 The the generated analytic normal, n, is given by n=m if vertex program 4463 mode is enabled or by n=m/|m| if vertex program mode is disabled. 4464 4465 4466 Modify Section 5.4, Display Lists (p. 191) 4467 4468 (modify third paragraph, p. 195) ... These are IsList, GenLists, ..., 4469 IsProgramARB, GenProgramsARB, DeleteProgramsARB, and 4470 VertexAttribPointerARB, EnableVertexAttribArrayARB, 4471 DisableVertexAttribArrayARB, as well as IsEnabled and all the Get commands 4472 (chapter 6). 4473 4474 4475Additions to Chapter 6 of the OpenGL 1.3 Specification (State and State 4476Requests) 4477 4478 Modify Section 6.1.2, Data Conversions (p. 198) 4479 4480 (add before last paragraph, p. 198) The matrix selected by the current 4481 matrix mode can be queried by calling GetBooleanv, GetIntegerv, GetFloatv, 4482 and GetDoublev with <pname> set to CURRENT_MATRIX_ARB; the matrix will be 4483 returned in transposed form with <pname> set to 4484 TRANSPOSE_CURRENT_MATRIX_ARB. The depth of the selected matrix stack can 4485 be queried with <pname> set to CURRENT_MATRIX_STACK_DEPTH_ARB. Querying 4486 CURRENT_MATRIX_ARB and CURRENT_MATRIX_STACK_DEPTH_ARB is the only means 4487 for querying the matrix and matrix stack depth of the program matrices 4488 described in section 2.14.6. 4489 4490 4491 Modify Section 6.1.11, Pointer and String Queries (p. 206) 4492 4493 (modify last paragraph, p. 206) ... The possible values for <name> are 4494 VENDOR, RENDERER, VERSION, EXTENSIONS, and PROGRAM_ERROR_STRING_ARB. 4495 4496 (add after last paragraph of section, p. 207) Queries of 4497 PROGRAM_ERROR_STRING_ARB return a pointer to an implementation-dependent 4498 program load error string. If the last call to ProgramStringARB failed to 4499 load a program, the returned string describes at least one reason why the 4500 program failed to load. If the last call to ProgramStringARB successfully 4501 loaded a program, the returned string may be empty (containing only a zero 4502 terminator) or may contain one or more implementation-dependent warning 4503 messages. The contents of the error string are guaranteed to remain 4504 constant only until the next ProgramStringARB command, which may overwrite 4505 the error string. 4506 4507 4508 Insert a new Section 6.1.12, Program Queries (p. 207), between existing 4509 sections 6.1.11 and 6.1.12. 4510 4511 Section 6.1.12, Program Queries 4512 4513 The commands 4514 4515 void GetProgramEnvParameterdvARB(enum target, uint index, 4516 double *params); 4517 void GetProgramEnvParameterfvARB(enum target, uint index, 4518 float *params); 4519 4520 obtain the current value for the program environment parameter numbered 4521 <index> for the given program target <target>, and places the information 4522 in the array <params>. The error INVALID_ENUM is generated if <target> 4523 specifies a nonexistent program target or a program target that does not 4524 support program environment parameters. The error INVALID_VALUE is 4525 generated if <index> is greater than or equal to the 4526 implementation-dependent number of supported program environment 4527 parameters for the program target. 4528 4529 When <target> is VERTEX_PROGRAM_ARB, each program parameter returned is an 4530 array of four values. 4531 4532 The commands 4533 4534 void GetProgramLocalParameterdvARB(enum target, uint index, 4535 double *params); 4536 void GetProgramLocalParameterfvARB(enum target, uint index, 4537 float *params); 4538 4539 obtain the current value for the program local parameter numbered <index> 4540 belonging to the program object currently bound to <target>, and places 4541 the information in the array <params>. The error INVALID_ENUM is 4542 generated if <target> specifies a nonexistent program target or a program 4543 target that does not support program local parameters. The error 4544 INVALID_VALUE is generated if <index> is greater than or equal to the 4545 implementation-dependent number of supported program local parameters for 4546 the program target. 4547 4548 When the program target type is VERTEX_PROGRAM_ARB, each program 4549 local parameter returned is an array of four values. 4550 4551 The command 4552 4553 void GetProgramivARB(enum target, enum pname, int *params); 4554 4555 obtains program state for the program target <target>, writing the state 4556 into the array given by <params>. GetProgramivARB can be used to 4557 determine the properties of the currently bound program object or 4558 implementation limits for <target>. 4559 4560 If <pname> is PROGRAM_LENGTH_ARB, PROGRAM_FORMAT_ARB, or 4561 PROGRAM_BINDING_ARB, GetProgramivARB returns one integer holding the 4562 program string length (in bytes), program string format, and program name, 4563 respectively, for the program object currently bound to <target>. 4564 4565 If <pname> is MAX_PROGRAM_LOCAL_PARAMETERS_ARB or 4566 MAX_PROGRAM_ENV_PARAMETERS_ARB, GetProgramivARB returns one integer 4567 holding the maximum number of program local parameters or program 4568 environment parameters, respectively, supported for the program target 4569 <target>. 4570 4571 If <pname> is MAX_PROGRAM_INSTRUCTIONS_ARB, MAX_PROGRAM_TEMPORARIES_ARB, 4572 MAX_PROGRAM_PARAMETERS_ARB, MAX_PROGRAM_ATTRIBS_ARB, or 4573 MAX_PROGRAM_ADDRESS_REGISTERS_ARB, GetProgramivARB returns a single 4574 integer giving the maximum number of instructions, temporaries, 4575 parameters, attributes, and address registers that can be used by a 4576 program of type <target>. If <pname> is PROGRAM_INSTRUCTIONS_ARB, 4577 PROGRAM_TEMPORARIES_ARB, PROGRAM_PARAMETERS_ARB, PROGRAM_ATTRIBS_ARB, or 4578 PROGRAM_ADDRESS_REGISTERS_ARB, GetProgramivARB returns a single integer 4579 giving the number of instructions, temporaries, parameters, attributes, 4580 and address registers used by the current program for <target>. 4581 4582 If <pname> is MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB, 4583 MAX_PROGRAM_NATIVE_TEMPORARIES_ARB, MAX_PROGRAM_NATIVE_PARAMETERS_ARB, 4584 MAX_PROGRAM_NATIVE_ATTRIBS_ARB, or 4585 MAX_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB, GetProgramivARB returns a single 4586 integer giving the maximum number of native instruction, temporary, 4587 parameter, attribute, and address register resources available to a 4588 program of type <target>. If <pname> is PROGRAM_NATIVE_INSTRUCTIONS_ARB, 4589 PROGRAM_NATIVE_TEMPORARIES_ARB, PROGRAM_NATIVE_PARAMETERS_ARB, 4590 PROGRAM_NATIVE_ATTRIBS_ARB, or PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB, 4591 GetProgramivARB returns a single integer giving the number of native 4592 instruction, temporary, parameter, attribute, and address register 4593 resources consumed by the program currently bound to <target>. Native 4594 resource counts will reflect the results of implementation-dependent 4595 scheduling and optimization algorithms applied by the GL, as well as 4596 emulation of non-native features. If <pname> is 4597 PROGRAM_UNDER_NATIVE_LIMITS_ARB, GetProgramivARB returns 0 if the native 4598 resource consumption of the program currently bound to <target> exceeds 4599 the number of available resources for any resource type, and 1 otherwise. 4600 4601 The command 4602 4603 void GetProgramStringARB(enum target, enum pname, void *string); 4604 4605 obtains the program string for the program object bound to <target> and 4606 places the information in the array <string>. <pname> must be 4607 PROGRAM_STRING_ARB. <n> ubytes are returned into the array program where 4608 <n> is the length of the program in ubytes, as returned by GetProgramivARB 4609 when <pname> is PROGRAM_LENGTH_ARB. The program string is always returned 4610 using the format given when the program string was specified. 4611 4612 The commands 4613 4614 void GetVertexAttribdvARB(uint index, enum pname, double *params); 4615 void GetVertexAttribfvARB(uint index, enum pname, float *params); 4616 void GetVertexAttribivARB(uint index, enum pname, int *params); 4617 4618 obtain the vertex attribute state named by <pname> for the vertex 4619 attribute numbered <index> and places the information in the array 4620 <params>. <pname> must be one of VERTEX_ATTRIB_ARRAY_ENABLED_ARB, 4621 VERTEX_ATTRIB_ARRAY_SIZE_ARB, VERTEX_ATTRIB_ARRAY_STRIDE_ARB, 4622 VERTEX_ATTRIB_ARRAY_TYPE_ARB, VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB, or 4623 CURRENT_VERTEX_ATTRIB_ARB. Note that all the queries except 4624 CURRENT_VERTEX_ATTRIB_ARB return client state. The error INVALID_VALUE is 4625 generated if <index> is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. 4626 The error INVALID_OPERATION is generated if <index> is zero and <pname> is 4627 CURRENT_VERTEX_ATTRIB_ARB, as there is no current value for vertex 4628 attribute zero. 4629 4630 The command 4631 4632 void GetVertexAttribPointervARB(uint index, enum pname, void **pointer); 4633 4634 obtains the pointer named <pname> for vertex attribute numbered <index> 4635 and places the information in the array <pointer>. <pname> must be 4636 VERTEX_ATTRIB_ARRAY_POINTER_ARB. The INVALID_VALUE error is generated if 4637 <index> is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. 4638 4639 The command 4640 4641 boolean IsProgramARB(uint program); 4642 4643 returns TRUE if <program> is the name of a program object. If <program> 4644 is zero or is a non-zero value that is not the name of a program object, 4645 or if an error condition occurs, IsProgramARB returns FALSE. A name 4646 returned by GenProgramsARB, but not yet bound, is not the name of a 4647 program object. 4648 4649 4650 Concerning Section 6.1.12, Saving and Restoring State (p. 207): 4651 4652 (no actual modifications to the spec) Only the enables, current vertex 4653 attributes, and vertex array state introduced by this extension can be 4654 pushed and popped. See the attribute column in Table X.6 for determining 4655 what vertex program state can be pushed and popped with PushAttrib, 4656 PopAttrib, PushClientAttrib, and PopClientAttrib. 4657 4658 4659Additions to Appendix A of the OpenGL 1.3 Specification (Invariance) 4660 4661 Add to end of Section A.3 (p. 242): 4662 4663 Rule 4. Vertex program instructions not relevant to the calculation of 4664 any result must have no effect on that result. 4665 4666 Rule 5. Vertex program instructions relevant to the calculation of any 4667 result must always produce the identical result. 4668 4669 Instructions relevant to the calculation of a result are any instructions 4670 in a sequence of instructions that eventually determine the source values 4671 for the calculation under consideration. 4672 4673 There is no guaranteed invariance between vertices transformed by 4674 conventional GL vertex transform mode and vertices transformed by vertex 4675 program mode. Multi-pass rendering algorithms that require rendering 4676 invariances to operate correctly should not mix conventional GL vertex 4677 transform mode with vertex program mode for different rendering passes, 4678 except by using the position invariance option (section 2.14.4.5.1) in all 4679 vertex program mode passes. However, such algorithms will operate 4680 correctly if the algorithms limit themselves to a single mode of vertex 4681 transformation. 4682 4683 4684Additions to the AGL/GLX/WGL Specifications 4685 4686 Program objects are shared between AGL/GLX/WGL rendering contexts if 4687 and only if the rendering contexts share display lists. No change 4688 is made to the AGL/GLX/WGL API. 4689 4690 Changes to program objects shared between multiple rendering contexts will 4691 be serialized (i.e., the changes will occur in a specific order). 4692 4693 Changes to a program object made by one rendering context are not 4694 guaranteed to take effect in another rendering context until the other 4695 calls BindProgram to bind the program object. 4696 4697 When a program object is deleted by one rendering context, the object 4698 itself is not destroyed until it is no longer the current program object 4699 in any context. However, the name of the deleted object is removed from 4700 the program object name space, so the next attempt to bind a program using 4701 the same name will create a new program object. Recall that destroying a 4702 program object bound in the current rendering context effectively unbinds 4703 the object being destroyed. 4704 4705 4706Dependencies on EXT_vertex_weighting and ARB_vertex_blend 4707 4708 If EXT_vertex_weighting and ARB_vertex_blend are both not supported, all 4709 discussions of vertex weights should be removed. 4710 4711 In particular, references to vertex weights should be removed from Table 4712 X.1, and the description of ArrayElement in section 2.8. The line 4713 4714 "weight" <vtxOptWeightNum> 4715 4716 should be removed from the <vtxAttribItem> grammar rule, and the grammar 4717 rules <vtxOptWeightNum> and <vtxWeightNum> should be deleted. 4718 "vertex.weight" and "vertex.weight[n]" should be removed from Table X.2. 4719 The discussion of vertex weights in section 2.14.3.1 should be removed. 4720 4721 Additionally, the first line of Table X.3.8 should be modified to read: 4722 4723 Binding Underlying State 4724 ------------------------------------ --------------------------- 4725 state.matrix.modelview modelview matrix 4726 4727 4728Dependencies on ARB_matrix_palette: 4729 4730 If ARB_matrix_palette is not supported, all discussions of per-vertex 4731 matrix indices and the matrix palette should be removed. 4732 4733 In particular, the reference to matrix indices should be removed from the 4734 description of ArrayElement in section 2.8. The line 4735 4736 "matrixindex" "[" <vtxWeightNum> "]" 4737 4738 should be removed from the <vtxAttribItem> grammar rule. The line 4739 4740 "palette" "[" <statePaletteMatNum> "]" 4741 4742 should be removed from the <stateMatrixName> grammar rule, and the 4743 <statePaletteMatNum> grammar rule should be removed entirely. 4744 "vertex.matrixindex[n]" should be removed from Table X.2, and 4745 "state.matrix.palette[n]" should be removed from Table X.3.8. The 4746 discussion of vertex matrix indices in section 2.14.3.1 should be removed. 4747 4748Dependencies on EXT_point_parameters and ARB_point_parameters 4749 4750 The discussion of point size determination in EXT/ARB_point_parameters 4751 should qualified to indicate that this functionality only applies when 4752 vertex program mode is disabled. 4753 4754 If EXT/ARB_point_parameters is not supported, references to point 4755 parameter state should be eliminated. In particular, 4756 4757 "attenuation" 4758 4759 should be eliminated from the <statePointProperty> grammar rule, and the 4760 corresponding entries in Table X.3.7 should be eliminated. 4761 4762 Additionally, references to the minimum and maximum point sizes and the 4763 fade threshold should be removed from Table X.3.7 and the explanatory text 4764 immediately thereafter. The components column of the "state.point.size" 4765 binding in Table X.3.7 should read (s,0,0,1). 4766 4767 Even if EXT/ARB_point_parameters is not supported, the point size result 4768 (result.pointsize) still operates as specified. 4769 4770Dependencies on EXT_fog_coord 4771 4772 If EXT_fog_coord is not supported, references to fog coordinates should be 4773 removed from Table X.1, and the description of ArrayElement in section 4774 2.8. The line "fogcoord" should be removed from the <vtxAttribItem> 4775 grammar rule, and "vertex.fogcoord" should be removed from Table X.2. 4776 Also, the use of FOG_COORDINATE_SOURCE_EXT in section 3.10 should be 4777 removed. 4778 4779 Even if EXT_fog_coord is not supported, the fog coordinate output 4780 (result.fogcoord) still operates as specified. When in vertex program 4781 mode, there are no well-defined eye coordinates that could be used for 4782 fog. This means that the functionality of EXT_fog_coord is required to 4783 implement ARB_vertex_program even if the EXT_fog_coord extension itself is 4784 not supported. 4785 4786Dependencies on EXT_secondary_color 4787 4788 If EXT_secondary_color is not supported, references to secondary color 4789 should be removed from Table X.1, and the description of ArrayElement in 4790 section 2.8. The line "secondary" should be removed from the 4791 <vtxOptColorType> grammar rule, and "vertex.color.secondary" should be 4792 removed from Table X.2. 4793 4794 Even if EXT_secondary_color is not supported, the secondary color results 4795 (result.color.secondary, result.color.front.secondary, 4796 result.color.back.secondary) still operate as specified in program mode, 4797 and when in program mode, the color sum enable behaves exactly as 4798 specified in EXT_secondary_color. These vertex result registers are 4799 required to implement OpenGL 1.2's separate specular mode within a vertex 4800 program. 4801 4802 The color sum enable enumerant from EXT_secondary_color has been brought 4803 over and renamed to COLOR_SUM_ARB. The enumerant value itself is 4804 unchanged from EXT_secondary_color. 4805 4806Dependencies on ARB_transpose_matrix 4807 4808 If ARB_transpose_matrix is not supported, the discussion of 4809 TRANSPOSE_CURRENT_MATRIX_ARB in the edits to section 6.1.2 should be 4810 removed. 4811 4812Interactions with NV_vertex_program 4813 4814 The existing NV_vertex_program extension, if supported, also provides a 4815 similar vertex programming model. This extension is incompatible with 4816 NV_vertex_program in a number of different ways. Mixing the two models in 4817 a single application is possible but not recommended. The interactions 4818 between the extensions are defined below. 4819 4820 Functions, enumerants, and programs defined in NV_vertex_program are 4821 called "NV functions", "NV enumerants", and "NV programs" respectively. 4822 Functions, enumerants, and programs defined in ARB_vertex_program are 4823 called "ARB functions", "ARB enumerants", and "ARB programs" respectively. 4824 4825 The following enumerants are identical in the two extensions: 4826 4827 ARB_vertex_program NV_vertex_program 4828 ------------------------------ ------------------------------ 4829 VERTEX_PROGRAM_ARB VERTEX_PROGRAM_NV 4830 VERTEX_PROGRAM_POINT_SIZE_ARB VERTEX_PROGRAM_POINT_SIZE_NV 4831 VERTEX_PROGRAM_TWO_SIDE_ARB VERTEX_PROGRAM_TWO_SIDE_NV 4832 VERTEX_ATTRIB_ARRAY_SIZE_ARB ATTRIB_ARRAY_SIZE_NV 4833 VERTEX_ATTRIB_ARRAY_STRIDE_ARB ATTRIB_ARRAY_STRIDE_NV 4834 VERTEX_ATTRIB_ARRAY_TYPE_ARB ATTRIB_ARRAY_TYPE_NV 4835 CURRENT_VERTEX_ATTRIB_ARB CURRENT_ATTRIB_NV 4836 VERTEX_ATTRIB_ARRAY_POINTER_ARB ATTRIB_ARRAY_POINTER_NV 4837 PROGRAM_LENGTH_ARB PROGRAM_LENGTH_NV 4838 PROGRAM_STRING_ARB PROGRAM_STRING_NV 4839 PROGRAM_ERROR_POSITION_ARB PROGRAM_ERROR_POSITION_NV 4840 CURRENT_MATRIX_ARB CURRENT_MATRIX_NV 4841 CURRENT_MATRIX_STACK_DEPTH_ARB CURRENT_MATRIX_STACK_DEPTH_NV 4842 MAX_PROGRAM_MATRICES_ARB MAX_TRACK_MATRICES_NV 4843 MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB MAX_TRACK_MATRIX_STACK_DEPTH_NV 4844 4845 The following GL state is identical in the two extensions and can be set 4846 or queried using either NV functions or ARB functions. 4847 4848 - Vertex program mode enable. 4849 4850 - Vertex program point size mode enable. 4851 4852 - Vertex program two sided mode enable. 4853 4854 - Program error position. 4855 4856 - NV_vertex_program "program parameters" and ARB_vertex_program "program 4857 environment parameters". 4858 4859 - Current values of generic vertex attributes. Conventional and generic 4860 vertex attributes will alias according to the NV_vertex_program spec, 4861 which is permissible but optional under ARB_vertex_program. 4862 4863 - NV_vertex_program "tracking matrices" and ARB_vertex_program "program 4864 matrices". The NV and ARB enumerants passed to MatrixMode are 4865 different, however. 4866 4867 - Vertex attribute array sizes, types, strides, and pointers. 4868 4869 - Vertex program object names, targets, formats, program string, program 4870 string lengths, and residency information. The ARB and NV query 4871 functions operate differently. The ARB query function does not allow 4872 queries of target (passed in to the query) and residency information. 4873 The NV query function does not allow queries of program name (passed 4874 in to the query) or format. The format of NV programs is always 4875 PROGRAM_FORMAT_ASCII_ARB. 4876 4877 - Current matrix and current matrix stack depth. 4878 4879 - Implementation-dependent limits on number of tracking/program matrices 4880 and tracking/program matrix stack depth. 4881 4882 - Program object name space. Program objects are created differently in 4883 the NV and ARB specs. Under the NV spec, program objects are created 4884 by calling LoadProgramNV. Under the ARB spec, program objects are 4885 created by calling BindProgramARB with an unused program name. 4886 4887 The following state is provided only by ARB_vertex_program: 4888 4889 - Program error string. Querying the error string after calling 4890 LoadProgramNV produces undefined results. 4891 4892 - Vertex attribute array normalization enables. Setting up vertex 4893 attribute arrays through NV functions will set the normalization 4894 enable appropriately based on the NV spec. 4895 4896 - Vertex program object resource counts and native resource counts. 4897 These values are undefined for NV programs. 4898 4899 - Vertex program local parameters. They can not be used by NV programs. 4900 4901 - Implementation-dependent limits on the number of program environment 4902 parameters, program local parameters, resource counts, and native 4903 resource counts. These limits are baked into the NV spec, except for 4904 native counts, which don't exist. 4905 4906 The following state is provided only by NV_vertex_program: 4907 4908 - TrackMatrix enables and transforms. 4909 4910 - Generic vertex attribute evaluator maps. The NV evaluator 4911 functionality will be supported even for ARB programs. 4912 4913 The following are additional functional differences between 4914 ARB_vertex_program and NV_vertex_program: 4915 4916 - ARB program temporaries, address registers, and result registers are 4917 initially undefined. The corresponding values in NV programs are 4918 initialized to (0,0,0,0), 0, and (0,0,0,1), respectively. ARB 4919 programs running on NV_vertex_program platforms can not rely on 4920 NV_vertex_program initialization behavior for temporaries or address 4921 registers, but result registers will be initialized to (0,0,0,1). In 4922 any event, ARB programs that rely on NV_vertex_program initialization 4923 may not behave properly on other platforms that support 4924 ARB_vertex_program but not NV_vertex_program. 4925 4926 - NV programs use a set of fixed variable and register names, with no 4927 support for user-defined variables. ARB programs provide no support 4928 for fixed variable names; all variables must be declared, explicitly 4929 or implicitly, in the program. 4930 4931 - ARB programs support parameter variables that can be bound to selected 4932 GL state variables, and are updated automatically when the underlying 4933 state changes. NV programs provide no such support; applications must 4934 set program parameters themselves. 4935 4936 - ARB programs allow program constants to be declared in the program 4937 text; NV programs require that constants be loaded into the program 4938 parameter array. 4939 4940 - ARB programs support program local parameters; NV programs do not. 4941 Applications using multiple NV programs must manage the shared program 4942 parameter array appropriately. 4943 4944 - ARB_vertex_program vertex array support provides a normalized flag to 4945 optionally normalize fixed-point array data to the [0,1] or [-1,1] 4946 range. ARB_vertex_program also provides several immediate-mode entry 4947 points with the same support. NV_vertex_program supports normalized 4948 data only for unsigned byte data types, and does not support 4949 non-normalized unsigned bytes. VertexAttrib4ub{v}NV was renamed to 4950 VertexAttrib4Nub{v}ARB to indicate that the 4ub call normalizes its 4951 parameters to a [0,1] range. 4952 4953 - ARB_vertex_blend and ARB_matrix_palette support are documented by the 4954 ARB spec, but not by the NV spec. 4955 4956 - ARB_vertex_program contains an OPTION mechanism for future 4957 extensibility, and a position invariant program option. Both features 4958 are found in NV_vertex_program1_1, but not in NV_vertex_program. 4959 4960 - NV_vertex_program supports a vertex state program target that allows 4961 programs to write to program parameters (VERTEX_STATE_PROGRAM_NV). No 4962 such support exists in ARB_vertex_program. Running a NV state program 4963 will update the program parameter/program environment parameter array, 4964 and such updates can be visible through ARB programs. 4965 4966 - LoadProgramNV entry point was changed to ProgramStringARB to match 4967 OpenGL convention that a verb should not be included in a command name 4968 that merely sets state. 4969 4970 - The formal parameter name for program objects was "id" in 4971 NV_vertex_program; in ARB_vertex_program, this formal name is now 4972 "program" to match how texture object routines name their formal 4973 texture object names "texture". 4974 4975 - NV_vertex_program has language that makes it sound that LoadProgramNV 4976 (ProgramStringARB) only accepts the VERTEX_PROGRAM_NV target and the 4977 start token must be "!!VP1.0". This extension clarifies the language 4978 so that it is clear that other targets and start token types are 4979 permitted. 4980 4981 - NV_vertex_program numeric requirements are not present in the ARB 4982 spec. The ARB spec requires nothing more than the numeric 4983 requirements spelled out in section 2.1.1 (Floating-Point 4984 Computations) in the core specification. 4985 4986 - ARB programs allow single instructions to source multiple distinct 4987 vertex attributes or program parameters. NV programs do not. On 4988 current NV_vertex_program hardware, such instructions may require 4989 additional instructions and temporaries to execute. 4990 4991 - ARB programs support the folowing instructions not supported by NV 4992 "VP1.0" programs: 4993 4994 * ABS: absolute value. Supported on VP1.1 NV programs, but not 4995 on VP1.0 programs. Equivalent to "MAX dst, src, -src". 4996 4997 * EX2: exponential base 2. On VP1.0 and VP1.1 hardware, this 4998 instruction will be emulated using EXP and a number of 4999 additional instructions. 5000 5001 * FLR: floor. On VP1.0 and VP1.1 hardware, this instruction will 5002 be emulated using an EXP and an ADD instruction. 5003 5004 * FRC: fraction. On VP1.0 and VP1.1 hardware, this instruction 5005 will be emulated using an EXP instruction, and possibly a MOV 5006 instruction to replicate the scalar result. 5007 5008 * LG2: logarithm base 2. On VP1.0 and VP1.1 hardware, this 5009 instruction will be emulated using LOG and a number of 5010 additional instructions. 5011 5012 * POW: exponentiation. On VP1.0 and VP1.1 hardware, this 5013 instruction will be emulated using LOG, MUL, and EXP 5014 instructions, and possibly additional instructions to generate a 5015 high-precision result. 5016 5017 * SUB: subtraction. Supported on VP1.1 NV programs, but not on 5018 VP1.0 programs. Equivalent to "ADD dst, src1, -src2". 5019 5020 * SWZ: extended swizzle. On VP1.0 and VP1.1 hardware, this 5021 instruction will be emulated using a single MAD instruction and 5022 a program parameter constant. 5023 5024 * XPD: cross product. On VP1.0 and VP1.1 hardware, this 5025 instruction will be emulated using a MUL and a MAD instruction. 5026 5027 - The COLOR_SUM_EXT enable is ignored when NV programs are executed 5028 (default secondary color outputs are zero) but not when ARB programs 5029 are executed (default secondary color outputs are undefined). The 5030 driver will take care of the color sum operation based on which type 5031 of program is currently bound. 5032 5033 - NV programs are required to write a vertex position; ARB programs are 5034 not. 5035 5036 - There is both an ARB and an NV boolean enable for each generic 5037 array (two booleans per generic array). Each generic array's NV 5038 enable is enabled with EnableClientState(VERTEX_ATTRIB_ARRAYn_NV) 5039 or disabled with DisableClientState(VERTEX_ATTRIB_ARRAYn_NV) 5040 while each generic array's ARB enable is enabled 5041 with EnableVertexAttribArrayARB(n) and disabled with 5042 DisableVertexAttribArrayARB(n). 5043 5044 Enabling (or disabling) an ARB generic array enables (or disables) 5045 BOTH the NV and ARB generic array booleans. 5046 5047 However enabling (or disabling) the NV generic array enable 5048 changes only the NV generic array enable (the ARB enable is 5049 UNchanged). 5050 5051 When an enabled valid current vertex program (whether specified 5052 as an ARB or NV vertex program) is bound, the NV generic array 5053 enables are considered (and the ARB enables are ignored). If a 5054 given NV generic array enable is true, the corresponding generic 5055 array state is applied. However if there is an enabled valid 5056 vertex program and a particular NV generic array is disabled, then 5057 the corresponding conventional aliased array state is applied. 5058 5059 When the current vertex program is disabled or not valid (so 5060 conventional vertex processing is performed), the ARB generic 5061 array enables are considered (and the NV enables are ignored). 5062 If a given ARB generic array enable is true, the corresponding 5063 generic array state is applied. However if the current vertex 5064 program is disabled or NOT valid and a particular ARB generic 5065 array is disabled, then the corresponding conventional aliased 5066 array state is applied. 5067 5068 This behavior means generic vertex arrays can be applied to 5069 conventional vertex processing when the ARB generic vertex array 5070 enable boolean is true. For example, you can send normalized 5071 UNSIGNED_SHORT texture coordinate set arrays as aliased generic 5072 vertex arrays where conventionally UNSIGNED_SHORT texture 5073 coordinate set arrays are unnormalized. 5074 5075 NV_vertex_program interaction Issues: 5076 5077 - Should matrix tracking support extend to ARB program environment 5078 parameters? 5079 5080 5081Interactions with EXT_vertex_shader 5082 5083 The existing EXT_vertex_shader extension, if supported, also provides a 5084 similar vertex programming model. This extension is incompatible with 5085 ARB_vertex_program in a number of different ways. Mixing the two models 5086 in a single application is possible but not recommended. The interactions 5087 between the extensions are defined below. 5088 5089 First, it should be trivially noted that an EXT_vertex_shader "shader" 5090 serves the same purpose as an ARB_vertex_program "program". The two terms 5091 will be used interchangeably throughout this discussion. 5092 5093 The most obvious difference between the two extensions is that the 5094 definition of the vertex program is accomplished in EXT_vertex_shader 5095 through the use of instruction-specifying procedure calls and is 5096 accomplished in ARB_vertex_program by providing a textual string 5097 describing the program. This is mostly a distinction of interface rather 5098 than functionality. 5099 5100 Each extension provides its own distinct set of GL state, entry points, 5101 and enumerants. However, there are several areas of overlap both in 5102 conceptual framework and in programming model that are worth noting for 5103 those familiar with both API's. 5104 5105 1. Resource terminology and types 5106 5107 Both ARB_vertex_program and EXT_vertex_shader offer access to similar 5108 types of resources for use by vertex programs. 5109 5110 The following terms describe roughly equivalent resources in their 5111 respective extensions: 5112 5113 EXT_vertex_shader ARB_vertex_program Note 5114 ----------------- ------------------ ---- 5115 instructions instructions 5116 variants attributes 5117 locals temporaries 5118 local constants parameters bound to inline constants (a) 5119 invariants parameters bound to GL state and (b) 5120 program environment parameters 5121 5122 a. ARB_vertex_program has no intrinsic storage type that corresponds 5123 to EXT_vertex_shader's LOCAL_CONSTANT storage type, but rather 5124 supports program parameters bound to inline constant vectors 5125 specified within the program text. This essentially makes 5126 LOCAL_CONSTANT a special case of an ARB_vertex_program program 5127 parameter. The values of these inline constant parameters can not 5128 be changed without redefining the program itself, just like the 5129 values of EXT_vertex_shader LOCAL_CONSTANTs. 5130 5131 b. ARB_vertex_program has no intrinsic storage type that corresponds 5132 to EXT_vertex_shader's INVARIANT storage type, but rather supports 5133 program parameters bound to GL state variables, program 5134 environment parameters, and program local parameters. This 5135 essentially makes INVARIANT a special case of an 5136 ARB_vertex_program program parameter. The values of these bound 5137 program parameters can be changed without redefining the program 5138 itself, but remain constant from vertex to vertex during vertex 5139 program execution, just like the values of EXT_vertex_shader 5140 INVARIANTs. 5141 5142 ARB_vertex_program also adds the concept of a program local parameter, 5143 which has no direct analogue in EXT_vertex_shader, as it represents a 5144 parameter that is stored locally with the program object, but the 5145 values of these parameters can be changed without redefining the 5146 program itself. 5147 5148 2. Resource usage queries 5149 5150 Both ARB_vertex_program and EXT_vertex_shader provide queries to assist 5151 in determining the resource usage of a given shader and whether the 5152 shader would "fit" within the limits imposed by the underlying hardware 5153 implementation. The application can investigate the maximum numbers of 5154 shader resources supported by an implementation, shader resources 5155 available in hardware, and resources consumed by a given shader after 5156 being compiled into the implementation's native representation. 5157 5158 In EXT_vertex_shader (see the end of section 2.14 of the 5159 EXT_vertex_shader specification), the queries are handled by glGet. 5160 5161 In ARB_vertex_programs (see section 2.14.3.7 of this specification), 5162 similar queries are handled by GetProgramivARB, with a target of 5163 VERTEX_PROGRAM_ARB. 5164 5165 The following queries exist in both extensions and serve roughly 5166 equivalent purposes in each: 5167 5168 EXT_vertex_shader ARB_vertex_program 5169 ----------------- ------------------ 5170 MAX_VERTEX_SHADER_INSTRUCTIONS_EXT MAX_PROGRAM_INSTRUCTIONS_ARB 5171 MAX_VERTEX_SHADER_VARIANTS_EXT MAX_PROGRAM_ATTRIBS_ARB 5172 MAX_VERTEX_SHADER_LOCALS_EXT MAX_PROGRAM_TEMPORARIES_ARB 5173 5174 MAX_OPTIMIZED_VERTEX_SHADER_INSTRUCTIONS_EXT MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB 5175 MAX_OPTIMIZED_VERTEX_SHADER_VARIANTS_EXT MAX_PROGRAM_NATIVE_ATTRIBS_ARB 5176 MAX_OPTIMIZED_VERTEX_SHADER_LOCALS_EXT MAX_PROGRAM_NATIVE_TEMPORARIES_ARB 5177 5178 VERTEX_SHADER_INSTRUCTIONS_EXT PROGRAM_NATIVE_INSTRUCTIONS_ARB 5179 VERTEX_SHADER_VARIANTS_EXT PROGRAM_NATIVE_ATTRIBS_ARB 5180 VERTEX_SHADER_LOCALS_EXT PROGRAM_NATIVE_TEMPORARIES_ARB 5181 5182 VERTEX_SHADER_OPTIMIZED_EXT PROGRAM_UNDER_NATIVE_LIMITS_ARB 5183 5184 ARB_vertex_program offers additional queries to account for differences 5185 in some of the resource definitions (program environment parameters and 5186 program local parameters, address registers, etc.) as well as the 5187 ability to separately query a compiled program's resource usage 5188 according to the specification versus a possibly more efficient 5189 resource usage obtained by passing the program through by a "smart" 5190 compiler. 5191 5192 The following queries do not exist in ARB_vertex_program due to the 5193 slightly different resource models: 5194 5195 EXT_vertex_shader ARB_vertex_program 5196 ----------------- ------------------ 5197 {MAX_}{OPTIMIZED_}VERTEX_SHADER_INVARIANTS_EXT (a) 5198 {MAX_}{OPTIMIZED_}VERTEX_SHADER_LOCAL_CONSTANTS_EXT (a) 5199 5200 a. ARB_vertex_program coalesces all of the different program 5201 parameters (environment, local, inline constant, and those bound 5202 to GL state) into a single queryable resource for 5203 PROGRAM_PARAMETERS. EXT_vertex_shader provides separate queries 5204 even though these parameters may consume the same resource on some 5205 implementations. 5206 5207 The following queries do not exist in EXT_vertex_shader due to the 5208 slightly different resource models: 5209 5210 EXT_vertex_shader ARB_vertex_program 5211 ----------------- ------------------ 5212 (b) PROGRAM_*_ARB 5213 5214 (c) {MAX_}{NATIVE_}PROGRAM_PARAMETERS_ARB 5215 5216 (d) {MAX_}{NATIVE_}PROGRAM_ADDRESS_REGISTERS_ARB 5217 5218 b. These queries are used to find out how many resources a given 5219 program used according to the specification, *before* running the 5220 program through an optimizing compiler. This distinction is not 5221 made in EXT_vertex_shader. 5222 5223 c. These queries are used to find out how many parameters were used 5224 by a program or are allowed by an implementation, in total without 5225 distinguishing between environment parameters, program local 5226 parameters, inline constant parameters, or parameters bound to GL 5227 state. EXT_vertex_shader does not provide this information. 5228 5229 d. EXT_vertex_shader does not provide have any address register 5230 resources since all dynamic array references are handled with the 5231 atomic OP_INDEX instruction. 5232 5233 3. Symbols and variable names 5234 5235 In EXT_vertex_shader resources that represent storage locations 5236 (i.e. INVARIANTS, VARIANTS, LOCALS, LOCAL_CONSTANTS) are abstractly 5237 referenced through a GL-allocated symbol id obtained from 5238 GenSymbolsEXT. This level of abstraction is provided to allow the 5239 implementation to make hardware-dependent decisions about the best way 5240 to arrange, allocate, and re-use hardware resources. 5241 5242 Though ARB_vertex_program does not use symbol id's to refer to similar 5243 types of resources, it does provide similar functionality by allowing a 5244 vertex program to declare arbitrarily named variables for each resource 5245 in use. These names are assigned using the declaration syntax 5246 associated with the "PARAM", "ATTRIB", "TEMP", and "OUTPUT", and 5247 "ADDRESS" keywords. 5248 5249 4. Program management 5250 5251 With the exception of the actual program specification itself, 5252 EXT_vertex_shader and ARB_vertex_program have very similar program 5253 management API's. 5254 5255 The following procedures serve roughly equivalent functions in their 5256 respective extensions. 5257 5258 EXT_vertex_shader ARB_vertex_program 5259 ----------------- ------------------ 5260 BindVertexShaderEXT BindProgramARB 5261 GenVertexShadersEXT GenProgramsARB 5262 DeleteVertexShaderEXT DeleteProgramsARB 5263 5264 The following procedures are used in EXT_vertex_shader to define the 5265 program instruction sequence, and are not present in ARB_vertex_program 5266 since the string provided to ProgramStringARB fully defines the program 5267 contents. 5268 5269 ShaderOp1EXT 5270 ShaderOp2EXT 5271 ShaderOp3EXT 5272 SwizzleEXT 5273 WriteMaskEXT 5274 InsertComponentEXT 5275 ExtractComponentEXT 5276 5277 5. Data specification routines 5278 5279 With the exception of the discrepancies in data types and resource 5280 names described above, EXT_vertex_shader and ARB_vertex_program provide 5281 similar program data specification and "current data query" API's. 5282 5283 The following procedures serve roughly equivalent functions in their 5284 respective extensions: 5285 5286 EXT_vertex_shader ARB_vertex_program Note 5287 ----------------- ------------------ ----- 5288 SetInvariantEXT ProgramEnvParameter4*ARB (a) 5289 GetInvariant*vEXT GetProgramEnvParameter*vARB (a) 5290 Variant*vEXT VertexAttrib*ARB 5291 VariantPointerEXT VertexAttribPointerARB 5292 GetVariant*vEXT GetVertexAttrib*vARB 5293 GetVariantPointervEXT GetVertexAttribPointervARB 5294 EnableVariantClientStateEXT EnableVertexAttribArrayARB 5295 DisableVariantClientStateEXT DisableVertexAttribArrayARB 5296 IsVariantEnabledEXT GetVertexAttrib*vARB (b) 5297 5298 a. See item #1 and #2 for more information on the relationship 5299 between EXT_vertex_shader invariants and ARB_vertex_program 5300 program parameters. 5301 5302 b. The enabled state of an attribute array in ARB_vertex_program can 5303 be queried with GetVertexAttrib*v and a parameter of 5304 VERTEX_ATTRIB_ARRAY_ENABLED_ARB. In EXT_vertex_shader there is a 5305 dedicated enabled query procedure. 5306 5307 However, there are some data specification routines in 5308 EXT_vertex_shader that have no procedure call analogue in 5309 ARB_vertex_program as their functions are subsumed by the string 5310 representation of the program itself. 5311 5312 The following procedures in EXT_vertex_shader have functionality 5313 roughly covered by the following strings within the program text in 5314 ARB_vertex_shader: 5315 5316 EXT_vertex_shader ARB_vertex_program Note 5317 ----------------- ------------------ ----- 5318 SetLocalConstantEXT PARAM C = {<x>,<y>,<z>,<w>}; (c) 5319 5320 BindLightParameterEXT state.light[n].* 5321 BindMaterialParameterEXT state.material.* (d) 5322 BindTexGenParameterEXT state.texgen[n].* 5323 5324 BindTextureUnitParameterEXT 5325 CURRENT_TEXTURE_COORDS vertex.texcoord[n] 5326 TEXTURE_MATRIX state.matrix.texture[n] 5327 5328 BindParameterEXT 5329 CURRENT_VERTEX_EXT vertex.position 5330 CURRENT_NORMAL vertex.normal 5331 CURRENT_COLOR vertex.color.* 5332 MODELVIEW_MATRIX state.matrix.modelview[n] 5333 PROJECTION_MATRIX state.matrix.projection 5334 MVP_MATRIX_EXT state.matrix.mvp 5335 COLOR_MATRIX <unavailable> (e) 5336 CLIP_PLANE state.clip[n].plane 5337 FOG_COLOR state.fog.color 5338 FOG_DENSITY state.fog.params.x 5339 FOG_START state.fog.params.y 5340 FOG_END state.fog.params.z 5341 LIGHT_MODEL_AMBIENT state.lightmodel.ambient 5342 5343 c. Note that while EXT_vertex_shader style local constants can be 5344 specified using inline constants in the program text, there is no 5345 functionality in ARB_vertex_program that corresponds to the 5346 GetLocalConstant*vEXT call. That is, program parameters bound to 5347 inline constant vectors can be set in the text, but not queried 5348 from the application. 5349 5350 d. Note that while EXT_vertex_shader supports binding material 5351 properties to variants, ARB_vertex_shader only supports binding 5352 them to program parameters (invariants). See item #11 below for 5353 more information. 5354 5355 e. Note that while EXT_vertex_shader supports binding color matrix if 5356 the ARB_imaging subset is supported, ARB_vertex_shader does not 5357 allow for such a binding. See item #11 below for more information. 5358 5359 6. Data types 5360 5361 EXT_vertex_shader supports data types of SCALAR, VECTOR, and MATRIX. 5362 5363 ARB_vertex_program intrinsically supports only vectors, though it 5364 allows for the definition of a matrix as a contiguous allocation of 5365 four row vectors. Some operations that, in EXT_vertex_shader require 5366 scalar inputs or scalar outputs, will, in ARB_vertex_program, use the 5367 selected component of the source vector as input and/or replicate their 5368 output to all components. 5369 5370 Further, EXT_vertex_shader supports a pair of InsertComponents and 5371 ExtractComponents functions that are not available (nor required) in 5372 ARB_vertex_program, as they essentially provide for conversion between 5373 the SCALAR, VECTOR, and MATRIX data types. 5374 5375 7. Input swizzles and output write-masks 5376 5377 In EXT_vertex_shader, write masks are specified as a type of 5378 "instruction", using WriteMaskEXT, while in ARB_vertex_program, write 5379 masks are specified as modifiers to the destination resource with 5380 writemask modifiers, such as ".xyz" or ".w". 5381 5382 In EXT_vertex_shader, source operand swizzles (component re- ordering, 5383 negation, and hard-coding to the value 0 and +/- 1.0) are also 5384 specified as a type of "instruction", using SwizzleEXT. 5385 5386 In ARB_vertex_program, swizzles can either be handled as instruction 5387 ("SWZ") or as part of a modifier of the source argument to an 5388 instruction. The only differences between the two methods is that the 5389 source modifiers in ARB_vertex_program do not provide the ability to 5390 use 0.0 and +/- 1.0, or negate individual components, while the "SWZ" 5391 instruction does. 5392 5393 8. Support for clipping and user clip planes 5394 5395 Both extensions provide similar support for traditional clipping to the 5396 view frustum, namely that frustum clipping is not subsumed by vertex 5397 shader, or vertex program execution. 5398 5399 Additionally, EXT_vertex_shader supports user clip planes by 5400 transforming the user clip planes from eye-space into clip space and 5401 clipping in the clip space coordinate system. This is supported as long 5402 as the projection matrix is non-singular. 5403 5404 ARB_vertex_program provides similar functionality but only for programs 5405 specified using the "position invariant" option. For more information on 5406 user clip-plane support, see issue #20 and section 2.14.4.5.1 of this 5407 specification. 5408 5409 9. Support for glRasterPos 5410 5411 EXT_vertex_shader does not support transforming the current raster 5412 position vertex by the current vertex shader, while ARB_vertex_program 5413 does. 5414 5415 10. Relative addressing. 5416 5417 The string based syntax of ARB_vertex_program supports a relative 5418 addressing model where a given declared array can be dynamically 5419 dereferenced by first loading a declared ADDRESS register, using the 5420 "ARL" instruction with a value obtained at program execution then using 5421 that named ADDRESS register as the index to dereference a declared array 5422 of parameters later on. See section 2.14.3.5 of this specification for 5423 details. 5424 5425 For example, in ARB_vertex_program you can specify the following 5426 piece of a program. 5427 5428 PARAM arr[5] = { program.env[0..4] }; 5429 ADDRESS addr; 5430 ATTRIB v1 = vertex.attrib[1]; 5431 ARL addr, v1; 5432 MOV result, arr[addr.x + 1]; 5433 5434 EXT_vertex_shader supports relative addressing as as a single atomic 5435 operation through the use of the instruction OP_INDEX_EXT, as in 5436 5437 ShaderOp2EXT(OP_INDEX_EXT, <res>, <arg1>, <arg2>). 5438 5439 OP_INDEX_EXT supports relative addressing by taking the value stored in 5440 the register referred to by <arg1> and adding that value to the register 5441 number referred to by <arg2>, and loading <res> with the value stored in 5442 the register at the resulting offset. EXT_vertex_shader has the 5443 requirement that the register referred to by <arg2> is allocated as one 5444 of a contiguous range of symbols obtained from a single call to 5445 GenSymbolsEXT. 5446 5447 To achieve the same functionality as the above ARB_vertex_program, using 5448 EXT_vertex_shader, one could allocate a LOCAL symbol to hold a "fake" 5449 address register, and do a similar type of dynamic dereference 5450 operation, placing the output in a temporary LOCAL before giving it as 5451 an source argument to the "real" instruction. 5452 5453 arr_contiguousArraySymbol = 5454 GenSymbolsEXT(GL_VECTOR_EXT, GL_LOCAL_EXT, GL_FULL_RANGE_EXT, 5); 5455 5456 addr_fakeAddressRegSymbol = 5457 GenSymbolsEXT(GL_VECTOR_EXT, GL_LOCAL_EXT, GL_FULL_RANGE_EXT, 1); 5458 5459 v1_srcSymbolForARLOp = 5460 GenSymbolsEXT(GL_VECTOR_EXT, GL_VARIANT_EXT, GL_FULL_RANGE_EXT, 1); 5461 5462 temp = 5463 GenSymbolsEXT(GL_VECTOR_EXT, GL_LOCAL_EXT, GL_FULL_RANGE_EXT, 1); 5464 5465 result_ForMovOpSymbol = 5466 GenSymbolsEXT(GL_VECTOR_EXT, GL_LOCAL_EXT, GL_FULL_RANGE_EXT, 1); 5467 5468 // load fake ADDRESS register 5469 ExtractComponentEXT( 5470 addr_fakeAddressRegSymbol, 5471 v1_srcSymbolForARLOp, 5472 0); 5473 5474 // do dynamic dereference into a temp 5475 ShaderOp2EXT( 5476 GL_OP_INDEX_EXT, 5477 temp, 5478 addr_fakeAddressRegSymbol, 5479 contiguousArraySymbol); 5480 5481 // do operation we really wanted (MOV) using looked up src value 5482 ShaderOp1EXT( 5483 GL_OP_MOV_EXT, 5484 result_ForMovOpSymbol, 5485 temp, 5486 (arr_contiguousArraySymbol + 1)); 5487 5488 11. Available GL state bindings 5489 5490 Both EXT_vertex_shader and ARB_vertex_program offer the ability to bind 5491 program resources to pieces of OpenGL state so that the values of 5492 OpenGL state parameters are available to the program without the 5493 application having to copy the state values manually into program 5494 parameters. 5495 5496 The two extensions differ in exactly which pieces of state are 5497 available to a vertex program, with the main difference being that 5498 ARB_vertex_program offers a more comprehensive set of state bindings. 5499 5500 First, EXT_vertex_shader can bind pieces of GL state considered to be 5501 "scalar" values to a single SCALAR symbol, whereas ARB_vertex_program, 5502 which handles only vectors, packs up to 4 scalar bindings into a single 5503 vector parameter. 5504 5505 Similarly, EXT_vertex_shader can bind pieces of GL state considered to 5506 be "matrix" values to a single MATRIX symbol, whereas 5507 ARB_vertex_program supports bindings to matrix data by using up to four 5508 vectors to store the rows of the matrix. 5509 5510 Other differences between the state bindings available in both API's 5511 are listed below: 5512 5513 a. In EXT_vertex_shader, the light attenuation factors (CONSTANT, 5514 LINEAR, QUADRATIC, and SPOT_EXPONENT), are available as separate 5515 SCALAR bindings. 5516 5517 In ARB_vertex_program, the light attenuation factors are all 5518 packed into a single vector called state.light[n].attenuation with 5519 the CONSTANT, LINEAR, QUADRATIC, and SPOT_EXPONENT factors in the 5520 x,y,z, and w parameters respectively. 5521 5522 b. In EXT_vertex_shader the spotlight direction (SPOT_DIRECTION) and 5523 spot light cutoff angle (SPOT_CUTOFF), are available as separate 5524 bindings. 5525 5526 In ARB_vertex_program, these parameters are all packed into a 5527 single vector called state.light[n].spot.direction with the with 5528 the x,y,z parameters of the spotlight direction and the the 5529 *cosine* of the cutoff angle in the x,y,z, and w parameters 5530 respectively. 5531 5532 c. In EXT_vertex_shader, the fog equation factors (FOG_DENSITY, 5533 FOG_START, FOG_END), are avaiable as separate SCALAR bindings. 5534 5535 In ARB_vertex_program, the fog equation factors are all packed 5536 into a single vector called state.fog.params with the fog density, 5537 linear start, linear end, and pre-computed 1.0/ (end-start) 5538 factors in the x,y,z, and w parameters respectively. 5539 5540 d. In EXT_vertex_shader, material properties can be bound to a 5541 variant (i.e. "attribute" in ARB_vertex_program terminology) and 5542 can change per vertex, and the changes take effect immediately. 5543 5544 In ARB_vertex_program, material properties can only be bound to 5545 program parameters, and any changes to material properties between 5546 a Begin/End pair are not guaranteed to take effect until the 5547 following End command. 5548 5549 e. In EXT_vertex_shader, the material shininess property is bound to 5550 a SCALAR variable. 5551 5552 In ARB_vertex_program, the material shininess property is bound to 5553 a vector with elements { s, 0.0, 0.0, 1.0 } where "s" is the 5554 material shininess property. 5555 5556 f. In EXT_vertex_shader, a program can bind to the current modelview, 5557 projection, composite modelview-projection, color, and texture 5558 matrices only in their entirety. 5559 5560 In ARB_vertex_program, a program can bind to individual rows of 5561 any matrix, with the exception of the color matrix, which is not 5562 available in ARB_vertex_program. 5563 5564 Additionally, ARB_vertex_program adds the ability to bind to 5565 multiple modelview matrices, multiple palette matrices, and a set 5566 of matrices dedicated for use with vertex programs called "program 5567 matrices". Further, ARB_vertex_program offers the ability to bind 5568 to the inverse, transpose, and inverse_transpose of any of the 5569 matrices available for binding. 5570 5571 If an application desires the functionality of binding to the 5572 color matrix in ARB_vertex_program, that application can use one 5573 of the other matrices, for instance program matrices, to store the 5574 current color matrix. 5575 5576 12. Instruction set differences. 5577 5578 In general, ARB_vertex_program's instruction set is a super-set of the 5579 EXT_vertex_shader instructions that take VECTOR inputs and produce 5580 VECTOR outputs. The versions of the EXT_vertex_shader instructions that 5581 take non-vector (i.e. SCALAR or MATRIX) operands are almost all 5582 available in vector form as well. 5583 5584 The instructions from each set correspond as follows: 5585 5586 EXT_vertex_shader ARB_vertex_program Note 5587 ----------------- ------------------ ----- 5588 OP_INDEX_EXT <unavailable> (a) 5589 OP_NEGATE_EXT <unavailable> (b) 5590 OP_DOT3_EXT "DP3" (c) 5591 OP_DOT4_EXT "DP4" 5592 OP_MUL_EXT "MUL" 5593 OP_ADD_EXT "ADD" 5594 OP_MADD_EXT "MAD" 5595 OP_FRAC_EXT "FRC" 5596 OP_MAX_EXT "MAX" 5597 OP_MIN_EXT "MIN" 5598 OP_SET_GE_EXT "SGE" 5599 OP_SET_LT_EXT "SLT" 5600 OP_CLAMP_EXT <unavailable> (d) 5601 OP_FLOOR_EXT "FLR" 5602 OP_ROUND_EXT <unavailable> (e) 5603 OP_EXP_BASE_2_EXT "EX2" (f) 5604 OP_LOG_BASE_2_EXT "LG2" (g) 5605 OP_POWER_EXT "POW" (h) 5606 OP_RECIP_EXT "RCP" (i) 5607 OP_RECIP_SQRT_EXT "RSQ" (j) 5608 OP_SUB_EXT "SUB" 5609 OP_CROSS_PRODUCT_EXT "XPD" (k) 5610 OP_MULTIPLY_MATRIX_EXT <unavailable> (l) 5611 OP_MOV_EXT "MOV" 5612 <unavailable> "ARL" (a) 5613 <unavailable> "ABS" 5614 <unavailable> "LIT" 5615 <unavailable> "EXP" (f) 5616 <unavailable> "LOG" (g) 5617 <unavailable> "DPH" 5618 <unavailable> "DST" 5619 5620 There are a few minor differences, however. 5621 5622 a. EXT_vertex_shader's OP_INDEX_EXT is not available in 5623 ARB_vertex_program which uses the "ARL" instruction and array syntax 5624 to handle dynamically dereferencing source data. See item #10 above 5625 and the discussion of "ARL" in section 2.14.3.5. 5626 5627 b. EXT_vertex_shader's OP_NEGATE_EXT is not available in 5628 ARB_vertex_program. ARB_vertex_program can support a "NEGATE" 5629 operation through the use of swizzle modifiers on source operands or 5630 the "SWZ" instruction. 5631 5632 MOV tempA, -tempB; 5633 5634 or 5635 5636 SWZ tempA, -tempB, x,y,z,w; 5637 5638 c. The "w" component of EXT_vertex_shader's OP_DOT3_EXT instruction is 5639 left unchanged. 5640 5641 However, in ARB_vertex_program, the "w" component gets the same 5642 result as the "x", "y", and "z" components. 5643 5644 d. EXT_vertex_shader's OP_CLAMP_EXT is not available in 5645 ARB_vertex_program. ARB_vertex_program can support a "CLAMP" 5646 operation by using a pair of "MAX" and "MIN" instructions as in: 5647 5648 # CLAMP arg1 to be within [arg2, arg3] 5649 MAX temp, arg1, arg2; 5650 MIN result, temp, arg3; 5651 5652 e. EXT_vertex_shader's OP_ROUND_EXT is not available in 5653 ARB_vertex_program. ARB_vertex_program can support a "ROUND" 5654 operation by using a pair of "ADD" and "FLOOR" instructions as in: 5655 5656 ADD temp, arg1, 0.5; 5657 FLOOR result, temp; 5658 5659 f. EXT_vertex_shader's OP_EXP_BASE_2_EXT is designed to support high 5660 precision calculations of base-2 exponentiation. 5661 5662 ARB_vertex_program's "EX2" is the equivalent function, however 5663 ARB_vertex_program also offers an "EXP" function that is designed to 5664 support a lower precision approximation of base-2 exponentiation 5665 that can be further refined through an iterative process. 5666 5667 On some implementations, both "EX2" and "EXP" may be carried out 5668 with the same high precision at no cost relative to each other. As 5669 such, if a vertex program is using "EXP" with the intent of 5670 iteratively refining the approximation by using several successive 5671 instructions it may be more efficient to use a single call to "EX2" 5672 and get the high precision with a single instruction. 5673 5674 If on the other hand, a single approximation is good enough, there 5675 is no additional cost to using "EXP" on such implementations. 5676 5677 Further note that in EXT_vertex_shader, OP_EXP_BASE_2_EXT is 5678 specified to take a scalar operand, whereas ARB_vertex_program's 5679 "EXP" and "EX2" instruction each take a vector operand, use the "x" 5680 component, and then write (partial) results to all components of a 5681 destination vector. 5682 5683 g. EXT_vertex_shader's OP_LOG_BASE_2_EXT is designed to support high 5684 precision calculations of base-2 logarithms. 5685 5686 ARB_vertex_program's "LG2" is the equivalent function, however 5687 ARB_vertex_program also offers an "LOG" function that is designed to 5688 support a lower precision approximation of base-2 logarithms that 5689 can be further refined through an iterative process. 5690 5691 On some implementations, both "LG2" and "LOG" may be carried out 5692 with the same high precision at no cost relative to each other. As 5693 such, if a vertex program is using "LOG" with the intent of 5694 iteratively refining the approximation by using several successive 5695 instructions it may be more efficient to use a single call to "LG2" 5696 and get the high precision with a single instruction. 5697 5698 If on the other hand, a single approximation is good enough, there 5699 is no additional cost to using "LOG" on such implementations. 5700 5701 Further note that in EXT_vertex_shader, OP_LOG_BASE_2_EXT is 5702 specified to take a scalar operand, whereas ARB_vertex_program's 5703 "LOG" and "LOG2" instruction each take a vector operand, use the "x" 5704 component, and then write (partial) results to all components of a 5705 destination vector. 5706 5707 h. EXT_vertex_shader's OP_POWER_EXT is designed to support high 5708 precision calculations of the power function. 5709 5710 ARB_vertex_program's "POW" is the equivalent function. 5711 5712 Further note that in EXT_vertex_shader, OP_POWER_EXT is specified to 5713 take a scalar operand, whereas ARB_vertex_program's "POW" 5714 instruction takes a vector operand, uses the "x" component, and 5715 replicates the same result to all components of a destination 5716 vector. 5717 5718 i. EXT_vertex_shader's OP_RECIP_EXT is specified to take a scalar 5719 operand, whereas ARB_vertex_program's "RCP" instruction takes a 5720 single component of a vector and replicates the same result to all 5721 components of the destination vector. 5722 5723 j. EXT_vertex_shader's OP_RECIP_SQRT_EXT is specified to take a scalar 5724 operand, whereas ARB_vertex_program's "RSQ" instruction takes a 5725 single component of a vector and replicates the same result to all 5726 components of the destination vector. 5727 5728 k. The "w" component of EXT_vertex_shader's OP_CROSS_PRODUCT_EXT 5729 instruction is forced to 1.0; 5730 5731 However, in ARB_vertex_program, the "w" component is left undefined 5732 and "writes to the w component of the destination are treated as 5733 disabled, regardless of the write mask specified in the XPD 5734 instruction". 5735 5736 l. EXT_vertex_shader's OP_MULTIPLY_MATRIX is not available in 5737 ARB_vertex_program. ARB_vertex_program can support a "MATRIX 5738 MULTIPLY" operation by using a series of "DP4" instructions as in: 5739 5740 PARAM mat[4] = { state.matrix.modelview }; 5741 DP4 result.x, vec, mat[0]; 5742 DP4 result.y, vec, mat[1]; 5743 DP4 result.z, vec, mat[2]; 5744 DP4 result.w, vec, mat[3]; 5745 5746 13. Vertex provoking behavior 5747 5748 EXT_vertex_shader does not provoke vertex shader execution when variant 5749 0 is specified (either using Variant*EXT, or variant 5750 arrays). Applications are required to use the conventional Vertex* or 5751 vertex arrays to provoke a vertex in both vertex shader mode and 5752 conventional mode. Variant 0 is considered current state and is 5753 queryable. 5754 5755 Conversely, ARB_vertex_program does provoke vertex program execution 5756 when attribute 0 is specified (either using VertexAttrib*vARB, or 5757 attribute arrays) in both vertex program mode and conventional mode. 5758 Attribute 0 is not considered current state and is not queryable. 5759 5760 For implementations that support both extensions, this means that if 5761 ARB_vertex_program is disabled, and EXT_vertex_shader is enabled, then 5762 specifying ARB_vertex_program's attribute 0 will still provoke 5763 execution of the currently bound EXT_vertex_shader defined shader. 5764 5765 14. Enabled state 5766 5767 On implementations that support both EXT_vertex_shader, and 5768 ARB_vertex_program, priority is given to ARB_vertex_program. That is to 5769 say, if both are enabled, the implementation uses the program defined 5770 by ARB_vertex_program and does not execute the currently bound 5771 EXT_vertex_shader shader unless or until ARB_vertex_program is 5772 subsequently disabled. Needless to say, it is not expected that a given 5773 application will actually attempt to use both vertex program API's at 5774 once. 5775 5776 5777GLX Protocol 5778 5779 The following rendering commands are sent to the server as part of a 5780 glXRender request: 5781 5782 VertexAttrib1svARB 5783 2 12 rendering command length 5784 2 4189 rendering command opcode 5785 4 CARD32 index 5786 2 INT16 v[0] 5787 2 unused 5788 5789 VertexAttrib1fvARB 5790 2 12 rendering command length 5791 2 4193 rendering command opcode 5792 4 CARD32 index 5793 4 FLOAT32 v[0] 5794 5795 VertexAttrib1dvARB 5796 2 16 rendering command length 5797 2 4197 rendering command opcode 5798 4 CARD32 index 5799 8 FLOAT64 v[0] 5800 5801 VertexAttrib2svARB 5802 2 12 rendering command length 5803 2 4190 rendering command opcode 5804 4 CARD32 index 5805 2 INT16 v[0] 5806 2 INT16 v[1] 5807 5808 VertexAttrib2fvARB 5809 2 16 rendering command length 5810 2 4194 rendering command opcode 5811 4 CARD32 index 5812 4 FLOAT32 v[0] 5813 4 FLOAT32 v[1] 5814 5815 VertexAttrib2dvARB 5816 2 24 rendering command length 5817 2 4198 rendering command opcode 5818 4 CARD32 index 5819 8 FLOAT64 v[0] 5820 8 FLOAT64 v[1] 5821 5822 VertexAttrib3svARB 5823 2 16 rendering command length 5824 2 4191 rendering command opcode 5825 4 CARD32 index 5826 2 INT16 v[0] 5827 2 INT16 v[1] 5828 2 INT16 v[2] 5829 2 unused 5830 5831 VertexAttrib3fvARB 5832 2 20 rendering command length 5833 2 4195 rendering command opcode 5834 4 CARD32 index 5835 4 FLOAT32 v[0] 5836 4 FLOAT32 v[1] 5837 4 FLOAT32 v[2] 5838 5839 VertexAttrib3dvARB 5840 2 32 rendering command length 5841 2 4199 rendering command opcode 5842 4 CARD32 index 5843 8 FLOAT64 v[0] 5844 8 FLOAT64 v[1] 5845 8 FLOAT64 v[2] 5846 5847 VertexAttrib4bvARB 5848 2 12 rendering command length 5849 2 4230 rendering command opcode 5850 4 CARD32 index 5851 1 INT8 v[0] 5852 1 INT8 v[1] 5853 1 INT8 v[2] 5854 1 INT8 v[3] 5855 5856 VertexAttrib4svARB 5857 2 16 rendering command length 5858 2 4192 rendering command opcode 5859 4 CARD32 index 5860 2 INT16 v[0] 5861 2 INT16 v[1] 5862 2 INT16 v[2] 5863 2 INT16 v[3] 5864 5865 VertexAttrib4ivARB 5866 2 24 rendering command length 5867 2 4231 rendering command opcode 5868 4 CARD32 index 5869 4 INT32 v[0] 5870 4 INT32 v[1] 5871 4 INT32 v[2] 5872 4 INT32 v[3] 5873 5874 VertexAttrib4ubvARB 5875 2 12 rendering command length 5876 2 4232 rendering command opcode 5877 4 CARD32 index 5878 1 CARD8 v[0] 5879 1 CARD8 v[1] 5880 1 CARD8 v[2] 5881 1 CARD8 v[3] 5882 5883 VertexAttrib4usvARB 5884 2 16 rendering command length 5885 2 4233 rendering command opcode 5886 4 CARD32 index 5887 2 CARD16 v[0] 5888 2 CARD16 v[1] 5889 2 CARD16 v[2] 5890 2 CARD16 v[3] 5891 5892 VertexAttrib4uivARB 5893 2 24 rendering command length 5894 2 4234 rendering command opcode 5895 4 CARD32 index 5896 4 CARD32 v[0] 5897 4 CARD32 v[1] 5898 4 CARD32 v[2] 5899 4 CARD32 v[3] 5900 5901 VertexAttrib4fvARB 5902 2 24 rendering command length 5903 2 4196 rendering command opcode 5904 4 CARD32 index 5905 4 FLOAT32 v[0] 5906 4 FLOAT32 v[1] 5907 4 FLOAT32 v[2] 5908 4 FLOAT32 v[3] 5909 5910 VertexAttrib4dvARB 5911 2 40 rendering command length 5912 2 4200 rendering command opcode 5913 4 CARD32 index 5914 8 FLOAT64 v[0] 5915 8 FLOAT64 v[1] 5916 8 FLOAT64 v[2] 5917 8 FLOAT64 v[3] 5918 5919 VertexAttrib4NbvARB 5920 2 12 rendering command length 5921 2 4235 rendering command opcode 5922 4 CARD32 index 5923 1 INT8 v[0] 5924 1 INT8 v[1] 5925 1 INT8 v[2] 5926 1 INT8 v[3] 5927 5928 VertexAttrib4NsvARB 5929 2 16 rendering command length 5930 2 4236 rendering command opcode 5931 4 CARD32 index 5932 2 INT16 v[0] 5933 2 INT16 v[1] 5934 2 INT16 v[2] 5935 2 INT16 v[3] 5936 5937 VertexAttrib4NivARB 5938 2 24 rendering command length 5939 2 4237 rendering command opcode 5940 4 CARD32 index 5941 4 INT32 v[0] 5942 4 INT32 v[1] 5943 4 INT32 v[2] 5944 4 INT32 v[3] 5945 5946 VertexAttrib4NubvARB 5947 2 12 rendering command length 5948 2 4201 rendering command opcode 5949 4 CARD32 index 5950 1 CARD8 v[0] 5951 1 CARD8 v[1] 5952 1 CARD8 v[2] 5953 1 CARD8 v[3] 5954 5955 VertexAttrib4NusvARB 5956 2 16 rendering command length 5957 2 4238 rendering command opcode 5958 4 CARD32 index 5959 2 CARD16 v[0] 5960 2 CARD16 v[1] 5961 2 CARD16 v[2] 5962 2 CARD16 v[3] 5963 5964 VertexAttrib4NuivARB 5965 2 24 rendering command length 5966 2 4239 rendering command opcode 5967 4 CARD32 index 5968 4 CARD32 v[0] 5969 4 CARD32 v[1] 5970 4 CARD32 v[2] 5971 4 CARD32 v[3] 5972 5973 BindProgramARB 5974 2 12 rendering command length 5975 2 4180 rendering command opcode 5976 4 ENUM target 5977 4 CARD32 program 5978 5979 ProgramEnvParameter4fvARB 5980 2 32 rendering command length 5981 2 4184 rendering command opcode 5982 4 ENUM target 5983 4 CARD32 index 5984 4 FLOAT32 params[0] 5985 4 FLOAT32 params[1] 5986 4 FLOAT32 params[2] 5987 4 FLOAT32 params[3] 5988 5989 ProgramEnvParameter4dvARB 5990 2 44 rendering command length 5991 2 4185 rendering command opcode 5992 4 ENUM target 5993 4 CARD32 index 5994 8 FLOAT64 params[0] 5995 8 FLOAT64 params[1] 5996 8 FLOAT64 params[2] 5997 8 FLOAT64 params[3] 5998 5999 ProgramLocalParameter4fvARB 6000 2 32 rendering command length 6001 2 4215 rendering command opcode 6002 4 ENUM target 6003 4 CARD32 index 6004 4 FLOAT32 params[0] 6005 4 FLOAT32 params[1] 6006 4 FLOAT32 params[2] 6007 4 FLOAT32 params[3] 6008 6009 ProgramLocalParameter4dvARB 6010 2 44 rendering command length 6011 2 4216 rendering command opcode 6012 4 ENUM target 6013 4 CARD32 index 6014 8 FLOAT64 params[0] 6015 8 FLOAT64 params[1] 6016 8 FLOAT64 params[2] 6017 8 FLOAT64 params[3] 6018 6019 The ProgramStringARB is potentially large, and hence can be sent in a 6020 glXRender or glXRenderLarge request. 6021 6022 ProgramStringARB 6023 2 16+len+p rendering command length 6024 2 4217 rendering command opcode 6025 4 ENUM target 6026 4 ENUM format 6027 4 sizei len 6028 len LISTofBYTE program 6029 p unused, p=pad(len) 6030 6031 If the command is encoded in a glxRenderLarge request, the command 6032 opcode and command length fields above are expanded to 4 bytes each: 6033 6034 4 16+len+p rendering command length 6035 4 4217 rendering command opcode 6036 6037 VertexAttribPointerARB, EnableVertexAttribArrayARB, and 6038 DisableVertexAttribArrayARB are entirely client-side commands. 6039 6040 The remaining commands are non-rendering commands. These commands are 6041 sent separately (i.e., not as part of a glXRender or glXRenderLarge 6042 request), using the glXVendorPrivateWithReply request: 6043 6044 DeleteProgramsARB 6045 1 CARD8 opcode (X assigned) 6046 1 17 GLX opcode (glXVendorPrivateWithReply) 6047 2 4+n request length 6048 4 1294 vendor specific opcode 6049 4 GLX_CONTEXT_TAG context tag 6050 4 INT32 n 6051 n*4 LISTofCARD32 programs 6052 6053 GenProgramsARB 6054 1 CARD8 opcode (X assigned) 6055 1 17 GLX opcode (glXVendorPrivateWithReply) 6056 2 4 request length 6057 4 1295 vendor specific opcode 6058 4 GLX_CONTEXT_TAG context tag 6059 4 INT32 n 6060 => 6061 1 1 reply 6062 1 unused 6063 2 CARD16 sequence number 6064 4 n reply length 6065 24 unused 6066 n*4 LISTofCARD322 programs 6067 6068 GetProgramEnvParameterfvARB 6069 1 CARD8 opcode (X assigned) 6070 1 17 GLX opcode (glXVendorPrivateWithReply) 6071 2 6 request length 6072 4 1296 vendor specific opcode 6073 4 GLX_CONTEXT_TAG context tag 6074 4 ENUM target 6075 4 CARD32 index 6076 4 unused 6077 => 6078 1 1 reply 6079 1 unused 6080 2 CARD16 sequence number 6081 4 m reply length, m=(n==1?0:n) 6082 4 unused 6083 4 CARD32 n (number of parameter components) 6084 6085 if (n=1) this follows: 6086 6087 4 FLOAT32 params 6088 12 unused 6089 6090 otherwise this follows: 6091 6092 16 unused 6093 n*4 LISTofFLOAT32 params 6094 6095 GetProgramEnvParameterdvARB 6096 1 CARD8 opcode (X assigned) 6097 1 17 GLX opcode (glXVendorPrivateWithReply) 6098 2 6 request length 6099 4 1297 vendor specific opcode 6100 4 GLX_CONTEXT_TAG context tag 6101 4 ENUM target 6102 4 CARD32 index 6103 4 unused 6104 => 6105 1 1 reply 6106 1 unused 6107 2 CARD16 sequence number 6108 4 m reply length, m=(n==1?0:n*2) 6109 4 unused 6110 4 CARD32 n (number of parameter components) 6111 6112 if (n=1) this follows: 6113 6114 8 FLOAT64 params 6115 8 unused 6116 6117 otherwise this follows: 6118 6119 16 unused 6120 n*8 LISTofFLOAT64 params 6121 6122 GetProgramLocalParameterfvARB 6123 1 CARD8 opcode (X assigned) 6124 1 17 GLX opcode (glXVendorPrivateWithReply) 6125 2 6 request length 6126 4 1305 vendor specific opcode 6127 4 GLX_CONTEXT_TAG context tag 6128 4 ENUM target 6129 4 CARD32 index 6130 4 unused 6131 => 6132 1 1 reply 6133 1 unused 6134 2 CARD16 sequence number 6135 4 m reply length, m=(n==1?0:n) 6136 4 unused 6137 4 CARD32 n (number of parameter components) 6138 6139 if (n=1) this follows: 6140 6141 4 FLOAT32 params 6142 12 unused 6143 6144 otherwise this follows: 6145 6146 16 unused 6147 n*4 LISTofFLOAT32 params 6148 6149 GetProgramLocalParameterdvARB 6150 1 CARD8 opcode (X assigned) 6151 1 17 GLX opcode (glXVendorPrivateWithReply) 6152 2 6 request length 6153 4 1306 vendor specific opcode 6154 4 GLX_CONTEXT_TAG context tag 6155 4 ENUM target 6156 4 CARD32 index 6157 4 unused 6158 => 6159 1 1 reply 6160 1 unused 6161 2 CARD16 sequence number 6162 4 m reply length, m=(n==1?0:n*2) 6163 4 unused 6164 4 CARD32 n (number of parameter components) 6165 6166 if (n=1) this follows: 6167 6168 8 FLOAT64 params 6169 8 unused 6170 6171 otherwise this follows: 6172 6173 16 unused 6174 n*8 LISTofFLOAT64 params 6175 6176 GetProgramivARB 6177 1 CARD8 opcode (X assigned) 6178 1 17 GLX opcode (glXVendorPrivateWithReply) 6179 2 5 request length 6180 4 1307 vendor specific opcode 6181 4 GLX_CONTEXT_TAG context tag 6182 4 ENUM target 6183 4 ENUM pname 6184 => 6185 1 1 reply 6186 1 unused 6187 2 CARD16 sequence number 6188 4 m reply length, m=(n==1?0:n) 6189 4 unused 6190 4 CARD32 n 6191 6192 if (n=1) this follows: 6193 6194 4 INT32 params 6195 12 unused 6196 6197 otherwise this follows: 6198 6199 16 unused 6200 n*4 LISTofINT32 params 6201 6202 GetProgramStringARB 6203 1 CARD8 opcode (X assigned) 6204 1 17 GLX opcode (glXVendorPrivateWithReply) 6205 2 5 request length 6206 4 1308 vendor specific opcode 6207 4 GLX_CONTEXT_TAG context tag 6208 4 ENUM target 6209 4 ENUM pname 6210 => 6211 1 1 reply 6212 1 unused 6213 2 CARD16 sequence number 6214 4 (n+p)/4 reply length 6215 4 unused 6216 4 CARD32 n 6217 16 unused 6218 n STRING program 6219 p unused, p=pad(n) 6220 6221 Note that VERTEX_ATTRIB_ARRAY_ENABLED_ARB, 6222 VERTEX_ATTRIB_ARRAY_SIZE_ARB, VERTEX_ATTRIB_ARRAY_STRIDE_ARB, 6223 VERTEX_ATTRIB_ARRAY_TYPE_ARB, and VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB 6224 may be queried by GetVertexAttrib[dfi]ARB, but generate no protocol 6225 and return client-side state. 6226 6227 GetVertexAttribdvARB 6228 1 CARD8 opcode (X assigned) 6229 1 17 GLX opcode (glXVendorPrivateWithReply) 6230 2 5 request length 6231 4 1301 vendor specific opcode 6232 4 GLX_CONTEXT_TAG context tag 6233 4 INT32 index 6234 4 ENUM pname 6235 => 6236 1 1 reply 6237 1 unused 6238 2 CARD16 sequence number 6239 4 m reply length, m=(n==1?0:n*2) 6240 4 unused 6241 4 CARD32 n 6242 6243 if (n=1) this follows: 6244 6245 8 FLOAT64 params 6246 8 unused 6247 6248 otherwise this follows: 6249 6250 16 unused 6251 n*8 LISTofFLOAT64 params 6252 6253 GetVertexAttribfvARB 6254 1 CARD8 opcode (X assigned) 6255 1 17 GLX opcode (glXVendorPrivateWithReply) 6256 2 5 request length 6257 4 1302 vendor specific opcode 6258 4 GLX_CONTEXT_TAG context tag 6259 4 INT32 index 6260 4 ENUM pname 6261 => 6262 1 1 reply 6263 1 unused 6264 2 CARD16 sequence number 6265 4 m reply length, m=(n==1?0:n) 6266 4 unused 6267 4 CARD32 n 6268 6269 if (n=1) this follows: 6270 6271 4 FLOAT32 params 6272 12 unused 6273 6274 otherwise this follows: 6275 6276 16 unused 6277 n*4 LISTofFLOAT32 params 6278 6279 GetVertexAttribivARB 6280 1 CARD8 opcode (X assigned) 6281 1 17 GLX opcode (glXVendorPrivateWithReply) 6282 2 5 request length 6283 4 1303 vendor specific opcode 6284 4 GLX_CONTEXT_TAG context tag 6285 4 INT32 index 6286 4 ENUM pname 6287 => 6288 1 1 reply 6289 1 unused 6290 2 CARD16 sequence number 6291 4 m reply length, m=(n==1?0:n) 6292 4 unused 6293 4 CARD32 n 6294 6295 if (n=1) this follows: 6296 6297 4 INT32 params 6298 12 unused 6299 6300 otherwise this follows: 6301 6302 16 unused 6303 n*4 LISTofINT32 params 6304 6305 IsProgramARB 6306 1 CARD8 opcode (X assigned) 6307 1 17 GLX opcode (glXVendorPrivateWithReply) 6308 2 4 request length 6309 4 1304 vendor specific opcode 6310 4 GLX_CONTEXT_TAG context tag 6311 4 INT32 n 6312 => 6313 1 1 reply 6314 1 unused 6315 2 CARD16 sequence number 6316 4 0 reply length 6317 4 BOOL32 return value 6318 20 unused 6319 6320 When transferring vertex attribute array elements, there may not be a 6321 protocol encoding that exactly matches the combination of combination of 6322 size, normalization enable, and data type in the array. If no match 6323 protocol encoding exists, the encoding for the corresponding 4-component 6324 attribute is used. v[1] and v[2] are set to zero if not specified in the 6325 vertex array. If v[3] is not specified in the vertex array, it is set to 6326 0x7F, 0x7FFF, 0x7FFFFFFF, 0xFF, 0xFFFF, or 0xFFFFFFFF for the 6327 VertexAttrib4NbvARB, VertexAttrib4NsvARB, VertexAttrib4NivARB, 6328 VertexAttrib4NubvARB, VertexAttrib4NusvARB, and VertexAttrib4NuivARB 6329 protocol encodings, respectively. v[3] is set to one if it is not 6330 specified in the vertex array for the the VertexAttrib4bvARB, 6331 VertexAttrib4svARB, VertexAttrib4ivARB, VertexAttrib4ubvARB, 6332 VertexAttrib4usvARB, and VertexAttrib4uivARB protocol encodings. 6333 6334 6335Errors 6336 6337 The error INVALID_VALUE is generated by any VertexAttrib*ARB or 6338 GetVertexAttrib*ARB command if <index> is greater than or equal to 6339 MAX_VERTEX_ATTRIBS_ARB. 6340 6341 The error INVALID_VALUE is generated by VertexAttribPointerARB or 6342 GetVertexAttribPointervARB if <index> is greater than or equal to 6343 MAX_VERTEX_ATTRIBS_ARB. 6344 6345 The error INVALID_VALUE is generated by VertexAttribPointerARB if <size> 6346 is not one of 1, 2, 3, or 4. 6347 6348 The error INVALID_VALUE is generated by VertexAttribPointerARB if <stride> 6349 is negative. 6350 6351 The error INVALID_VALUE is generated by EnableVertexAttribArrayARB or 6352 DisableVertexAttribArrayARB if <index> is greater than or equal to 6353 MAX_VERTEX_ATTRIBS_ARB. 6354 6355 The error INVALID_OPERATION is generated by ProgramStringARB if the 6356 program string <string> is syntactically incorrect or violates any 6357 semantic restriction of the execution environment of the specified program 6358 target <target>. 6359 6360 The error INVALID_OPERATION is generated by BindProgramARB if <program> is 6361 the name of a program whose target does not match <target>. 6362 6363 The error INVALID_VALUE is generated by any ProgramEnvParameter*ARB or 6364 GetProgramEnvParameter*ARB command if <index> is greater than or equal to 6365 the value of MAX_PROGRAM_ENV_PARAMETERS_ARB corresponding to the program 6366 target <target>. 6367 6368 The error INVALID_VALUE is generated by any ProgramLocalParameter*ARB or 6369 GetProgramLocalParameter*ARB command if <index> is greater than or equal 6370 to the value of MAX_PROGRAM_LOCAL_PARAMETERS_ARB corresponding to the 6371 program target <target>. 6372 6373 The error INVALID_OPERATION is generated if Begin, RasterPos, or any 6374 command that performs an explicit Begin is called when vertex program mode 6375 is enabled and the currently bound vertex program object does not contain 6376 a valid vertex program. 6377 6378 The error INVALID_OPERATION is generated by GetVertexAttrib*ARB if <index> 6379 is zero and <pname> is CURRENT_VERTEX_ATTRIB_ARB. 6380 6381 6382New State 6383 6384 6385Get Value Type Get Command Initial Value Description Section Attribute 6386------------------------------- ------ ------------- ------------- ------------------ ------------ ------------ 6387VERTEX_PROGRAM_ARB B IsEnabled False vertex program 2.10 enable 6388 enable 6389VERTEX_PROGRAM_POINT_SIZE_ARB B IsEnabled False program-specified 2.14.3.7 enable 6390 point size mode 6391VERTEX_PROGRAM_TWO_SIDE_ARB B IsEnabled False two-sided color 2.14.3.7 enable 6392 mode 6393- 96+xR4 GetProgramEnv- (0,0,0,0) program environment 2.14.1 - 6394 ParameterARB parameters 6395CURRENT_VERTEX_ATTRIB_ARB 16+xR4 GetVertex- undefined generic vertex 2.7 current 6396 AttribARB attributes 6397PROGRAM_ERROR_POSITION_ARB Z GetIntegerv -1 last program error 2.14.1 - 6398 position 6399PROGRAM_ERROR_STRING_ARB 0+xub GetString "" last program error 2.14.1 - 6400 string 6401 6402Table X.6. New Accessible State Introduced by ARB_vertex_program. 6403 6404 6405Get Value Type Get Command Initial Value Description Section Attribute 6406------------------------------- ------ ------------- ------------- ------------------ ------------ ------------ 6407VERTEX_ATTRIB_ARRAY_ENABLED_ARB 16+xB GetVertex- False vertex attrib 2.8 vertex-array 6408 AttribARB array enable 6409VERTEX_ATTRIB_ARRAY_SIZE_ARB 16+xZ GetVertex- 4 vertex attrib 2.8 vertex-array 6410 AttribARB array size 6411VERTEX_ATTRIB_ARRAY_STRIDE_ARB 16+xZ+ GetVertex- 0 vertex attrib 2.8 vertex-array 6412 AttribARB array stride 6413VERTEX_ATTRIB_ARRAY_TYPE_ARB 16+xZ4 GetVertex- FLOAT vertex attrib 2.8 vertex-array 6414 AttribARB array type 6415VERTEX_ATTRIB_ARRAY_ 16+xB GetVertex- False vertex attrib 2.8 vertex-array 6416 NORMALIZED_ARB AttribARB array normalized 6417VERTEX_ATTRIB_ARRAY_POINTER_ARB 16+xP GetVertex- NULL vertex attrib 2.8 vertex-array 6418 AttribPointerARB array pointer 6419 6420Table X.7. New Accessible Client State Introduced by ARB_vertex_program. 6421 6422 6423Get Value Type Get Command Initial Value Description Sec Attrib 6424-------------------- ----- ------------------- --------------- ---------------------- -------- ------ 6425PROGRAM_BINDING_ARB Z+ GetProgramivARB object-specific bound program name 6.1.12 - 6426PROGRAM_LENGTH_ARB Z+ GetProgramivARB 0 bound program length 6.1.12 - 6427PROGRAM_FORMAT_ARB Z1 GetProgramivARB PROGRAM_FORMAT_ bound program format 6.1.12 - 6428 ASCII_ARB 6429PROGRAM_STRING_ARB ubxn GetProgramStringARB (empty) bound program string 6.1.12 - 6430PROGRAM_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 6431 instructions 6432PROGRAM_TEMPORARIES_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 6433 temporaries 6434PROGRAM_PARAMETERS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 6435 parameter bindings 6436PROGRAM_ATTRIBS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 6437 attribute bindings 6438PROGRAM_ADDRESS_REGISTERS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 6439 address registers 6440PROGRAM_NATIVE_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 6441 instructions 6442PROGRAM_NATIVE_TEMPORARIES_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 6443 temporaries 6444PROGRAM_NATIVE_PARAMETERS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 6445 parameter bindings 6446PROGRAM_NATIVE_ATTRIBS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 6447 attribute bindings 6448PROGRAM_NATIVE_ADDRESS_ Z+ GetProgramivARB 0 bound program native 6.1.12 - 6449 REGISTERS_ARB address registers 6450PROGRAM_UNDER_NATIVE_LIMITS_ARB B GetProgramivARB 0 bound program under 6.1.12 - 6451 native resource limits 6452- 96+xR4 GetProgramLocal- (0,0,0,0) bound program local 2.14.1 - 6453 ParameterARB parameter value 6454 6455Table X.8. Program Object State. Program object queries return attributes of 6456the program object currently bound to the program target <target>. 6457 6458 6459Get Value Type Get Command Initial Value Description Sec Attribute 6460--------- ------ ----------- ------------- ----------------------- -------- --------- 6461- 12+xR4 - undefined temporary registers 2.14.3.6 - 6462- 8+xR4 - undefined vertex result registers 2.14.3.7 - 6463 1+xZ1 - undefined vertex program 2.14.3.8 - 6464 address registers 6465 6466Table X.9. Vertex Program Per-vertex Execution State. All per-vertex 6467execution state registers are uninitialized at the beginning of program 6468execution. 6469 6470 6471Get Value Type Get Command Initial Value Description Sec Attribute 6472------------------------------ -------- -------------- ------------- ------------------- ------- --------- 6473CURRENT_MATRIX_ARB m*n*xM^4 GetFloatv Identity current matrix 6.1.2 - 6474CURRENT_MATRIX_STACK_DEPTH_ARB m*Z+ GetIntegerv 1 current stack depth 6.1.2 - 6475 6476Table X.10. Current matrix state where m is the total number of matrices 6477including texture matrices and program matrices and n is the number of 6478matrices on each particular matrix stack. Note that this state is aliased 6479with existing matrix state. 6480 6481 6482New Implementation Dependent State 6483 Minimum 6484Get Value Type Get Command Value Description Sec Attrib 6485----------------------------------- ---- --------------- ---------- -------------------- ------------ ------ 6486MAX_PROGRAM_ENV_PARAMETERS_ARB Z+ GetProgramivARB 96 maximum program 2.14.1 - 6487 env parameters 6488MAX_PROGRAM_LOCAL_PARAMETERS_ARB Z+ GetProgramivARB 96 maximum program 2.14.1 - 6489 local parameters 6490MAX_PROGRAM_MATRICES_ARB Z+ GetIntegerv 8 (not to maximum number of 2.14.6 - 6491 exceed 32) program matrices 6492MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB Z+ GetIntegerv 1 maximum program 2.14.6 - 6493 matrix stack depth 6494MAX_PROGRAM_INSTRUCTIONS_ARB Z+ GetProgramivARB 128 maximum program 6.1.12 - 6495 instructions 6496MAX_PROGRAM_TEMPORARIES_ARB Z+ GetProgramivARB 12 maximum program 6.1.12 - 6497 temporaries 6498MAX_PROGRAM_PARAMETERS_ARB Z+ GetProgramivARB 96 maximum program 6.1.12 - 6499 parameter bindings 6500MAX_PROGRAM_ATTRIBS_ARB Z+ GetProgramivARB 16 maximum program 6.1.12 - 6501 attribute bindings 6502MAX_PROGRAM_ADDRESS_REGISTERS_ARB Z+ GetProgramivARB 1 maximum program 6.1.12 - 6503 address registers 6504MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 6505 instructions 6506MAX_PROGRAM_NATIVE_TEMPORARIES_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 6507 temporaries 6508MAX_PROGRAM_NATIVE_PARAMETERS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 6509 parameter bindings 6510MAX_PROGRAM_NATIVE_ATTRIBS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 6511 attribute bindings 6512MAX_PROGRAM_NATIVE_ADDRESS_ Z+ GetProgramivARB - maximum program native 6.1.12 - 6513 REGISTERS_ARB address registers 6514 6515Table X.11. New Implementation-Dependent Values Introduced by 6516ARB_vertex_program. Values queried by GetProgramivARB require a <pname> of 6517VERTEX_PROGRAM_ARB. 6518 6519 6520Revision History 6521 6522 Rev. Date Author Changes 6523 ---- -------- -------- -------------------------------------------- 6524 46 07/25/07 mjk Document how the ARB and NV generic arrays 6525 interact. This documents NVIDIA's 6526 long-standing implemented behavior. 6527 6528 45 09/27/04 pbrown Fixed GLX protocol, removing the unused <pname> 6529 parameters for GetProgram{Env,Local}Parameter 6530 [df]vARB, leaving an unused CARD32 in its place. 6531 This was an error when propogating 6532 NV_vertex_program protocol, which did have a 6533 <pname> parameter. 6534 6535 44 09/12/03 pbrown Fixed opcode table entry for "ARL" -- it takes a 6536 scalar operand as specified in the grammar. 6537 6538 43 08/17/03 pbrown Fixed a couple minor typos (missing quotes) 6539 in the grammar. 6540 6541 42 05/01/03 pbrown Clarified the handling of color sum; old text 6542 suggested that COLOR_SUM controlled the 6543 operation even when doing separate specular 6544 lighting. 6545 6546 41 04/18/03 pbrown Add a couple overlooked contributors. 6547 6548 40 03/03/03 pbrown Fixed list of immediate-mode VertexAttrib 6549 functions in Section 2.7 -- there are no 6550 normalized float functions (e.g., 6551 VertexAttrib4Nfv). Clarified issue (42) 6552 describing how point size is handled in vertex 6553 program mode. 6554 6555 39 01/31/03 pbrown Fixed minor bug in the description of vertex 6556 array state kept by the GL -- normalization 6557 flags were omitted from the text (but were in 6558 the state tables). 6559 6560 38 01/08/03 pbrown Fixed bug where "state.matrix.mvp" was specified 6561 incorrectly -- it should be P*M0 rather than 6562 M0*P. 6563 6564 37 12/23/02 pbrown Fixed minor typos. Fixed state table bug where 6565 CURRENT_VERTEX_ATTRIB_ARB was incorrectly called 6566 CURRENT_ATTRIB_ARB. 6567 6568 36 09/09/02 pbrown Fixed incorrect example of matrix row bindings 6569 (and transposition). Small wording/typo fixes. 6570 6571 35 08/27/02 pbrown Fixed several minor typos. Documented that a 6572 program string should not include a null 6573 terminator in its first <len> characters. Fixed 6574 dangling reference in <paramMultipleItem> 6575 grammar rule. Fix incorrect wording in 6576 computation of state.light.half vector. 6577 Documented that the inverse of a singular matrix 6578 is undefined. Clarified that native 6579 instructions can include additions due to 6580 emulation of features not supported natively. 6581 Documented that LG2 produces undefined results 6582 with zero or negative inputs. Clarified that 6583 POW may be a LOG/MUL/EXP sequence, but isn't 6584 necessarily so. Disallowed multiple modelview 6585 matrix syntax if ARB_vertex_blend or 6586 EXT_vertex_weighting is unsupported. Fixed 6587 state table query function for attribute array 6588 enables. Added missing state table entry for 6589 PROGRAM_UNDER_NATIVE_LIMITS_ARB. 6590 6591 34 07/19/02 pbrown Fixed typo in ArrayElement pseudo-code. 6592 6593 33 07/17/02 pbrown Fixed bug in the <stateLModProperty> grammar 6594 rule. Fixed documentation to indicate that 6595 Enable/DisableVertexAttribArray are not display 6596 listable. 6597 6598 31 07/15/02 pbrown Fixed <SWZ_instruction> grammar rule to match 6599 the spec language -- base operand negation 6600 doesn't apply, since you can independently 6601 negate components. Modified "XPD" instruction 6602 to eliminate the implicit masking of the "w" 6603 component; slight efficiency gain for some SW 6604 implementations. Modified "scenecolor" binding 6605 to pass the diffuse alpha instead of the ambient 6606 alpha; the former is more useful. 6607 6608 30 07/02/02 pbrown Minor wording fixes. 6609 6610 29 06/21/02 pbrown Mostly minor bug fixes from reviewer feedback; 6611 also added one new item approved at ARB meeting. 6612 6613 Additions: Added a "lightmodel.*.scenecolor" 6614 holding lit color containing the composite 6615 lighting result ignoring individual lights -- 6616 i.e., from only emissive materials and the light 6617 model. Added GLX protocol. 6618 6619 Minor changes: Numerous minor typo and wording 6620 fixes. Added missing vertex array types to 6621 vertex array size/type/normalized table. Added 6622 missing description of ambient light model color 6623 binding. Removed several references to language 6624 features long since deleted. Documented that 6625 POW is not necessarily implemented as 6626 LOG/MUL/EXP. Fixed a couple minor errata in the 6627 EXT_vertex_shader interaction section. Added a 6628 list of reserved keywords. 6629 6630 28 06/16/02 pbrown Minor updates based on feedback given on 6631 versions 26 and 27. 6632 6633 Additions: Added section on EXT_vertex_shader 6634 interaction, provided by ATI. 6635 6636 Minor changes: Minor grammar and readability 6637 fixes. Fixed several incomplete definitions. 6638 Removed "GL" and "gl" prefixes from several 6639 enumerants and function names to match spec 6640 conventions. Clarified the precision issue on 6641 EX2/LG2. Added missing functions that take 6642 VERTEX_PROGRAM_ARB. Clarified component 6643 normalization on vertex arrays. Clarified 6644 clipping section to note that user clipping is 6645 done with position invariant programs. 6646 Clarified the handling of program zero in 6647 BindProgramARB. Fixed a couple incorrect 6648 grammar rules. Fixed incorrect grammar 6649 references in description of vertex program 6650 parameter array accesses. Documented that the 6651 SWZ instruction doesn't take "normal" swizzle 6652 and negation modifiers, since it already has 6653 some. Clarified some NV_vertex_program 6654 interactions. 6655 6656 27 06/07/02 pbrown Minor update based on ARB_vertex_program sample 6657 implementation work. 6658 6659 Changes: Changed fog coordinate attribute and 6660 result binding name to "fogcoord" (was "fog"). 6661 Rearranged grammar based on sample 6662 implementation verification. There might be a 6663 minor fix or two stuck in there. 6664 6665 26 06/04/02 pbrown Spec checkpoint published on the working group 6666 web site. Resolves most of the remaining open 6667 issues. 6668 6669 Deletions: Removed the ability to bind the 6670 color matrix (from ARB_imaging). 6671 6672 Changes: Resolved the handling of vertex 6673 attribute zero (it always specifies a vertex, in 6674 program mode or not). Resolved the handling of 6675 generic and conventional vertex attribute arrays 6676 (they are always sent, although they also have 6677 "undefined aliasing" behavior). Default values 6678 of generic attributes are undefined, to 6679 accommodate aliasing and non-aliasing 6680 implementations. Added pseudocode to document 6681 the processing of ArrayElement. Moved program 6682 object language into the vertex program section. 6683 Renamed the fog coordinate attribute and result 6684 binding to "fogcoord". Added missing 6685 documentation of the agreed-upon semantic 6686 restriction that programs can't bind 6687 conventional / generic attribute pairs that may 6688 alias. Added documentation of what happens when 6689 multiple contexts share program objects 6690 Disallowed queries of generic attribute zero. 6691 6692 Fixes: Fixed prototype for VertexAttrib4Nub. 6693 6694 Minor Changes: Minor typo and language 6695 fixes. Added guidelines for future 6696 programmability extensions. Added several 6697 missing grammar rules. 6698 6699 25 05/30/02 pbrown Spec checkpoint published on the working group 6700 web site. 6701 6702 Additions: Add "DPH" (dot product homogeneous) 6703 instruction. Added the ability to query the 6704 current matrix in transposed form. Assigned 6705 enumerant values for program matrices. Added 6706 the ability bind selected rows of a matrix. 6707 Added ability to bind matrix palette matrices. 6708 6709 Changes: Renamed PROGRAM_NAME_ARB to 6710 PROGRAM_BINDING_ARB. Specifying the number of 6711 elements in parameter arrays is now optional, 6712 but compilation will fail if the specified count 6713 does not match. Programs performing 6714 out-of-bounds array accesses using absolute 6715 addressing will now fail to load. Allow "$" in 6716 token names. 6717 6718 Minor changes: Completed scrub of the issues 6719 and error list. Added new issues about reserved 6720 keywords, identifier characters, and parsing of 6721 floating-point constants in programs. 6722 Miscellaneous typo fixes. Updated the grammar 6723 to include light products and half angles, moved 6724 material properties from per-vertex to parameter 6725 bindings, and a few other miscellaneous fixes. 6726 Simplified the matrix binding table. Modified 6727 the color sum portion of the spec to explicitly 6728 add R,G,B only. Removed several incorrect 6729 errors. Fixed program object state table. 6730 6731 24 05/21/02 pbrown Spec checkpoint published on the working group 6732 web site. 6733 6734 Deletions: Removed the semantic requirement 6735 that vertex programs write a vertex position, 6736 per working group resolution. 6737 6738 Minor changes: Cleaned up cruft in a number of 6739 issues; many more to go. Added several issues. 6740 Documented that VertexAttrib functions are 6741 allowed inside Begin/End pairs. Changed default 6742 initialization values of generic attributes to 6743 accommodate attribute aliasing. Documented that 6744 point sizes and fog coordinates computed by 6745 vertex programs are clipped during primitive 6746 clipping. Documented that vertex program 6747 behavior is undefined in color index mode. 6748 6749 23 05/21/02 pbrown Spec checkpoint. More changes from working 6750 group deliberations. 6751 6752 Additions: Added vertex materials as allowed 6753 program parameter bindings. Allow programs to 6754 use vertex attribute binding names, program 6755 parameter binding names, result variable binding 6756 names, and constants in executable statements, 6757 resulting in implicit bindings. Added support 6758 for binding a single row of a matrix. Added 6759 support for binding precomputed light/material 6760 products. Added restriction that a single GL 6761 state vector can't be bound multiple times in 6762 two separate arrays accessed with relative 6763 addressing. Added new section documenting the 6764 various resource limits, and introducting the 6765 idea of "native" resource limits and counts. 6766 6767 Deletions: Removed vertex materials as allowed 6768 vertex attribute bindings. 6769 6770 Minor changes: Added more names to the 6771 contributors list. Updated issues concerning 6772 undefined aliasing. Moved NV_vertex_program 6773 related issues to the NV_vertex_program 6774 interaction sections. Updated NV_vertex_program 6775 interactions. Updated lighting example using 6776 new derived state bindings. Clarified that 6777 "!!ARBvp1.0" is not a token in the grammar and 6778 that programs are parsed beginning immediately 6779 after the header string. Added text to explain 6780 all attribute, program parameter, and result 6781 bindings instead of depending on binding table 6782 interpretations. Broke the large program 6783 parameter binding table into several smaller 6784 tables, organized by function. Documented that 6785 the queryable program error string may contain 6786 warnings when a program loads successfully, and 6787 that a queried program error string is 6788 guaranteed to remain constant only until the 6789 next program load attempt. Added PROGRAM_NAME 6790 query to the appropriate state table. 6791 6792 22 05/20/02 pbrown Spec checkpoint. More changes from working 6793 group deliberations. 6794 6795 Added functionality: Assigned enumerant values. 6796 Added "undefined (vertex attribute) aliasing" 6797 language, where setting a generic attribute 6798 leaves a conventional one undefined, and vice 6799 versa. Added support for matrix indices from 6800 ARB_matrix_palette. Added default program 6801 object zero. Added support for simple named 6802 variable aliasing. Added queries of API-level 6803 and "native" resources used by a program and 6804 their corresponding limits. Added general query 6805 to determine if a program fits in native limits. 6806 6807 Removed functionality: Removed extension string 6808 entry for position-invariant programs (now 6809 mandatory). 6810 6811 Modified functionality: GetProgram and 6812 GetProgramString now take a target instead of a 6813 program name. Default values for 3 generic 6814 attributes are changed for consistent aliasing. 6815 Added 1/(end-start) binding for fog parameters. 6816 Added precomputed infinite light/viewer half 6817 angle binding. ProgramString takes a "void *" 6818 instead of a "ubyte *". 6819 6820 Minor Changes: Clarified key terms for the 6821 extension. Documented that user clipping is not 6822 supported in the base extension. Added warnings 6823 on a couple pitfalls from uninitalized result 6824 registers. Document that EXT_vertex_weighting 6825 and ARB_vertex_blend use the same weight. 6826 Cleaned up bindings for 4-component colors for 6827 cases where only three components are used. 6828 Documented the implicit absolute value operation 6829 on the LOG instruction. Renamed query token for 6830 querying generic vertex attribute array enables. 6831 Renamed and relocated vertex program binding 6832 query. Added language to Section 2.6. Changed 6833 syntax to bind a range of the environment or 6834 local paramater array to use double dots (".."). 6835 Clarified what happens on a weight binding using 6836 more weights than an implementation supports. 6837 Clarified the component selection pseudocode for 6838 scalar operand loads. Clarified what happens to 6839 vertex program results during primitive 6840 assembly. Fixed a number of errors in the state 6841 tables. 6842 6843 21 04/29/02 pbrown More changes from working group deliberations. 6844 6845 Added functionality: Added "FLR", "FRC", "POW", 6846 and "XPD" (cross product) instructions. Added 6847 functions to enable/disable generic attribute 6848 arrays. Added query of a program error string. 6849 Added "format" enum argument to ProgramStringARB 6850 to provide for possible programs not using ASCII 6851 text. Added new enums to permit different 6852 limits for overall numbers of program 6853 environment and local parameters and the number 6854 of parameters that can be bound by a program. 6855 6856 Removed functionality: Removed support for 6857 evaluators for generic attributes. Removed 6858 support for program residency management. 6859 Removed support for user clipping in standard 6860 vertex programs. Removed functionality to set 6861 more than one program environment parameter at 6862 once. 6863 6864 Issues/Changes: Resolved set of immediate mode 6865 VertexAttrib functions. Combined parameter 6866 bindings for several groups of related GL state. 6867 Resolved user clipping issue by disallowing 6868 except for position invariant programs. 6869 Resolved limits for array relative offsets. 6870 GenProgramsARB and DeleteProgramsARB will use 6871 texture object model. Program environment 6872 parameters will not be pushed/popped. 6873 6874 Bug fixes: Fixed vertex attribute index 6875 prototypes (should be uint instead of int). 6876 Fixed tokens used to query generic attribute 6877 state (should have VERTEX prefixes). Fixed 6878 documentation of the alpha component of material 6879 colors. Fixed documentation of initial state 6880 for vertex program objects. 6881 6882 Temporarily removed dated GLX protocol language 6883 (will restore in one pass after resolving 6884 remaining issues). 6885 6886 20 04/17/02 pbrown Clarify the meaning of individual components of 6887 program parameters where the component mapping 6888 is not obvious from the mapping table. 6889 6890 18 04/15/02 pbrown Update spec to reflect issues resolved by the 6891 working group on 4/11. 6892 6893 Started using "program matrix" terminology -- 6894 was "tracking matrix". 6895 6896 Address register variables must now be declared. 6897 The number of address registers can be queried. 6898 Only 1-component address registers are currently 6899 supported. 6900 6901 VertexAttribPointer takes a separate argument to 6902 indicate normalized data, now called 6903 "normalized" (was "normalize"). 6904 6905 ProgramString and functions to set and query 6906 local parameters all take a <target> and refer 6907 to the currently bound program (previously took 6908 a program number). Have not touched other 6909 somewhat related issues (e.g., is there a 6910 program object zero?). 6911 6912 Added COLOR_SUM enable (taken directly from 6913 EXT_secondary_color) for completeness and a 6914 few updates to EXT_secondary_color 6915 interactions. 6916 6917 Fixed cut-and-paste error in specification of 6918 the clip-space user clip dot product. 6919 6920 Documented special-case arithmetic for ADD, MAD, 6921 and MUL. 6922 6923 Eliminated some wordiness in DP3 and DP4 6924 instruction pseudo-code. 6925 6926 Minor changes not from working group: More 6927 verbose documentation on the user clipping 6928 issue. More detail on other opcode candidates. 6929 Removed redundant color material issue. Minor 6930 fixes to error roundup (not complete) and to 6931 state tables to reflect that most program 6932 execution variables are initially undefined. 6933 6934 17 04/08/02 pbrown Issues: Enumerated other candidates for 6935 consideration in the instruction set -- there 6936 may be more that I missed. Added a description 6937 of some of the considerations on how color 6938 material should be treated. Added issues on the 6939 name of the program matrices, the number of MVP 6940 matrices, and where variable declarations 6941 can be done. Added numbers to all spec issues. 6942 Fixed lighting example (issue 74) so it 6943 compiles, and so that the half vector is 6944 properly normalized. 6945 6946 Grammar: Eliminated stale hardwired temporary, 6947 parameter array, and result register names 6948 (R<n>, c[<n>], and o[...]). Should have been 6949 deleted going from revision 5 to revision 12. 6950 Added missing program matrix bindings to the 6951 grammar. Eliminated state material-as-parameter 6952 bindings. Fixed texgen paramete bindings, which 6953 should have had both "eye" and "object" planes. 6954 Added separate address register write masks and 6955 selectors to reflect the current single- 6956 component address register restriction. Added 6957 an array[A0.x] rule -- before, you erroneously 6958 had to add or subtract a constant. Modified SWZ 6959 so that the register being swizzled can't take a 6960 conventional swizzle suffix, too. 6961 6962 Also reorganized grammar to closely mirror the 6963 sample implementation, consolidating a number of 6964 redundant rules. Also fixed several bugs 6965 found by the implementation. 6966 6967 Documentation changes to "LIT" to use the right 6968 variable name and also indicate that 0^0=1. 6969 Fixed the computation of result.y in the "LOG" 6970 instruction. 6971 6972 Other: Added dependency on ARB_imaging. Added 6973 notation of Microsoft's IP claims. Fixed name 6974 of MAX_VERTEX_PROGRAM_TEMPORARIES_ARB. 6975 6976 A few minor typo fixes. 6977 6978 12 03/11/02 pbrown Modified spec to reflect decisions made at 6979 the March 2002 ARB meeting. Distributed 6980 to the OpenGL participants list. 6981 6982 5 03/03/02 pbrown Distributed to the ARB prior to March 2002 6983 ARB meeting. 6984