1Name 2 3 ARB_fragment_program 4 5Name Strings 6 7 GL_ARB_fragment_program 8 9Contributors 10 11 Bob Beretta 12 Pat Brown 13 Matt Craighead 14 Cass Everitt 15 Evan Hart 16 Jon Leech 17 Bill Licea-Kane 18 Bimal Poddar 19 Jeremy Sandmel 20 Jon Paul Schelter 21 Avinash Seetharamaiah 22 Nick Triantos 23 24 and contributors to the ARB_vertex_program working group, 25 the product of which provided the basis for this spec 26 27Contact 28 29 Benj Lipchak, AMD (benj.lipchak 'at' amd.com) 30 31Notice 32 33 Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at 34 http://www.khronos.org/registry/speccopyright.html 35 36IP Status 37 38 Microsoft claims to own intellectual property related to this 39 extension. 40 41Status 42 43 Complete. Approved by ARB on September 18, 2002 44 45Version 46 47 Last Modified Date: October 8, 2013 48 Revision: 28 49 50Number 51 52 ARB Extension #27 53 54Dependencies 55 56 The extension is written against the OpenGL 1.3 Specification. 57 58 OpenGL 1.3 is required. 59 60 EXT_texture_lod_bias or OpenGL 1.4 is required. 61 62 OpenGL 1.4 affects the definition of this extension. 63 64 ARB_vertex_blend and EXT_vertex_weighting affect the definition of 65 this extension. 66 67 ARB_matrix_palette affects the definition of this extension. 68 69 ARB_transpose_matrix affects the definition of this extension. 70 71 EXT_fog_coord affects the definition of this extension. 72 73 EXT_texture_rectangle affects the definition of this extension. 74 75 ARB_shadow interacts with this extension. 76 77 ARB_vertex_program interacts with this extension. 78 79 ATI_fragment_shader interacts with this extension. 80 81 NV_fragment_program interacts with this extension. 82 83 84Overview 85 86 Unextended OpenGL mandates a certain set of configurable per- 87 fragment computations defining texture application, texture 88 environment, color sum, and fog operations. Several extensions have 89 added further per-fragment computations to OpenGL. For example, 90 extensions have defined new texture environment capabilities 91 (ARB_texture_env_add, ARB_texture_env_combine, ARB_texture_env_dot3, 92 ARB_texture_env_crossbar), per-fragment depth comparisons 93 (ARB_depth_texture, ARB_shadow, ARB_shadow_ambient, 94 EXT_shadow_funcs), per-fragment lighting (EXT_fragment_lighting, 95 EXT_light_texture), and environment mapped bump mapping 96 (ATI_envmap_bumpmap). 97 98 Each such extension adds a small set of relatively inflexible per- 99 fragment computations. 100 101 This inflexibility is in contrast to the typical flexibility 102 provided by the underlying programmable floating point engines 103 (whether micro-coded fragment engines, DSPs, or CPUs) that are 104 traditionally used to implement OpenGL's texturing computations. 105 The purpose of this extension is to expose to the OpenGL application 106 writer a significant degree of per-fragment programmability for 107 computing fragment parameters. 108 109 For the purposes of discussing this extension, a fragment program is 110 a sequence of floating-point 4-component vector operations that 111 determines how a set of program parameters (not specific to an 112 individual fragment) and an input set of per-fragment parameters are 113 transformed to a set of per-fragment result parameters. 114 115 The per-fragment computations for standard OpenGL given a particular 116 set of texture and fog application modes (along with any state for 117 extensions defining per-fragment computations) is, in essence, a 118 fragment program. However, the sequence of operations is defined 119 implicitly by the current OpenGL state settings rather than defined 120 explicitly as a sequence of instructions. 121 122 This extension provides an explicit mechanism for defining fragment 123 program instruction sequences for application-defined fragment 124 programs. In order to define such fragment programs, this extension 125 defines a fragment programming model including a floating-point 126 4-component vector instruction set and a relatively large set of 127 floating-point 4-component registers. 128 129 The extension's fragment programming model is designed for efficient 130 hardware implementation and to support a wide variety of fragment 131 programs. By design, the entire set of existing fragment programs 132 defined by existing OpenGL per-fragment computation extensions can 133 be implemented using the extension's fragment programming model. 134 135Issues 136 137 This extension is closely related to ARB_vertex_program, and is in 138 sync with revision 36 of that spec. ARB_fragment_program will 139 continue to track changes made to ARB_vertex_program. 140 141 (1) Should we provide precision queries? 142 143 RESOLVED: We've decided not to include precision queries. 144 Implementations are expected to meet or exceed the precision 145 guidelines set forth in the core GL spec, section 2.1.1, p. 6, 146 as ammended by this extension. 147 148 To summarize section 2.1.1, the maximum representable magnitude of 149 colors must be at least 2^10, while the maximum representable 150 magnitude of other floating-point values must be at least 2^32. 151 The individual results of floating-point operations must be 152 accurate to about 1 part in 10^5. 153 154 Here are the reasons why precision queries were not included: 155 1. It is unclear what the queries should be: 156 a) min, max, [0,1) granularity 157 b) min +, max +, min -, max -, [0,1) granularity 158 c) IEEE mantissa bits, IEEE exponent bits 159 2. Due to instruction emulation, there is no way to query the 160 actual precision that can be expected. Should the query 161 return the best-case or worst-case precision? 162 3. Implementations may support multiple precisions, on a per- 163 instruction basis or across the board. How would this be 164 exposed? 165 4. Current implementations are able to meet the minimum 166 requirements specified in the core GL, thanks to its 167 sufficiently loose wording "... so that the individual 168 results of floating-point operations are accurate to ABOUT 169 1 part in 10^5." (Emphasis added.) 170 5. A conformance test can act as watchdog to ensure 171 implementations are not cutting corners on precision. 172 6. Adding precision queries would require a new entrypoint. 173 174 See issue 22 regarding reduced-precision modes. 175 176 (2) Should the LOD biased texture sample be optional? 177 178 RESOLVED: TXB support is mandatory. This exposes useful 179 functionality which enables blurring and sharpening effects. It 180 will be more useful to entirely override derivatives (scale 181 factor) rather than just biasing the level-of-detail. This would 182 be a future extension to fragment programs. 183 184 It should be noted here that the bias introduced per-fragment by 185 TXB is added to any per-object or per-stage LOD bias. If per- 186 fragment LOD bias is not necessary, using the per-object and/or 187 per-stage LOD biases may perform better. 188 189 (3) Should we include the ability to bind to the color matrix? How 190 about others? Program matrices? 191 192 RESOLVED: We will not specifically add anything that depends on 193 the ARB_imaging subset. So we have not included matrix bindings 194 to the color matrix (or parameter bindings to the color biases, 195 etc.). However, we have included matrix binding support and 196 support for all of the matrices present in ARB_vertex_program. 197 198 (4) Should we include the ability to bind to just a texcoord 199 attribute's S,T components? (Or just S, or S,T,P for that matter?) 200 201 RESOLVED: No. Issue #15 below obviates this issue by making the 202 texture coordinate usage within a program explicit, thereby making 203 optimizations to reduce the number of interpolated texture 204 coordinates something an implementation can do at compile time 205 instead of having to do it during every texture target change. 206 207 (5) What other instructions should be added? Should any be removed? 208 209 RESOLVED: The differences between the ARB_vertex_program 210 instruction set and the ARB_fragment_program instruction set are 211 minimal. ARB_fragment_program removes the LOG and EXP rough 212 approximation instructions and the ARL address register load 213 instruction. ARB_fragment_program adds the SIN/COS/SCS 214 trigonometric instructions, the LRP linear interpolation 215 instruction, the CMP compare instruction, and the TEX/TXP/TXB/KIL 216 texture instructions. 217 218 (6) Should depth output be a program option or a mandatory feature? 219 220 RESOLVED: Depth output capability should be mandatory. 221 222 (6a) How should per-vertex geometric depth clipping be handled when 223 replacing depth in a fragment program? 224 225 RESOLVED: Per-vertex geometric depth clipping should be performed 226 by the GL as usual, so no spec change is required. The ideal 227 behavior would be to disable near and far clipping planes when 228 replacing depth, but not all implementations can natively support 229 disabling individual clip planes. 230 231 (6b) How should depth output from the fragment program be further 232 processed before being handed to the per-fragment operations? 233 234 RESOLVED: Depth gets clamped by GL to [0,1]. App has access to 235 depth range as a bindable parameter if it wants to either scale 236 and bias its depth to fall within the depth range, or to kill 237 fragments outside the depth range. 238 239 (7) If a fragment program does not write a color value, what should 240 be the final color of the fragment? 241 242 RESOLVED: The final fragment color is undefined. Note that it may 243 be perfectly reasonable to have a program that computes depth 244 values but not colors. Fragment colors are often irrelevant if 245 color writes are disabled (via ColorMask). 246 247 (7a) If a fragment program does not write a depth value, what should 248 be the final depth value of the fragment? 249 250 RESOLVED: "Depth fly-over" (using the conventional depth produced 251 by rasterization) should happen whenever a depth-replacing program 252 is not in use. A depth-replacing program is defined as a program 253 that writes to result.depth in at least one instruction. The 254 presence of a depth declaration alone DOES NOT designate a depth- 255 replacing program. The intention is that a future extension 256 introducing conditional execution will still consider a program to 257 be depth-replacing even if the instruction(s) writing to 258 result.depth do(es) not execute. 259 260 Other considered definitions of depth-replacing program: 261 1. The presence of a depth declaration -OR- the use of 262 result.depth as an instruction destination anywhere in the 263 program designates a depth-replacing program. 264 2. Every program is a depth-replacing program, but the GL 265 initializes the depth output to be the depth produced by 266 rasterization. The app may then overwrite the depth output. 267 3. Every program is a depth-replacing program, and the app is 268 solely responsible for copying the depth input to depth 269 output if desired. 270 271 (8) Should relative addressing, like that defined in 272 ARB_vertex_program, be supported in this spec? 273 274 RESOLVED: No, relative addressing won't be included in this spec. 275 276 (9) Should full-featured operand component swizzling, like that 277 defined in ARB_vertex_program, be supported in this spec? 278 279 RESOLVED: Yes, full swizzling is mandatory. 280 281 (10) Should texture instructions contain specific limitations on 282 operations that can be performed? For example, should write masks 283 or operand component swizzling be disallowed? 284 285 RESOLVED: Texture instructions are specified to be very similar to 286 ALU instructions. They have been given 3-letter names, they allow 287 writemasking and saturation (which would be useful for floating- 288 point texture formats), source swizzles and negates, and the 289 ability to use parameters as sources. 290 291 (11) Should we standardize options for stencil or aux data buffer 292 outputs? 293 294 RESOLVED: Stencil and aux data buffers will be saved for a 295 possible future extension to fragment programs. 296 297 (12) Should depth output be pulled from the 3rd or 4th component? 298 299 RESOLVED: 3rd component, as the 3rd component is also used for 300 depth input from the "fragment.position" attribute. 301 302 (13) Which stages are subsumed by fragment programs? 303 304 RESOLVED: Texturing, color sum, and fog. 305 306 (14) What should the minimum resource limits be? 307 308 RESOLVED: 10 attributes, 24 parameters, 4 texture indirections, 309 48 ALU instructions, 24 texture instructions, and 16 temporaries. 310 311 (15) OpenGL provides a hierarchy of texture enables (cube map, 3D, 312 2D, 1D). Should the texture sampling instructions here override 313 that hierarchy and select specific texture targets? 314 315 RESOLVED: Yes. This removes a potential pitfall for developers: 316 leaving the hierarchy of enables in an undesired state. It makes 317 programs more readable as the intent of the sample is more 318 obvious. Finally, it allows compilers to be more aggressive as 319 to which texcoord components are "don't cares" without having to 320 recompile programs when fixed-function texenables change. One 321 drawback is that programs cannot be reused for both 2D and 3D 322 texturing, for example, by simply changing the texture enables. 323 324 Texture sampling can be specified by instructions like 325 326 TEX myTexel, fragment.texcoord[1], texture[2], 3D; 327 328 which would indicate to use texture coordinate set number 1 to 329 sample from the texture object bound to the TEXTURE_3D target on 330 texture image unit 2. 331 332 Each texture unit can have only one "active" target. Programs are 333 not allowed to reference different texture targets in the same 334 texture image unit. In the example above, any other texture 335 instructions using texture image unit 2 must specify the 3D 336 texture target. 337 338 Note that every texture image unit always has a texture bound to 339 every texture target, whether it is a named texture object or a 340 default texture. However, the texture may not be complete as 341 defined in section 3.8.9 of the core GL spec. See issue 23. 342 343 (16) Should aux texture units be additional units on top of existing 344 full-featured texture units, or should this spec fully deprecate 345 "legacy" texture units and only expose texture coordinate sets and 346 texture image units? 347 348 Background: Some implementations are able to expose more 349 "texture image units" (texture maps and associated parameters) 350 than "texture coordinate sets" (current texcoords, texgen, and 351 texture matrices). A conventional GL "texture unit" encompasses 352 both a texture image unit and a texture coordinate set as well as 353 texture environment state. 354 355 RESOLVED: Yes, deprecate "legacy" texture units. This is a more 356 flexible model. 357 358 (17) Should fragment programs affect all fragments, or just those 359 produced by the rasterization of points, lines, and triangles? 360 361 RESOLVED: Every fragment generated by the GL is subject to 362 fragment program mode. This includes point, line, and polygon 363 primitives as well as pixel rectangles and bitmaps. 364 365 (18) Should per-fragment position and fogcoord be bindable as 366 fragment attributes? 367 368 RESOLVED: Yes, interpolated fogcoord will make per-fragment 369 fog application possible, in addition to full fog stage 370 subsummation. Interpolated window position, especially depth, 371 enables interesting depth-replacing algorithms. 372 373 (19) What characters should be used to identify individual 374 components in swizzle selectors and write masks? 375 376 RESOLVED: ARB_vertex_program provides "xyzw". This extension 377 supports "xyzw" and also provides "rgba" for better readability 378 when dealing with RGBA color values. Adding support for special 379 identifiers for dealing with texture coordinates was considered 380 and rejected. "strq" could be used to identify texture coordinate 381 components, but the "r" would conflict with the "r" from "rgba". 382 "stpq" would be another possibility, but could be a source of 383 confusion. 384 385 (20) Should implementations be required to support all programs that 386 fit within the exported limits on the number of resources (e.g., 387 instructions, temporaries) that can be present in a program, even if 388 it means falling back to software? Should implementations be 389 required to reject programs that could never be accelerated? 390 391 RESOLVED: No and no. An implementation is allowed to fail 392 ProgramStringARB due to the program exceeding native resources. 393 Note that this failure must be invariant with respect to all other 394 OpenGL state. In other words, a program cannot succeed to load 395 with default state, but then fail to load when certain GL state 396 is altered. However, an implementation is not required to fail 397 when a program would exceed native resources, and is in fact 398 encouraged to fallback to a software path. See issue 21 for a way 399 of determining if this has happened. 400 401 This notable departure from ARB_vertex_program was made as an 402 accommodation to vendors who could not justify implementing a 403 software fallback path which would be relatively slow even 404 compared to an ARB_vertex_program software fallback path. 405 406 Two issues with this decision: 407 1. The API limits become hints, and one can no longer tell by 408 visual inspection whether or not a program will load on 409 every implementation. 410 2. Program loading will now depend on the optimizer, which may 411 vary from release to release of an implementation. A 412 program that succeeded to load when an ISV first wrote it 413 may fail to load in a future driver version, and vice versa. 414 415 (21) How can applications determine if their programs are too large 416 to run on the native (likely hardware) implementation, and therefore may 417 run with reduced performance? 418 419 RESOLVED: The following code snippet uses a native resource 420 query to guarantee a program is loaded natively (or not at all): 421 422 GLboolean ProgramStringIsNative(GLenum target, GLenum format, 423 GLsizei len, const void *string) 424 { 425 GLint errorPos, isNative; 426 glProgramStringARB(target, format, len, string); 427 glGetIntegerv(GL_PROGRAM_ERROR_POSITION_ARB, &errorPos); 428 glGetProgramivARB(GL_FRAGMENT_PROGRAM_ARB, 429 GL_PROGRAM_UNDER_NATIVE_LIMITS_ARB, &isNative); 430 if ((errorPos == -1) && (isNative == 1)) 431 return GL_TRUE; 432 else 433 return GL_FALSE; 434 } 435 436 Note that a program that successfully loads, and falls under the 437 native limits, is still not guaranteed to execute in hardware. 438 Lack of other resources (e.g., texture memory) or the use of other 439 OpenGL features not natively supported by the implementation 440 (e.g., textures with borders) may also prevent the program from 441 executing in hardware. 442 443 (22) Should we provide applications with a method to control the 444 level of precision used to carry out fragment program computations? 445 446 RESOLVED: Yes. The GL implementation ultimately has control over 447 the level of precision used for fragment program computations. 448 However, the "ARB_precision_hint_fastest" and 449 "ARB_precision_hint_nicest" program options allow applications to 450 guide the GL implementation in its precision selection. The 451 "fastest" option encourages the GL to minimize execution time, 452 with possibly reduced precision. The "nicest" option encourages 453 the GL to maximize precision, with possibly increased execution 454 time. 455 456 If the precision hint is not "fastest", GL implementations should 457 perform low-precision operations only if they could not 458 appreciably affect the final results of the program. Regardless 459 of the precision hint, GL implementations are discouraged from 460 reducing the precision of computations so aggressively that final 461 rendering results could be seriously compromised due to overflow 462 of intermediate values or insufficient number of mantissa bits. 463 464 Some implementations may provide only a single level of precision, 465 in which case these hints may have no effect. However, all 466 implementations will accept these options, even if they are 467 silently ignored. 468 469 More explicit control of precision, such as provided in "C" with 470 data types such as "short", "int", "float", "double", may also be 471 a desirable feature, but this level of detail is left to a 472 separate extension. 473 474 (23) What is the result of a sample from an incomplete texture? 475 The definition of texture completeness can be found in section 3.8.9 476 of the core GL spec. 477 478 RESOLVED: The result of a sample from an incomplete texture is the 479 constant vector (0,0,0,1). The benefit of defining the result to 480 be a constant is that broken apps are guaranteed to generate 481 unexpected (black) results from their bad samples. If we were to 482 leave the result undefined, some implementations may generate 483 expected results some of the time, for example when magfiltering, 484 giving app developers a false sense of correctness in their apps. 485 486 (24) What is a texture indirection, and how is it counted? 487 488 RESOLVED: On some implementations, fragment programs that have 489 complex texture dependency chains may not be supported, even if 490 the instruction counts fit within the exported limits. A texture 491 dependency occurs when a texture instruction depends on the 492 result of a previous instruction (ALU or texture) for use as its 493 texture coordinate. 494 495 A texture indirection can be considered a node in the texture 496 dependency chain. Each node contains a set of texture 497 instructions which execute in parallel, followed by a sequence of 498 ALU instructions. A dependent texture instruction is one that 499 uses a temporary as an input coordinate rather than an attribute 500 or a parameter. A program with no dependent texture instructions 501 (or no texture instructions at all) will have a single node in 502 its texture dependency chain, and thus a single indirection. 503 504 API-level texture indirections are counted by keeping track of 505 which temporaries are read and written within the current node in 506 the texture dependency chain. When a texture instruction is 507 encountered, an indirection may be added and a new node started 508 if either of the following two conditions is true: 509 510 1. the source coordinate of the texture instruction is a 511 temporary that has already been written in the current node, 512 either by a previous texture instruction or ALU instruction; 513 514 2. the result of the texture instruction is a temporary that 515 has already been read or written in the current node by an 516 ALU instruction. 517 518 The texture instruction provoking a new indirection and all 519 subsequent instructions are added to the new node. This process 520 is repeated until the end of the program is encountered. Below 521 is some pseudo-code to describe this: 522 523 indirections = 1; 524 tempsOutput = 0; 525 aluTemps = 0; 526 while (i = getInst()) 527 { 528 if (i.type == TEX) 529 { 530 if (((i.input.type == TEMP) && 531 (tempsOutput & (1 << i.input.index))) || 532 ((i.op != KILL) && (i.output.type == TEMP) && 533 (aluTemps & (1 << i.output.index)))) 534 { 535 indirections++; 536 tempsOutput = 0; 537 aluTemps = 0; 538 } 539 } else { 540 if (i.input1.type == TEMP) 541 aluTemps |= (1 << i.input1.index); 542 if (i.input2 && i.input2.type == TEMP) 543 aluTemps |= (1 << i.input2.index); 544 if (i.input3 && i.input3.type == TEMP) 545 aluTemps |= (1 << i.input3.index); 546 if (i.output.type == TEMP) 547 aluTemps |= (1 << i.output.index); 548 } 549 if ((i.op != KILL) && (i.output.type == TEMP)) 550 tempsOutput |= (1 << i.output.index); 551 } 552 553 For example, the following programs would have 1, 2, and 3 554 texture indirections, respectively: 555 556 !!ARBfp1.0 557 # No texture instructions, but always 1 indirection 558 MOV result.color, fragment.color; 559 END 560 561 !!ARBfp1.0 562 # A simple dependent texture instruction, 2 indirections 563 TEMP myColor; 564 MUL myColor, fragment.texcoord[0], fragment.texcoord[1]; 565 TEX result.color, myColor, texture[0], 2D; 566 END 567 568 !!ARBfp1.0 569 # A more complex example with 3 indirections 570 TEMP myColor1, myColor2; 571 TEX myColor1, fragment.texcoord[0], texture[0], 2D; 572 MUL myColor1, myColor1, myColor1; 573 TEX myColor2, fragment.texcoord[1], texture[1], 2D; 574 # so far we still only have 1 indirection 575 TEX myColor2, myColor1, texture[2], 2D; # This is #2 576 TEX result.color, myColor2, texture[3], 2D; # And #3 577 END 578 579 Note that writemasks for the temporaries written and swizzles 580 for the temporaries read are not taken into consideration when 581 counting indirections. This makes hand-counting of indirections 582 by a developer an easier task. 583 584 Native texture indirections may be counted differently by an 585 implementation to reflect its exact restrictions, to reflect the 586 true dependencies taking into account writemasks and swizzles, 587 and to reflect optimizations such as instruction reordering. 588 589 For implementations with no restrictions on the number of 590 indirections, the maximum indirection count will equal the 591 maximum texture instruction count. 592 593 (25) How can a program reduce SCS's scalar operand to the 594 fundamental period [-PI,PI]? 595 596 RESOLVED: Unlike the individual SIN and COS instructions, SCS 597 requires that its argument be reduced ahead of time to the 598 fundamental period. The reason SCS doesn't perform this 599 operation automatically is that it may make unnecessary redundant 600 work for programs that already have their operand in the correct 601 range. Other programs that do need to reduce their operand 602 simply need to add a block of code before the SCS instruction: 603 604 PARAM myParams = { 0.5, -3.14159, 6.28319, 0.15915 }; 605 MAD myOperand.x, myOperand.x, myParams.w, myParams.x; # a = (a/(2*PI))+0.5 606 FRC myOperand.x, myOperand.x; # a = frac(a) 607 MAD myOperand.x, myOperand.x, myParams.z, myParams.y # a = (a*2*PI)-PI 608 ... 609 SCS myResult, myOperand.x; 610 611 (26) Is depth output from a fragment program guaranteed to be 612 invariant with respect to depth produced via conventional 613 rasterization? 614 615 RESOLVED: No. The floating-point representation of depth values 616 output from a fragment program may lead to the output of depth 617 with less precision than the depth output by convention GL 618 rasterization. For example, a floating-point representation with 619 16 bits of mantissa will certainly produce depth with lesser 620 precision than that of conventional rasterization used in 621 conjunction with a 24-bit depth buffer, where all values are 622 maintained as integers. Be aware of this when mixing conventional 623 GL rendering with fragment program rendering. 624 625 (27) How can conventional GL fog application be achieved within a 626 fragment program? 627 628 RESOLVED: Program options have been introduced that allow a 629 program to request fog to be applied to the final clamped fragment 630 color before being passed along to the antialiasing application 631 stage. This makes it easy for: 632 1. developers to request conventional fog behavior 633 2. implementations with dedicated fog hardware to use it 634 3. implementations without dedicated fog hardware, so they need 635 not track fog state after compilation, and constantly 636 recompile when fog state changes. 637 638 The three mandatory options are ARB_fog_exp, ARB_fog_exp2, and 639 ARB_fog_linear. As these options are mutually exclusive by 640 nature, specifying more than one is not useful. If more than one 641 is specified, the last one encountered in the <optionSequence> 642 will be the one to actually modify the execution environment. 643 644 (28) Why have all of the enums, entrypoints, GLX protocol, and spec 645 language shared with ARB_vertex_program been reproduced here? 646 647 RESOLVED: The two extensions are independent of one another, in 648 so far as an implementation need not support both of them in order 649 to support one of them. Everything needed to implement or make 650 use of ARB_fragment_program is present in this spec without the 651 need to refer to the ARB_vertex_program spec. When and if these 652 two extensions are incorporated into the core OpenGL, the 653 significant overlap of the two will be collapsed into a single 654 instance of the shared parts. 655 656 (29) How might an implementation implement the fog options? To What 657 does the extra resource consumption described in 3.11.4.5.1 658 correspond? 659 660 RESOLVED: The following code snippets reflect possible 661 implementations of the fog options. While an implementation may 662 use other instruction sequences to achieve the same result, or may 663 use external fog hardware if available, all implementations must 664 enforce the API-level resource consumption as described: 2 params, 665 1 temp, 1 attribute, and 3, 4, or 2 instructions. "finalColor" in 666 the examples below is the color that would otherwise be 667 "result.color", with components clamped to the range [0,1]. 668 "result.color.a" is assumed to have already been written, as fog 669 blending does not affect the alpha component. 670 671 EXP: 672 # Exponential fog 673 # f = exp(-d*z) 674 # 675 PARAM p = {DENSITY/LN(2), NOT USED, NOT USED, NOT USED}; 676 PARAM fogColor = state.fog.color; 677 TEMP fogFactor; 678 ATTRIB fogCoord = fragment.fogcoord.x; 679 MUL fogFactor.x, p.x, fogCoord.x; 680 EX2_SAT fogFactor.x, -fogFactor.x; 681 LRP result.color.rgb, fogFactor.x, finalColor, fogColor; 682 683 EXP2: 684 # 685 # 2nd-order Exponential fog 686 # f = exp(-(d*z)^2) 687 # 688 PARAM p = {DENSITY/SQRT(LN(2)), NOT USED, NOT USED, NOT USED}; 689 PARAM fogColor = state.fog.color; 690 TEMP fogFactor; 691 ATTRIB fogCoord = fragment.fogcoord.x; 692 MUL fogFactor.x, p.x, fogCoord.x; 693 MUL fogFactor.x, fogFactor.x, fogFactor.x; 694 EX2_SAT fogFactor.x, -fogFactor.x; 695 LRP result.color.rgb, fogFactor.x, finalColor, fogColor; 696 697 LINEAR: 698 # 699 # Linear fog 700 # f = (end-z)/(end-start) 701 # 702 PARAM p = {-1/(END-START), END/(END-START), NOT USED, NOT USED}; 703 PARAM fogColor = state.fog.color; 704 TEMP fogFactor; 705 ATTRIB fogCoord = fragment.fogcoord.x; 706 MAD_SAT fogFactor.x, p.x, fogCoord.x, p.y; 707 LRP result.color.rgb, fogFactor.x, finalColor, fogColor; 708 709 (30) Why is the order of operands for the CMP instruction different 710 than the order used by another popular graphics API? 711 712 RESOLVED: No other graphics API was used as a basis for the 713 design of ARB_fragment_program except ARB_vertex_program, which 714 did not have a CMP instruction. This independent evolution 715 naturally led to differences in minor details such as order of 716 operands. This discrepancy is noted here to help developers 717 familiar with the other API to avoid this potential pitfall. 718 719 (31) Is depth offset applied to the window z value before it enters 720 the fragment program? 721 722 RESOLVED: As in the base OpenGL specification, the depth offset 723 generated by polygon offset is added during polygon rasterization. 724 The depth value provided to shaders in the fragment.position.z 725 attribute already includes polygon offset, if enabled. If the 726 depth value is replaced by a fragment program, the polygon offset 727 value will NOT be recomputed and added back after fragment program 728 execution. 729 730 NOTE: This is probably not desirable for fragment programs that 731 modify depth values since the partials used to generate the offset 732 may not match the partials of the computed depth value. 733 734 735New Procedures and Functions 736 737 void ProgramStringARB(enum target, enum format, sizei len, 738 const void *string); 739 740 void BindProgramARB(enum target, uint program); 741 742 void DeleteProgramsARB(sizei n, const uint *programs); 743 744 void GenProgramsARB(sizei n, uint *programs); 745 746 void ProgramEnvParameter4dARB(enum target, uint index, 747 double x, double y, double z, double w); 748 void ProgramEnvParameter4dvARB(enum target, uint index, 749 const double *params); 750 void ProgramEnvParameter4fARB(enum target, uint index, 751 float x, float y, float z, float w); 752 void ProgramEnvParameter4fvARB(enum target, uint index, 753 const float *params); 754 755 void ProgramLocalParameter4dARB(enum target, uint index, 756 double x, double y, double z, double w); 757 void ProgramLocalParameter4dvARB(enum target, uint index, 758 const double *params); 759 void ProgramLocalParameter4fARB(enum target, uint index, 760 float x, float y, float z, float w); 761 void ProgramLocalParameter4fvARB(enum target, uint index, 762 const float *params); 763 764 void GetProgramEnvParameterdvARB(enum target, uint index, 765 double *params); 766 void GetProgramEnvParameterfvARB(enum target, uint index, 767 float *params); 768 769 void GetProgramLocalParameterdvARB(enum target, uint index, 770 double *params); 771 void GetProgramLocalParameterfvARB(enum target, uint index, 772 float *params); 773 774 void GetProgramivARB(enum target, enum pname, int *params); 775 776 void GetProgramStringARB(enum target, enum pname, void *string); 777 778 boolean IsProgramARB(uint program); 779 780 781New Tokens 782 783 Accepted by the <cap> parameter of Disable, Enable, and IsEnabled, 784 by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 785 and GetDoublev, and by the <target> parameter of ProgramStringARB, 786 BindProgramARB, ProgramEnvParameter4[df][v]ARB, 787 ProgramLocalParameter4[df][v]ARB, GetProgramEnvParameter[df]vARB, 788 GetProgramLocalParameter[df]vARB, GetProgramivARB and 789 GetProgramStringARB. 790 791 FRAGMENT_PROGRAM_ARB 0x8804 792 793 Accepted by the <format> parameter of ProgramStringARB: 794 795 PROGRAM_FORMAT_ASCII_ARB 0x8875 796 797 Accepted by the <pname> parameter of GetProgramivARB: 798 799 PROGRAM_LENGTH_ARB 0x8627 800 PROGRAM_FORMAT_ARB 0x8876 801 PROGRAM_BINDING_ARB 0x8677 802 PROGRAM_INSTRUCTIONS_ARB 0x88A0 803 MAX_PROGRAM_INSTRUCTIONS_ARB 0x88A1 804 PROGRAM_NATIVE_INSTRUCTIONS_ARB 0x88A2 805 MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB 0x88A3 806 PROGRAM_TEMPORARIES_ARB 0x88A4 807 MAX_PROGRAM_TEMPORARIES_ARB 0x88A5 808 PROGRAM_NATIVE_TEMPORARIES_ARB 0x88A6 809 MAX_PROGRAM_NATIVE_TEMPORARIES_ARB 0x88A7 810 PROGRAM_PARAMETERS_ARB 0x88A8 811 MAX_PROGRAM_PARAMETERS_ARB 0x88A9 812 PROGRAM_NATIVE_PARAMETERS_ARB 0x88AA 813 MAX_PROGRAM_NATIVE_PARAMETERS_ARB 0x88AB 814 PROGRAM_ATTRIBS_ARB 0x88AC 815 MAX_PROGRAM_ATTRIBS_ARB 0x88AD 816 PROGRAM_NATIVE_ATTRIBS_ARB 0x88AE 817 MAX_PROGRAM_NATIVE_ATTRIBS_ARB 0x88AF 818 MAX_PROGRAM_LOCAL_PARAMETERS_ARB 0x88B4 819 MAX_PROGRAM_ENV_PARAMETERS_ARB 0x88B5 820 PROGRAM_UNDER_NATIVE_LIMITS_ARB 0x88B6 821 822 PROGRAM_ALU_INSTRUCTIONS_ARB 0x8805 823 PROGRAM_TEX_INSTRUCTIONS_ARB 0x8806 824 PROGRAM_TEX_INDIRECTIONS_ARB 0x8807 825 PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB 0x8808 826 PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB 0x8809 827 PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB 0x880A 828 MAX_PROGRAM_ALU_INSTRUCTIONS_ARB 0x880B 829 MAX_PROGRAM_TEX_INSTRUCTIONS_ARB 0x880C 830 MAX_PROGRAM_TEX_INDIRECTIONS_ARB 0x880D 831 MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB 0x880E 832 MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB 0x880F 833 MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB 0x8810 834 835 Accepted by the <pname> parameter of GetProgramStringARB: 836 837 PROGRAM_STRING_ARB 0x8628 838 839 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 840 GetFloatv, and GetDoublev: 841 842 PROGRAM_ERROR_POSITION_ARB 0x864B 843 CURRENT_MATRIX_ARB 0x8641 844 TRANSPOSE_CURRENT_MATRIX_ARB 0x88B7 845 CURRENT_MATRIX_STACK_DEPTH_ARB 0x8640 846 MAX_PROGRAM_MATRICES_ARB 0x862F 847 MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB 0x862E 848 849 MAX_TEXTURE_COORDS_ARB 0x8871 850 MAX_TEXTURE_IMAGE_UNITS_ARB 0x8872 851 852 Accepted by the <name> parameter of GetString: 853 854 PROGRAM_ERROR_STRING_ARB 0x8874 855 856 Accepted by the <mode> parameter of MatrixMode: 857 858 MATRIX0_ARB 0x88C0 859 MATRIX1_ARB 0x88C1 860 MATRIX2_ARB 0x88C2 861 MATRIX3_ARB 0x88C3 862 MATRIX4_ARB 0x88C4 863 MATRIX5_ARB 0x88C5 864 MATRIX6_ARB 0x88C6 865 MATRIX7_ARB 0x88C7 866 MATRIX8_ARB 0x88C8 867 MATRIX9_ARB 0x88C9 868 MATRIX10_ARB 0x88CA 869 MATRIX11_ARB 0x88CB 870 MATRIX12_ARB 0x88CC 871 MATRIX13_ARB 0x88CD 872 MATRIX14_ARB 0x88CE 873 MATRIX15_ARB 0x88CF 874 MATRIX16_ARB 0x88D0 875 MATRIX17_ARB 0x88D1 876 MATRIX18_ARB 0x88D2 877 MATRIX19_ARB 0x88D3 878 MATRIX20_ARB 0x88D4 879 MATRIX21_ARB 0x88D5 880 MATRIX22_ARB 0x88D6 881 MATRIX23_ARB 0x88D7 882 MATRIX24_ARB 0x88D8 883 MATRIX25_ARB 0x88D9 884 MATRIX26_ARB 0x88DA 885 MATRIX27_ARB 0x88DB 886 MATRIX28_ARB 0x88DC 887 MATRIX29_ARB 0x88DD 888 MATRIX30_ARB 0x88DE 889 MATRIX31_ARB 0x88DF 890 891 892Additions to Chapter 2 of the OpenGL 1.3 Specification (OpenGL 893Operation) 894 895 Modify Section 2.1.1, Floating-Point Computation (p. 6) 896 897 (modify first paragraph, p. 6) ... The maximum representable 898 magnitude of a floating-point number used to represent position, 899 normal, or texture coordinates must be at least 2^32; the maximum 900 representable magnitude for colors must be at least 2^10. ... 901 902 903 Modify Section 2.7, Vertex Specification (p. 19) 904 905 (modify second paragraph, p. 20) Implementations support more than 906 one set of texture coordinates. The commands 907 908 void MultiTexCoord{1234}{sifd}(enum texture, T coords); 909 void MultiTexCoord{1234}{sifd}v(enum texture, T coords); 910 911 take the coordinate set to be modified as the <texture> parameter. 912 <texture> is a symbolic constant of the form TEXTUREi, indicating 913 that texture coordinate set i is to be modified. The constants obey 914 TEXTUREi = TEXTURE0 + i (i is in the range 0 to k-1, where k is the 915 implementation-dependent number of texture units defined by 916 MAX_TEXTURE_COORDS_ARB). 917 918 919 Modify Section 2.8, Vertex Arrays (p. 21) 920 921 (modify first paragraph, p. 21) ... The client may specify up to 5 922 plus the value of MAX_TEXTURE_COORDS_ARB arrays: one each to store 923 vertex coordinates... 924 925 926 (modify first paragraph, p. 23) The command 927 928 void ClientActiveTexture(enum texture); 929 930 is used to select the vertex array client state parameters to be 931 modified by the TexCoordPointer command and the array affected by 932 EnableClientState and DisableClientState with parameter 933 TEXTURE_COORD_ARRAY. This command sets the client state variable 934 CLIENT_ACTIVE_TEXTURE. Each texture coordinate set has a client 935 state vector which is selected when this command is invoked. This 936 state vector includes the vertex array state. This call also 937 selects the texture coordinate set state used for queries of client 938 state. 939 940 941 (modify first paragraph, p. 28) If the number of supported texture 942 coordinate sets (the value of MAX_TEXTURE_COORDS_ARB) is k, ... 943 944 945 Modify Section 2.10.2, Matrices (p. 31) 946 947 (modify first paragraph, p. 31) The projection matrix and model-view 948 matrix are set and modified with a variety of commands. The 949 affected matrix is determined by the current matrix mode. The 950 current matrix mode is set with 951 952 void MatrixMode(enum mode); 953 954 which takes one of the pre-defined constants TEXTURE, MODELVIEW, 955 COLOR, PROJECTION, or MATRIX<i>_ARB as the argument. In the case of 956 MATRIX<i>_ARB, <i> is an integer between 0 and <n>-1 indicating one 957 of <n> program matrices where <n> is the value of the implementation 958 defined constant MAX_PROGRAM_MATRICES_ARB. Such program matrices 959 are described in section 3.11.7. TEXTURE is described later in 960 section 2.10.2, and COLOR is described in section 3.6.3. If the 961 current matrix mode is MODELVIEW, then matrix operations apply to 962 the model-view matrix; if PROJECTION, then they apply to the 963 projection matrix. 964 965 966 (modify first paragraph, p. 34) For each texture coordinate set, a 967 4x4 matrix is applied to the corresponding texture coordinates... 968 969 970 (modify first and second paragraphs, p. 35) The command 971 972 void ActiveTexture(enum texture); 973 974 specifies the active texture unit selector, ACTIVE_TEXTURE. Each 975 texture unit contains up to two distinct sub-units: a texture 976 coordinate processing unit (consisting of a texture matrix stack and 977 texture coordinate generation state) and a texture image unit 978 (consisting of all the texture state defined in Section 3.8). In 979 implementations with a different number of supported texture 980 coordinate sets and texture image units, some texture units may 981 consist of only one of the two sub-units. 982 983 The active texture unit selector specifies the texture coordinate 984 set accessed by commands involving texture coordinate processing. 985 Such commands include those accessing the current matrix stack (if 986 MATRIX_MODE is TEXTURE), TexGen (section 2.10.4), Enable/Disable (if 987 any texture coordinate generation enum is selected), as well as 988 queries of the current texture coordinates and current raster 989 texture coordinates. If the texture coordinate set number 990 corresponding to the current value of ACTIVE_TEXTURE is greater than 991 or equal to the implementation-dependent constant 992 MAX_TEXTURE_COORDS_ARB, the error INVALID_OPERATION is generated by 993 any such command. 994 995 The active texture unit selector also selects the texture image unit 996 accessed by commands involving texture image processing (section 997 3.8). Such commands include all variants of TexEnv, TexParameter, 998 and TexImage commands, BindTexture, Enable/Disable for any texture 999 target (e.g., TEXTURE_2D), and queries of all such state. If the 1000 texture image unit number corresponding to the current value of 1001 ACTIVE_TEXTURE is greater than or equal to the implementation- 1002 dependent constant MAX_TEXTURE_IMAGE_UNITS_ARB, the error 1003 INVALID_OPERATION is generated by any such command. 1004 1005 ActiveTexture generates the error INVALID_ENUM if an invalid 1006 <texture> is specified. <texture> is a symbolic constant of the 1007 form TEXTUREi, indicating that texture unit i is to be modified. 1008 The constants obey TEXTUREi = TEXTURE0 + i (i is in the range 0 to 1009 k-1, where k is the larger of the MAX_TEXTURE_COORDS_ARB and 1010 MAX_TEXTURE_IMAGE_UNITS_ARB). For compatibility with old OpenGL 1011 specifications, the implementation-dependent constant 1012 MAX_TEXTURE_UNITS specifies the number of conventional texture units 1013 supported by the implementation. Its value must be no larger than 1014 the minimum of MAX_TEXTURE_COORDS_ARB and 1015 MAX_TEXTURE_IMAGE_UNITS_ARB. 1016 1017 1018 (modify last paragraph, p. 35) The state required to implement 1019 transformations consists of a <n>-value integer indicating the 1020 current matrix mode (where <n> is 4 + the number of supported 1021 texture and program matrices), a stack of at least two 4x4 matrices 1022 for each of COLOR, PROJECTION, and TEXTURE with associated stack 1023 pointers, <n> stacks (where <n> is at least 8) of at least one 4x4 1024 matrix for each MATRIX<i>_ARB with associated stack pointers, and a 1025 stack of at least 32 4x4 matrices with an associated stack pointer 1026 for MODELVIEW. Initially, there is only one matrix on each stack, 1027 and all matrices are set to the identity. The initial matrix mode 1028 is MODELVIEW. The initial value of ACTIVE_TEXTURE is TEXTURE0. 1029 1030 1031Additions to Chapter 3 of the OpenGL 1.3 Specification (Rasterization) 1032 1033 Modify Chapter 3, Introduction (p. 58) 1034 1035 (modify first paragraph, p. 58) ... Figure 3.1 diagrams the 1036 rasterization process. The color value assigned to a fragment is 1037 initially determined by the rasterization operations (sections 3.3 1038 through 3.7) and modified by either the execution of the texturing, 1039 color sum, and fog operations as defined in sections 3.8, 3.9, and 1040 3.10, or of a fragment program defined in section 3.11. The final 1041 depth value is initially determined by the rasterization operations 1042 and may be modified or replaced by a fragment program. 1043 1044 (modify Figure 3.1) 1045 1046 _ +---------------+ FRAGMENT_PROGRAM_ARB 1047 /|| Point | enable 1048 / | Rasterization |\ | 1049 / +---------------+ \ V o-------------+ 1050 From / +---------------+ \ | 1051 Primitive ---> | Line |---+++--->o o | 1052 Assembly \ | Rasterization | / || | | 1053 \ +---------------+ / || | | 1054 \ +---------------+/ || +-----+-----+ +----+-----+ 1055 \|| Polygon | || | Texturing | | Fragment | 1056 - | Rasterization | / | +-----+-----+ | Program | 1057 +---------------+ / | | +----+-----+ 1058 +---------------+ / | +-----+-----+ | 1059 | Pixel |/ | | Color Sum | | 1060 DrawPixels --> | Rectangle | / +-----+-----+ | 1061 | Rasterization | / | V 1062 +---------------+ / +-----+-----+ 1063 +---------------+ / | Fog |---> Fragments 1064 Bitmap ----> | Bitmap |/ +-----------+ 1065 | Rasterization | 1066 +---------------+ 1067 1068 1069 Modify Section 3.3, Points (p. 63) 1070 1071 (modify first and second paragraphs, p. 64) All fragments produced 1072 in rasterizing a non-antialiased point are assigned the same 1073 associated data, which are those of the vertex corresponding to the 1074 point. (delete reference to divide by q) 1075 1076 If antialiasing is enabled, then ... The data associated with each 1077 fragment are otherwise the data associated with the point being 1078 rasterized. (delete reference to divide by q) 1079 1080 1081 Modify Section 3.4.1, Basic Line Segment Rasterization (p. 66) 1082 1083 (modify first paragraph, p. 68) ... (Note that t=0 at p_a and t=1 at 1084 p_b). The value of an associated datum f from the fragment center, 1085 whether it be R, G, B, or A (in RGBA mode) or a color index (in 1086 color index mode) or the s, t, r, or q texture coordinate or the 1087 clip w coordinate (the depth value, window z, must be found using 1088 equation 3.3, below), is found as 1089 1090 f = (1-t)*(f_a/w_a) + t*(f_b/w_b) (3.2) 1091 ----------------------------- 1092 (1-t)*(1/w_a) + t*(1/w_b) 1093 1094 where f_a and f_b are the data associated with the starting and 1095 ending endpoints of the segment, respectively; w_a and w_b are the 1096 clip w coordinates of the starting and ending endpoints of the 1097 segments, respectively. Note that linear interpolation would use 1098 1099 f = (1-t)*f_a + t*f_b. (3.3) 1100 1101 ... A GL implementation may choose to approximate equation 3.2 with 1102 3.3, but this will normally lead to inacceptable distortion effects 1103 when interpolating texture coordinates or clip w coordinates. 1104 1105 1106 Modify Section 3.5.1, Basic Polygon Rasterization (p. 73) 1107 1108 (modify third and fourth paragraphs, p. 74) Denote a datum at p_a, 1109 p_b, or p_c as f_a, f_b, or f_c, respectively. Then the value f of 1110 a datum at a fragment produced by rasterizing a triangle is given by 1111 1112 f = a*(f_a/w_a) + b*(f_b/w_b) + c*(f_c/w_c) (3.4) 1113 --------------------------------------- 1114 a*(1/w_a) + b*(1/w_b) + c*(1/w_c) 1115 1116 where w_a, w_b, and w_c are the clip w coordinates of p_a, p_b, and 1117 p_c, respectively. a, b, and c are the barycentric coordinates of 1118 the fragment for which the data are produced. a, b, and c must 1119 correspond precisely to the ... at the fragment's center. 1120 1121 Just as with line segment rasterization, equation 3.4 may be 1122 approximated by 1123 1124 f = a*f_a + b*f_b + c*f_c; 1125 1126 this may yield ... for texture coordinates or clip w coordinates. 1127 1128 1129 Modify Section 3.6.4, Rasterization of Pixel Rectangles (p. 91) 1130 1131 (modify third paragraph, p. 103) A fragment arising from a group ... 1132 the color and texture coordinates are given by those associated with 1133 the current raster position. (delete reference to divide by q) 1134 Groups arising from DrawPixels... 1135 1136 1137 Modify Section 3.7, Bitmaps (p. 113) 1138 1139 (modify third paragraph, p. 114) Otherwise, a rectangular array ... 1140 The associated data for each fragment are those associated with the 1141 current raster position. (delete reference to divide by q) Once 1142 the fragments have been produced ... 1143 1144 1145 Modify Section 3.8, Texturing (p. 115) 1146 1147 (add new paragraphs before first paragraph, p. 115) Texture 1148 coordinate sets are mapped to RGBA colors for application to 1149 primitives in one of two modes. The first mode, described in this 1150 and subsequent sections, is GL's conventional multitexture pipeline, 1151 describing texture environment and texture application. The second 1152 mode, referred to as fragment program mode and described in section 1153 3.11, applies textures, color sum, and fog as specified in an 1154 application-supplied fragment program. 1155 1156 The fragment program mode is enabled and disabled using the generic 1157 Enable and Disable commands, respectively, with the symbolic 1158 constant FRAGMENT_PROGRAM_ARB. The required state is one bit 1159 indicating whether the fragment program mode is enabled or disabled. 1160 In the initial state, the fragment program mode is disabled. When 1161 fragment program mode is enabled, texturing, color sum, and fog 1162 application stages are ignored and a general purpose program is 1163 executed instead. 1164 1165 (modify first and second paragraph, p. 115) Conventional texturing 1166 is employed when fragment program mode is disabled. Texturing maps 1167 ... color of an image at the location indicated by a fragment's 1168 texture coordinates to modify the fragment's primary RGBA color. 1169 Texturing does not affect the secondary color. 1170 1171 An implementation may support texturing using more than one image at 1172 a time. In this case the fragment carries multiple sets of texture 1173 coordinates which are used to index ... 1174 1175 (add paragraph before 1st paragraph, p. 116) Except when in fragment 1176 program mode (section 3.11), the (s,t,r) texture coordinates used 1177 for texturing are the values s/q, t/q, and r/q, respectively, where 1178 s, t, r, and q are the texture coordinates associated with the 1179 fragment. When in fragment program mode, the (s,t,r) texture 1180 coordinates are specified by the program. If q is less than or 1181 equal to zero, the results of texturing are undefined. 1182 1183 1184 Modify Section 3.8.7, Texture Minification (p. 135) 1185 1186 (add new paragraph after first paragraph, p. 137) When fragment 1187 program mode is enabled, the derivatives of the coordinates may be 1188 ill-defined or non-existent. As a result, the implementation is 1189 free to approximate these derivatives with such techniques as 1190 differencing. The only requirement is that texture samples be 1191 equivalent across the two modes. In other words, the texture sample 1192 chosen for a fragment of a primitive must be invariant between 1193 fragment program mode and conventional mode subject to the rules 1194 set forth in Appendix A, Invariance. 1195 1196 1197 Modify Section 3.8.13, Texture Application (p. 149) 1198 1199 (modify fourth paragraph, p. 152) Texturing is enabled and disabled 1200 individually for each texture unit. If texturing is disabled for 1201 one of the units, then the fragment resulting from the previous unit 1202 is passed unaltered to the following unit. Individual texture units 1203 beyond those specified by MAX_TEXTURE_UNITS may be incomplete and 1204 are always treated as disabled. 1205 1206 1207 Insert a new Section 3.11, (p. 154), between existing sections 3.10 1208 and 3.11. Renumber 3.11, Antialiasing Application, to 3.12. 1209 1210 3.11 Fragment Programs 1211 1212 The conventional GL texturing model described in section 3.8 is a 1213 configurable but essentially hard-wired sequence of per-fragment 1214 computations based on a canonical set of per-fragment parameters 1215 and texturing-related state such as texture images, texture 1216 parameters, and texture environment parameters. The general success 1217 and utility of the conventional GL texturing model reflects its 1218 basic correspondence to the typical texturing requirements of 3D 1219 applications. 1220 1221 However when the conventional GL texturing model is not sufficient, 1222 the fragment program mode provides a substantially more flexible 1223 model for generating fragment colors. The fragment program mode 1224 permits applications to define their own fragment programs. 1225 1226 A fragment program is a character string that specifies a sequence 1227 of operations to perform. Fragment program instructions are 1228 typically 4-component vector operations that operate on per-fragment 1229 attributes and program parameters. Fragment programs execute on a 1230 per-fragment basis and operate on each fragment completely 1231 independently from any other fragments. Fragment programs execute a 1232 finite fixed sequence of instructions with no branching or looping. 1233 Fragment programs execute without data hazards so results computed 1234 in one instruction can be used immediately afterwards. The result 1235 of a fragment program is a set of fragment result registers that 1236 becomes the color used by antialiasing application and/or a depth 1237 value used in place of the interpolated depth value generated by 1238 conventional rasterization. 1239 1240 In fragment program mode, the color sum is subsumed by the fragment 1241 program. An application desiring the primary and secondary colors 1242 to be summed must explicitly include this operation in its program. 1243 1244 Fragment programs are defined to operate only in RGBA mode. The 1245 results of fragment program execution are undefined if the GL is in 1246 color index mode. 1247 1248 1249 3.11.1 Program Objects 1250 1251 The GL provides one or more program targets, each identifying a 1252 portion of the GL that can be controlled through application- 1253 specified programs. The program target for fragment programs is 1254 FRAGMENT_PROGRAM_ARB. Each program target has an associated program 1255 object, called the current program object. Each program target also 1256 has a default program object, which is initially the current program 1257 object. 1258 1259 Each program object has an associated program string. The command 1260 1261 ProgramStringARB(enum target, enum format, sizei len, 1262 const void *string); 1263 1264 updates the program string for the current program object for 1265 <target>. <format> describes the format of the program string, 1266 which must currently be PROGRAM_FORMAT_ASCII_ARB. <string> is a 1267 pointer to the array of bytes representing the program string being 1268 loaded, which need not be null-terminated. The length of the array 1269 is given by <len>. If <string> is null-terminated, <len> should not 1270 include the terminator. 1271 1272 When a program string is loaded, it is interpreted according to 1273 syntactic and semantic rules corresponding to the program target 1274 specified by <target>. If a program violates the syntactic or 1275 semantic restrictions of the program target, ProgramStringARB 1276 generates the error INVALID_OPERATION. An implementation may also 1277 generate the error INVALID_OPERATION if the program would exceed 1278 the native resource limits defined in section 6.1.12. A program 1279 which fails to load due to exceeding native resource limits must 1280 always fail, regardless of any other GL state. 1281 1282 Additionally, ProgramString will update the program error position 1283 (PROGRAM_ERROR_POSITION_ARB) and error string 1284 (PROGRAM_ERROR_STRING_ARB). If a program fails to load, the value 1285 of the program error position is set to the ubyte offset into the 1286 specified program string indicating where the first program error 1287 was detected. If the program fails to load because of a semantic 1288 restriction that is not detected until the program is fully 1289 scanned, the error position is set to the value of <len>. If a 1290 program loads successfully, the error position is set to the value 1291 negative one. The implementation-dependent program error string 1292 contains one or more error or warning messages. If a program loads 1293 succesfully, the error string may either contain warning messages or 1294 be empty. 1295 1296 Each program object has an associated array of program local 1297 parameters. The number and type of program local parameters is 1298 target- and implementation-dependent. For fragment programs, 1299 program local parameters are four-component floating-point vectors. 1300 The number of vectors is given by the implementation-dependent 1301 constant MAX_PROGRAM_LOCAL_PARAMETERS_ARB, which must be at least 1302 24. The commands 1303 1304 void ProgramLocalParameter4fARB(enum target, uint index, 1305 float x, float y, float z, float w); 1306 void ProgramLocalParameter4fvARB(enum target, uint index, 1307 const float *params); 1308 void ProgramLocalParameter4dARB(enum target, uint index, 1309 double x, double y, double z, double w); 1310 void ProgramLocalParameter4dvARB(enum target, uint index, 1311 const double *params); 1312 1313 update the values of the program local parameter numbered <index> 1314 belonging to the program object currently bound to <target>. For 1315 ProgramLocalParameter4fARB and ProgramLocalParameter4dARB, the four 1316 components of the parameter are updated with the values of <x>, <y>, 1317 <z>, and <w>, respectively. For ProgramLocalParameter4fvARB and 1318 ProgramLocalParameter4dvARB, the four components of the parameter 1319 are updated with the array of four values pointed to by <params>. 1320 The error INVALID_VALUE is generated if <index> is greater than or 1321 equal to the number of program local parameters supported by 1322 <target>. 1323 1324 Additionally, each program target has an associated array of program 1325 environment parameters. Unlike program local parameters, program 1326 environment parameters are shared by all program objects of a given 1327 target. The number and type of program environment parameters is 1328 target- and implementation-dependent. For fragment programs, 1329 program environment parameters are four-component floating-point 1330 vectors. The number of vectors is given by the implementation- 1331 dependent constant MAX_PROGRAM_ENV_PARAMETERS_ARB, which must be at 1332 least 24. The commands 1333 1334 void ProgramEnvParameter4fARB(enum target, uint index, 1335 float x, float y, float z, float w); 1336 void ProgramEnvParameter4fvARB(enum target, uint index, 1337 const float *params); 1338 void ProgramEnvParameter4dARB(enum target, uint index, 1339 double x, double y, double z, double w); 1340 void ProgramEnvParameter4dvARB(enum target, uint index, 1341 const double *params); 1342 1343 update the values of the program environment parameter numbered 1344 <index> for the given program target <target>. For 1345 ProgramEnvParameter4fARB and ProgramEnvParameter4dARB, the four 1346 components of the parameter are updated with the values of <x>, <y>, 1347 <z>, and <w>, respectively. For ProgramEnvParameter4fvARB and 1348 ProgramEnvParameter4dvARB, the four components of the parameter are 1349 updated with the array of four values pointed to by <params>. The 1350 error INVALID_VALUE is generated if <index> is greater than or equal 1351 to the number of program environment parameters supported by 1352 <target>. 1353 1354 Each program target has a default program object. Additionally, 1355 named program objects can be created and operated upon. The name 1356 space for program objects is the positive integers and is shared by 1357 programs of all targets. The name zero is reserved by the GL. 1358 1359 A named program object is created by binding an unused program 1360 object name to a valid program target. The binding is effected by 1361 calling 1362 1363 BindProgramARB(enum target, uint program); 1364 1365 with <target> set to the desired program target and <program> set to 1366 the unused program name. The resulting program object has a program 1367 target given by <target> and is assigned target-specific default 1368 values (see section 3.11.8 for fragment programs). BindProgramARB 1369 may also be used to bind an existing program object to a program 1370 target. If <program> is zero, the default program object for 1371 <target> is bound. If <program> is the name of an existing program 1372 object whose associated program target is <target>, the named 1373 program object is bound. The error INVALID_OPERATION is generated 1374 if <program> names an existing program object whose associated 1375 program target is anything other than <target>. 1376 1377 Programs objects are deleted by calling 1378 1379 void DeleteProgramsARB(sizei n, const uint *programs); 1380 1381 <programs> contains <n> names of programs to be deleted. After a 1382 program object is deleted, its name is again unused. If a program 1383 object that is bound to any target is deleted, it is as though 1384 BindProgramARB is first executed with same target and a <program> of 1385 zero. Unused names in <programs> are silently ignored, as is the 1386 value zero. 1387 1388 The command 1389 1390 void GenProgramsARB(sizei n, uint *programs); 1391 1392 returns <n> currently unused program names in <programs>. These 1393 names are marked as used, for the purposes of GenProgramsARB only, 1394 but objects are created only when they are first bound using 1395 BindProgramARB. 1396 1397 1398 3.11.2 Fragment Program Grammar and Semantic Restrictions 1399 1400 Fragment program strings are specified as an array of ASCII 1401 characters containing the program text. When a fragment program is 1402 loaded by a call to ProgramStringARB, the program string is parsed 1403 into a set of tokens possibly separated by whitespace. Spaces, 1404 tabs, newlines, carriage returns, and comments are considered 1405 whitespace. Comments begin with the character "#" and are 1406 terminated by a newline, a carriage return, or the end of the 1407 program array. 1408 1409 The Backus-Naur Form (BNF) grammar below specifies the syntactically 1410 valid sequences for fragment programs. The set of valid tokens can 1411 be inferred from the grammar. The token "" represents an empty 1412 string and is used to indicate optional rules. A program is invalid 1413 if it contains any undefined tokens or characters. 1414 1415 A fragment program is required to begin with the header string 1416 "!!ARBfp1.0", without any preceding whitespace. This string 1417 identifies the subsequent program text as a fragment program 1418 (version 1.0) that should be parsed according to the following 1419 grammar and semantic rules. Program string parsing begins with the 1420 character immediately following the header string. 1421 1422 <program> ::= <optionSequence> <statementSequence> "END" 1423 1424 <optionSequence> ::= <optionSequence> <option> 1425 | "" 1426 1427 <option> ::= "OPTION" <identifier> ";" 1428 1429 <statementSequence> ::= <statementSequence> <statement> 1430 | "" 1431 1432 <statement> ::= <instruction> ";" 1433 | <namingStatement> ";" 1434 1435 <instruction> ::= <ALUInstruction> 1436 | <TexInstruction> 1437 1438 <ALUInstruction> ::= <VECTORop_instruction> 1439 | <SCALARop_instruction> 1440 | <BINSCop_instruction> 1441 | <BINop_instruction> 1442 | <TRIop_instruction> 1443 | <SWZ_instruction> 1444 1445 <TexInstruction> ::= <SAMPLE_instruction> 1446 | <KIL_instruction> 1447 1448 <VECTORop_instruction> ::= <VECTORop> <maskedDstReg> "," 1449 <vectorSrcReg> 1450 1451 <VECTORop> ::= "ABS" | "ABS_SAT" 1452 | "FLR" | "FLR_SAT" 1453 | "FRC" | "FRC_SAT" 1454 | "LIT" | "LIT_SAT" 1455 | "MOV" | "MOV_SAT" 1456 1457 <SCALARop_instruction> ::= <SCALARop> <maskedDstReg> "," 1458 <scalarSrcReg> 1459 1460 <SCALARop> ::= "COS" | "COS_SAT" 1461 | "EX2" | "EX2_SAT" 1462 | "LG2" | "LG2_SAT" 1463 | "RCP" | "RCP_SAT" 1464 | "RSQ" | "RSQ_SAT" 1465 | "SIN" | "SIN_SAT" 1466 | "SCS" | "SCS_SAT" 1467 1468 <BINSCop_instruction> ::= <BINSCop> <maskedDstReg> "," 1469 <scalarSrcReg> "," <scalarSrcReg> 1470 1471 <BINSCop> ::= "POW" | "POW_SAT" 1472 1473 <BINop_instruction> ::= <BINop> <maskedDstReg> "," 1474 <vectorSrcReg> "," <vectorSrcReg> 1475 1476 <BINop> ::= "ADD" | "ADD_SAT" 1477 | "DP3" | "DP3_SAT" 1478 | "DP4" | "DP4_SAT" 1479 | "DPH" | "DPH_SAT" 1480 | "DST" | "DST_SAT" 1481 | "MAX" | "MAX_SAT" 1482 | "MIN" | "MIN_SAT" 1483 | "MUL" | "MUL_SAT" 1484 | "SGE" | "SGE_SAT" 1485 | "SLT" | "SLT_SAT" 1486 | "SUB" | "SUB_SAT" 1487 | "XPD" | "XPD_SAT" 1488 1489 <TRIop_instruction> ::= <TRIop> <maskedDstReg> "," 1490 <vectorSrcReg> "," <vectorSrcReg> "," 1491 <vectorSrcReg> 1492 1493 <TRIop> ::= "CMP" | "CMP_SAT" 1494 | "LRP" | "LRP_SAT" 1495 | "MAD" | "MAD_SAT" 1496 1497 <SWZ_instruction> ::= <SWZop> <maskedDstReg> "," 1498 <srcReg> "," <extendedSwizzle> 1499 1500 <SWZop> ::= "SWZ" | "SWZ_SAT" 1501 1502 <SAMPLE_instruction> ::= <SAMPLEop> <maskedDstReg> "," 1503 <vectorSrcReg> "," <texImageUnit> "," 1504 <texTarget> 1505 1506 <SAMPLEop> ::= "TEX" | "TEX_SAT" 1507 | "TXP" | "TXP_SAT" 1508 | "TXB" | "TXB_SAT" 1509 1510 <KIL_instruction> ::= "KIL" <vectorSrcReg> 1511 1512 <texImageUnit> ::= "texture" <optTexImageUnitNum> 1513 1514 <texTarget> ::= "1D" 1515 | "2D" 1516 | "3D" 1517 | "CUBE" 1518 | "RECT" 1519 1520 <optTexImageUnitNum> ::= "" 1521 | "[" <texImageUnitNum> "]" 1522 1523 <texImageUnitNum> ::= <integer> from 0 to 1524 MAX_TEXTURE_IMAGE_UNITS_ARB-1 1525 1526 <scalarSrcReg> ::= <optionalSign> <srcReg> <scalarSuffix> 1527 1528 <vectorSrcReg> ::= <optionalSign> <srcReg> <optionalSuffix> 1529 1530 <maskedDstReg> ::= <dstReg> <optionalMask> 1531 1532 <extendedSwizzle> ::= <xyzwExtendedSwizzle> 1533 | <rgbaExtendedSwizzle> 1534 1535 <xyzwExtendedSwizzle> ::= <xyzwExtSwizComp> "," <xyzwExtSwizComp> "," 1536 <xyzwExtSwizComp> "," <xyzwExtSwizComp> 1537 1538 <rgbaExtendedSwizzle> ::= <rgbaExtSwizComp> "," <rgbaExtSwizComp> "," 1539 <rgbaExtSwizComp> "," <rgbaExtSwizComp> 1540 1541 <xyzwExtSwizComp> ::= <optionalSign> <xyzwExtSwizSel> 1542 1543 <rgbaExtSwizComp> ::= <optionalSign> <rgbaExtSwizSel> 1544 1545 <xyzwExtSwizSel> ::= "0" 1546 | "1" 1547 | <xyzwComponent> 1548 1549 <rgbaExtSwizSel> ::= "0" 1550 | "1" 1551 | <rgbaComponent> 1552 1553 <srcReg> ::= <fragmentAttribReg> 1554 | <temporaryReg> 1555 | <progParamReg> 1556 1557 <dstReg> ::= <temporaryReg> 1558 | <fragmentResultReg> 1559 1560 <fragmentAttribReg> ::= <establishedName> 1561 | <fragAttribBinding> 1562 1563 <temporaryReg> ::= <establishedName> 1564 1565 <progParamReg> ::= <progParamSingle> 1566 | <progParamArray> "[" <progParamArrayAbs> "]" 1567 | <paramSingleItemUse> 1568 1569 <progParamSingle> ::= <establishedName> 1570 1571 <progParamArray> ::= <establishedName> 1572 1573 <progParamArrayAbs> ::= <integer> 1574 1575 <fragmentResultReg> ::= <establishedName> 1576 | <resultBinding> 1577 1578 <scalarSuffix> ::= "." <component> 1579 1580 <optionalSuffix> ::= "" 1581 | "." <component> 1582 | "." <xyzwComponent> <xyzwComponent> 1583 <xyzwComponent> <xyzwComponent> 1584 | "." <rgbaComponent> <rgbaComponent> 1585 <rgbaComponent> <rgbaComponent> 1586 1587 <component> ::= <xyzwComponent> 1588 | <rgbaComponent> 1589 1590 <xyzwComponent> ::= "x" | "y" | "z" | "w" 1591 1592 <rgbaComponent> ::= "r" | "g" | "b" | "a" 1593 1594 <optionalMask> ::= "" 1595 | <xyzwMask> 1596 | <rgbaMask> 1597 1598 <xyzwMask> ::= "." "x" 1599 | "." "y" 1600 | "." "xy" 1601 | "." "z" 1602 | "." "xz" 1603 | "." "yz" 1604 | "." "xyz" 1605 | "." "w" 1606 | "." "xw" 1607 | "." "yw" 1608 | "." "xyw" 1609 | "." "zw" 1610 | "." "xzw" 1611 | "." "yzw" 1612 | "." "xyzw" 1613 1614 <rgbaMask> ::= "." "r" 1615 | "." "g" 1616 | "." "rg" 1617 | "." "b" 1618 | "." "rb" 1619 | "." "gb" 1620 | "." "rgb" 1621 | "." "a" 1622 | "." "ra" 1623 | "." "ga" 1624 | "." "rga" 1625 | "." "ba" 1626 | "." "rba" 1627 | "." "gba" 1628 | "." "rgba" 1629 1630 <namingStatement> ::= <ATTRIB_statement> 1631 | <PARAM_statement> 1632 | <TEMP_statement> 1633 | <OUTPUT_statement> 1634 | <ALIAS_statement> 1635 1636 <ATTRIB_statement> ::= "ATTRIB" <establishName> "=" 1637 <fragAttribBinding> 1638 1639 <fragAttribBinding> ::= "fragment" "." <fragAttribItem> 1640 1641 <fragAttribItem> ::= "color" <optColorType> 1642 | "texcoord" <optTexCoordNum> 1643 | "fogcoord" 1644 | "position" 1645 1646 <PARAM_statement> ::= <PARAM_singleStmt> 1647 | <PARAM_multipleStmt> 1648 1649 <PARAM_singleStmt> ::= "PARAM" <establishName> <paramSingleInit> 1650 1651 <PARAM_multipleStmt> ::= "PARAM" <establishName> "[" <optArraySize> "]" 1652 <paramMultipleInit> 1653 1654 <optArraySize> ::= "" 1655 | <integer> from 1 to MAX_PROGRAM_PARAMETERS_ARB 1656 (maximum number of allowed program 1657 parameter bindings) 1658 1659 <paramSingleInit> ::= "=" <paramSingleItemDecl> 1660 1661 <paramMultipleInit> ::= "=" "{" <paramMultInitList> "}" 1662 1663 <paramMultInitList> ::= <paramMultipleItem> 1664 | <paramMultipleItem> "," <paramMultInitList> 1665 1666 <paramSingleItemDecl> ::= <stateSingleItem> 1667 | <programSingleItem> 1668 | <paramConstDecl> 1669 1670 <paramSingleItemUse> ::= <stateSingleItem> 1671 | <programSingleItem> 1672 | <paramConstUse> 1673 1674 <paramMultipleItem> ::= <stateMultipleItem> 1675 | <programMultipleItem> 1676 | <paramConstDecl> 1677 1678 <stateMultipleItem> ::= <stateSingleItem> 1679 | "state" "." <stateMatrixRows> 1680 1681 <stateSingleItem> ::= "state" "." <stateMaterialItem> 1682 | "state" "." <stateLightItem> 1683 | "state" "." <stateLightModelItem> 1684 | "state" "." <stateLightProdItem> 1685 | "state" "." <stateTexEnvItem> 1686 | "state" "." <stateFogItem> 1687 | "state" "." <stateDepthItem> 1688 | "state" "." <stateMatrixRow> 1689 1690 <stateMaterialItem> ::= "material" <optFaceType> "." <stateMatProperty> 1691 1692 <stateMatProperty> ::= "ambient" 1693 | "diffuse" 1694 | "specular" 1695 | "emission" 1696 | "shininess" 1697 1698 <stateLightItem> ::= "light" "[" <stateLightNumber> "]" "." 1699 <stateLightProperty> 1700 1701 <stateLightProperty> ::= "ambient" 1702 | "diffuse" 1703 | "specular" 1704 | "position" 1705 | "attenuation" 1706 | "spot" "." <stateSpotProperty> 1707 | "half" 1708 1709 <stateSpotProperty> ::= "direction" 1710 1711 <stateLightModelItem> ::= "lightmodel" <stateLModProperty> 1712 1713 <stateLModProperty> ::= "." "ambient" 1714 | <optFaceType> "." "scenecolor" 1715 1716 <stateLightProdItem> ::= "lightprod" "[" <stateLightNumber> "]" 1717 <optFaceType> "." <stateLProdProperty> 1718 1719 <stateLProdProperty> ::= "ambient" 1720 | "diffuse" 1721 | "specular" 1722 1723 <stateLightNumber> ::= <integer> from 0 to MAX_LIGHTS-1 1724 1725 <stateTexEnvItem> ::= "texenv" <optLegacyTexUnitNum> "." 1726 <stateTexEnvProperty> 1727 1728 <stateTexEnvProperty> ::= "color" 1729 1730 <optLegacyTexUnitNum> ::= "" 1731 | "[" <legacyTexUnitNum> "]" 1732 1733 <legacyTexUnitNum> ::= <integer> from 0 to MAX_TEXTURE_UNITS-1 1734 1735 <stateFogItem> ::= "fog" "." <stateFogProperty> 1736 1737 <stateFogProperty> ::= "color" 1738 | "params" 1739 1740 <stateDepthItem> ::= "depth" "." <stateDepthProperty> 1741 1742 <stateDepthProperty> ::= "range" 1743 1744 <stateMatrixRow> ::= <stateMatrixItem> "." "row" "[" 1745 <stateMatrixRowNum> "]" 1746 1747 <stateMatrixRows> ::= <stateMatrixItem> <optMatrixRows> 1748 1749 <optMatrixRows> ::= "" 1750 | "." "row" "[" <stateMatrixRowNum> ".." 1751 <stateMatrixRowNum> "]" 1752 1753 <stateMatrixItem> ::= "matrix" "." <stateMatrixName> 1754 <stateOptMatModifier> 1755 1756 <stateOptMatModifier> ::= "" 1757 | "." <stateMatModifier> 1758 1759 <stateMatModifier> ::= "inverse" 1760 | "transpose" 1761 | "invtrans" 1762 1763 <stateMatrixRowNum> ::= <integer> from 0 to 3 1764 1765 <stateMatrixName> ::= "modelview" <stateOptModMatNum> 1766 | "projection" 1767 | "mvp" 1768 | "texture" <optTexCoordNum> 1769 | "palette" "[" <statePaletteMatNum> "]" 1770 | "program" "[" <stateProgramMatNum> "]" 1771 1772 <stateOptModMatNum> ::= "" 1773 | "[" <stateModMatNum> "]" 1774 1775 <stateModMatNum> ::= <integer> from 0 to MAX_VERTEX_UNITS_ARB-1 1776 1777 <optTexCoordNum> ::= "" 1778 | "[" <texCoordNum> "]" 1779 1780 <texCoordNum> ::= <integer> from 0 to MAX_TEXTURE_COORDS_ARB-1 1781 1782 <statePaletteMatNum> ::= <integer> from 0 to MAX_PALETTE_MATRICES_ARB-1 1783 1784 <stateProgramMatNum> ::= <integer> from 0 to MAX_PROGRAM_MATRICES_ARB-1 1785 1786 <programSingleItem> ::= <progEnvParam> 1787 | <progLocalParam> 1788 1789 <programMultipleItem> ::= <progEnvParams> 1790 | <progLocalParams> 1791 1792 <progEnvParams> ::= "program" "." "env" 1793 "[" <progEnvParamNums> "]" 1794 1795 <progEnvParamNums> ::= <progEnvParamNum> 1796 | <progEnvParamNum> ".." <progEnvParamNum> 1797 1798 <progEnvParam> ::= "program" "." "env" 1799 "[" <progEnvParamNum> "]" 1800 1801 <progLocalParams> ::= "program" "." "local" 1802 "[" <progLocalParamNums> "]" 1803 1804 <progLocalParamNums> ::= <progLocalParamNum> 1805 | <progLocalParamNum> ".." <progLocalParamNum> 1806 1807 <progLocalParam> ::= "program" "." "local" 1808 "[" <progLocalParamNum> "]" 1809 1810 <progEnvParamNum> ::= <integer> from 0 to 1811 MAX_PROGRAM_ENV_PARAMETERS_ARB - 1 1812 1813 <progLocalParamNum> ::= <integer> from 0 to 1814 MAX_PROGRAM_LOCAL_PARAMETERS_ARB - 1 1815 1816 <paramConstDecl> ::= <paramConstScalarDecl> 1817 | <paramConstVector> 1818 1819 <paramConstUse> ::= <paramConstScalarUse> 1820 | <paramConstVector> 1821 1822 <paramConstScalarDecl> ::= <signedFloatConstant> 1823 1824 <paramConstScalarUse> ::= <floatConstant> 1825 1826 <paramConstVector> ::= "{" <signedFloatConstant> "}" 1827 | "{" <signedFloatConstant> "," 1828 <signedFloatConstant> "}" 1829 | "{" <signedFloatConstant> "," 1830 <signedFloatConstant> "," 1831 <signedFloatConstant> "}" 1832 | "{" <signedFloatConstant> "," 1833 <signedFloatConstant> "," 1834 <signedFloatConstant> "," 1835 <signedFloatConstant> "}" 1836 1837 <signedFloatConstant> ::= <optionalSign> <floatConstant> 1838 1839 <floatConstant> ::= see text 1840 1841 <optionalSign> ::= "" 1842 | "-" 1843 | "+" 1844 1845 <TEMP_statement> ::= "TEMP" <varNameList> 1846 1847 <varNameList> ::= <establishName> 1848 | <establishName> "," <varNameList> 1849 1850 <OUTPUT_statement> ::= "OUTPUT" <establishName> "=" 1851 <resultBinding> 1852 1853 <resultBinding> ::= "result" "." "color" 1854 | "result" "." "depth" 1855 1856 <optFaceType> ::= "" 1857 | "." "front" 1858 | "." "back" 1859 1860 <optColorType> ::= "" 1861 | "." "primary" 1862 | "." "secondary" 1863 1864 <ALIAS_statement> ::= "ALIAS" <establishName> "=" 1865 <establishedName> 1866 1867 <establishName> ::= <identifier> 1868 1869 <establishedName> ::= <identifier> 1870 1871 <identifier> ::= see text 1872 1873 The <integer> rule matches an integer constant. The integer 1874 consists of a sequence of one or more digits ("0" through "9"). 1875 1876 The <floatConstant> rule matches a floating-point constant 1877 consisting of an integer part, a decimal point, a fraction part, an 1878 "e" or "E", and an optionally signed integer exponent. The integer 1879 and fraction parts both consist of a sequence of one or more digits 1880 ("0" through "9"). Either the integer part or the fraction parts 1881 (not both) may be missing; either the decimal point or the "e" (or 1882 "E") and the exponent (not both) may be missing. 1883 1884 The <identifier> rule matches a sequence of one or more letters ("A" 1885 through "Z", "a" through "z"), digits ("0" through "9), underscores 1886 ("_"), or dollar signs ("$"); the first character must not be a 1887 number. Upper and lower case letters are considered different 1888 (names are case-sensitive). The following strings are reserved 1889 keywords and may not be used as identifiers: 1890 1891 ABS, ABS_SAT, ADD, ADD_SAT, ALIAS, ATTRIB, CMP, CMP_SAT, COS, 1892 COS_SAT, DP3, DP3_SAT, DP4, DP4_SAT, DPH, DPH_SAT, DST, DST_SAT, 1893 END, EX2, EX2_SAT, FLR, FLR_SAT, FRC, FRC_SAT, KIL, LG2, 1894 LG2_SAT, LIT, LIT_SAT, LRP, LRP_SAT, MAD, MAD_SAT, MAX, MAX_SAT, 1895 MIN, MIN_SAT, MOV, MOV_SAT, MUL, MUL_SAT, OPTION, OUTPUT, PARAM, 1896 POW, POW_SAT, RCP, RCP_SAT, RSQ, RSQ_SAT, SIN, SIN_SAT, SCS, 1897 SCS_SAT, SGE, SGE_SAT, SLT, SLT_SAT, SUB, SUB_SAT, SWZ, SWZ_SAT, 1898 TEMP, TEX, TEX_SAT, TXB, TXB_SAT, TXP, TXP_SAT, XPD, XPD_SAT, 1899 fragment, program, result, state, and texture. 1900 1901 The error INVALID_OPERATION is generated if a fragment program fails 1902 to load because it is not syntactically correct or for one of the 1903 semantic restrictions described in the following sections. 1904 1905 A successfully loaded fragment program is parsed into a sequence of 1906 instructions. Each instruction is identified by its tokenized name. 1907 The operation of these instructions when executed is defined in 1908 section 3.11.5. 1909 1910 A successfully loaded program string replaces the program string 1911 previously loaded into the specified program object. If the 1912 OUT_OF_MEMORY error is generated by ProgramStringARB, no change is 1913 made to the previous contents of the current program object. 1914 1915 1916 3.11.3 Fragment Program Variables 1917 1918 Fragment programs may access a number of different variables during 1919 their execution. The following sections define the variables that 1920 can be declared and used by a fragment program. 1921 1922 Explicit variable declarations allow a fragment program to establish 1923 a variable name that can be used to refer to a specified resource in 1924 subsequent instructions. A fragment program will fail to load if it 1925 declares the same variable name more than once or if it refers to a 1926 variable name that has not been previously declared in the program 1927 string. 1928 1929 Implicit variable declarations allow a fragment program to use the 1930 name of certain available resources by name. 1931 1932 1933 3.11.3.1 Fragment Attributes 1934 1935 Fragment program attribute variables are a set of four-component 1936 floating-point vectors holding the attributes of the fragment being 1937 processed. Fragment attribute variables are read-only during 1938 fragment program execution. 1939 1940 Fragment attribute variables can be declared explicitly using the 1941 <ATTRIB_statement> grammar rule, or implicitly using the 1942 <fragAttribBinding> grammar rule in an executable instruction. 1943 1944 Each fragment attribute variable is bound to a single item of 1945 fragment state according to the <fragAttrBinding> grammar rule. The 1946 set of GL state that can be bound to a fragment attribute variable 1947 is given in Table X.1. Fragment attribute variables are initialized 1948 at each fragment program invocation with the current values of the 1949 bound state. 1950 1951 Fragment Attribute Binding Components Underlying State 1952 -------------------------- ---------- ---------------------------- 1953 fragment.color (r,g,b,a) primary color 1954 fragment.color.primary (r,g,b,a) primary color 1955 fragment.color.secondary (r,g,b,a) secondary color 1956 fragment.texcoord (s,t,r,q) texture coordinate, unit 0 1957 fragment.texcoord[n] (s,t,r,q) texture coordinate, unit n 1958 fragment.fogcoord (f,0,0,1) fog distance/coordinate 1959 fragment.position (x,y,z,1/w) window position 1960 1961 Table X.1: Fragment Attribute Bindings. The "Components" column 1962 indicates the mapping of the state in the "Underlying State" 1963 column. Bindings containing "[n]" require an integer value of <n> 1964 to select an individual item. 1965 1966 If a fragment attribute binding matches "fragment.color" or 1967 "fragment.color.primary", the "x", "y", "z", and "w" components of 1968 the fragment attribute variable are filled with the "r", "g", "b", 1969 and "a" components, respectively, of the fragment color. Each 1970 fixed-point color component undergoes an implied conversion to 1971 floating point. This conversion must leave the values 0 and 1 1972 invariant. 1973 1974 If a fragment attribute binding matches "fragment.color.secondary", 1975 the "x", "y", "z", and "w" components of the fragment attribute 1976 variable are filled with the "r", "g", "b", and "a" components, 1977 respectively, of the fragment secondary color. Each fixed-point 1978 color component undergoes an implied conversion to floating point. 1979 This conversion must leave the values 0 and 1 invariant. 1980 1981 If a fragment attribute binding matches "fragment.texcoord" or 1982 "fragment.texcoord[n]", the "x", "y", "z", and "w" components of the 1983 fragment attribute variable are filled with the "s", "t", "r", and 1984 "q" components, respectively, of the fragment texture coordinates 1985 for texture unit <n>. If "[n]" is omitted, texture unit zero is 1986 used. 1987 1988 If a fragment attribute binding matches "fragment.fogcoord", the "x" 1989 component of the fragment attribute variable is filled with either 1990 the fragment eye distance or the fog coordinate, depending on 1991 whether the fog source is set to FRAGMENT_DEPTH_EXT or 1992 FOG_COORDINATE_EXT, respectively. The "y", "z", and "w" coordinates 1993 are filled with 0, 0, and 1, respectively. 1994 1995 If a fragment attribute binding matches "fragment.position", the "x" 1996 and "y" components of the fragment attribute variable are filled 1997 with the (x,y) window coordinates of the fragment center, relative 1998 to the lower left corner of the window. The "z" component is filled 1999 with the fragment's z window coordinate. This z window coordinate 2000 undergoes an implied conversion to floating point. This conversion 2001 must leave the values 0 and 1 invariant. The "w" component is 2002 filled with the reciprocal of the fragment's clip w coordinate. 2003 2004 On some implementations, the components of fragment.position may be 2005 generated by interpolating per-vertex position values. This may 2006 produce x and y window coordinates that don't exactly match those of 2007 the fragment center and z window coordinates that do not exactly 2008 match those generated by fixed-function rasterization. Therefore, 2009 there is no guaranteed invariance between the final z window 2010 coordinates of fragments processed by fragment programs that write 2011 depth values and fragments processed by any other means, even if the 2012 fragment programs in question simply copy the z value from the 2013 fragment.position binding. 2014 2015 2016 3.11.3.2 Fragment Program Parameters 2017 2018 Fragment program parameter variables are a set of four-component 2019 floating-point vectors used as constants during fragment program 2020 execution. Fragment program parameters retain their values across 2021 fragment program invocations, although their values can change 2022 between invocations due to GL state changes. 2023 2024 Single program parameter variables and arrays of program parameter 2025 variables can be declared explicitly using the <PARAM_statement> 2026 grammar rule. Single program parameter variables can also be 2027 declared implicitly using the <paramSingleItemUse> grammar rule in 2028 an executable instruction. 2029 2030 Each single program parameter variable is bound to a constant vector 2031 or to a GL state vector according to the <paramSingleInit> grammar 2032 rule. Individual items of a program parameter array are bound to 2033 constant vectors or GL state vectors according to the 2034 <programMultipleInit> grammar rule. The set of GL state that can be 2035 bound to program parameter variables are given in Tables X.2.1 2036 through X.2.4. 2037 2038 2039 Constant Bindings 2040 2041 A program parameter variable can be bound to a scalar or vector 2042 constant using the <paramConstDecl> grammar rule (explicit 2043 declarations) or the <paramConstUse> grammar rule (implicit 2044 declarations). 2045 2046 If a program parameter binding matches the <paramConstScalarDecl> or 2047 <paramConstScalarUse> grammar rules, the corresponding program 2048 parameter variable is bound to the vector (X,X,X,X), where X is the 2049 value of the specified constant. Note that the 2050 <paramConstScalarUse> grammar rule, used only in implicit 2051 declarations, allows only non-negative constants. This 2052 disambiguates cases like "-2", which could conceivably be taken to 2053 mean either the vector "(2,2,2,2)" with all components negated or 2054 "(-2,-2,-2,-2)" without negation. Only the former interpretation is 2055 allowed by the grammar. 2056 2057 If a program parameter binding matches <paramConstVector>, the 2058 corresponding program parameter variable is bound to the vector 2059 (X,Y,Z,W), where X, Y, Z, and W are the values corresponding to the 2060 first, second, third, and fourth match of <signedFloatConstant>. If 2061 fewer than four constants are specified, Y, Z, and W assume the 2062 values 0.0, 0.0, and 1.0, if their respective constants are not 2063 specified. 2064 2065 Program parameter variables initialized to constant values can never 2066 be modified. 2067 2068 2069 Program Environment/Local Parameter Bindings 2070 2071 Binding Components Underlying State 2072 ----------------------------- ---------- ---------------------------- 2073 program.env[a] (x,y,z,w) program environment 2074 parameter a 2075 program.local[a] (x,y,z,w) program local parameter a 2076 program.env[a..b] (x,y,z,w) program environment 2077 parameters a through b 2078 program.local[a..b] (x,y,z,w) program local parameters 2079 a through b 2080 2081 Table X.2.1: Program Environment/Local Parameter Bindings. <a> 2082 and <b> indicate parameter numbers, where <a> must be less than or 2083 equal to <b>. 2084 2085 If a program parameter binding matches "program.env[a]" or 2086 "program.local[a]", the four components of the program parameter 2087 variable are filled with the four components of program environment 2088 parameter <a> or program local parameter <a>, respectively. 2089 2090 Additionally, for program parameter array bindings, 2091 "program.env[a..b]" and "program.local[a..b]" are equivalent to 2092 specifying program environment parameters <a> through <b> in order 2093 or program local parameters <a> through <b> in order, respectively. 2094 In either case, a program will fail to load if <a> is greater than 2095 <b>. 2096 2097 2098 Material Property Bindings 2099 2100 Binding Components Underlying State 2101 ----------------------------- ---------- ---------------------------- 2102 state.material.ambient (r,g,b,a) front ambient material color 2103 state.material.diffuse (r,g,b,a) front diffuse material color 2104 state.material.specular (r,g,b,a) front specular material color 2105 state.material.emission (r,g,b,a) front emissive material color 2106 state.material.shininess (s,0,0,1) front material shininess 2107 state.material.front.ambient (r,g,b,a) front ambient material color 2108 state.material.front.diffuse (r,g,b,a) front diffuse material color 2109 state.material.front.specular (r,g,b,a) front specular material color 2110 state.material.front.emission (r,g,b,a) front emissive material color 2111 state.material.front.shininess (s,0,0,1) front material shininess 2112 state.material.back.ambient (r,g,b,a) back ambient material color 2113 state.material.back.diffuse (r,g,b,a) back diffuse material color 2114 state.material.back.specular (r,g,b,a) back specular material color 2115 state.material.back.emission (r,g,b,a) back emissive material color 2116 state.material.back.shininess (s,0,0,1) back material shininess 2117 2118 Table X.2.2: Material Property Bindings. If a material face is 2119 not specified in the binding, the front property is used. 2120 2121 If a program parameter binding matches any of the material 2122 properties listed in Table X.2.2, the program parameter variable is 2123 filled according to the table. For ambient, diffuse, specular, or 2124 emissive colors, the "x", "y", "z", and "w" components are filled 2125 with the "r", "g", "b", and "a" components, respectively, of the 2126 corresponding material color. For material shininess, the "x" 2127 component is filled with the material's specular exponent, and the 2128 "y", "z", and "w" components are filled with 0, 0, and 1, 2129 respectively. Bindings containing ".back" refer to the back 2130 material; all other bindings refer to the front material. 2131 2132 Material properties can be changed inside a Begin/End pair, either 2133 directly by calling Material, or indirectly through color material. 2134 However, such property changes are not guaranteed to update program 2135 parameter bindings until the following End command. Program 2136 parameter variables bound to material properties changed inside a 2137 Begin/End pair are undefined until the following End command. 2138 2139 2140 Light Property Bindings 2141 2142 Binding Components Underlying State 2143 ----------------------------- ---------- ---------------------------- 2144 state.light[n].ambient (r,g,b,a) light n ambient color 2145 state.light[n].diffuse (r,g,b,a) light n diffuse color 2146 state.light[n].specular (r,g,b,a) light n specular color 2147 state.light[n].position (x,y,z,w) light n position 2148 state.light[n].attenuation (a,b,c,e) light n attenuation constants 2149 and spot light exponent 2150 state.light[n].spot.direction (x,y,z,c) light n spot direction and 2151 cutoff angle cosine 2152 state.light[n].half (x,y,z,1) light n infinite half-angle 2153 state.lightmodel.ambient (r,g,b,a) light model ambient color 2154 state.lightmodel.scenecolor (r,g,b,a) light model front scene color 2155 state.lightmodel . (r,g,b,a) light model front scene color 2156 front.scenecolor 2157 state.lightmodel . (r,g,b,a) light model back scene color 2158 back.scenecolor 2159 state.lightprod[n].ambient (r,g,b,a) light n / front material 2160 ambient color product 2161 state.lightprod[n].diffuse (r,g,b,a) light n / front material 2162 diffuse color product 2163 state.lightprod[n].specular (r,g,b,a) light n / front material 2164 specular color product 2165 state.lightprod[n]. (r,g,b,a) light n / front material 2166 front.ambient ambient color product 2167 state.lightprod[n]. (r,g,b,a) light n / front material 2168 front.diffuse diffuse color product 2169 state.lightprod[n]. (r,g,b,a) light n / front material 2170 front.specular specular color product 2171 state.lightprod[n]. (r,g,b,a) light n / back material 2172 back.ambient ambient color product 2173 state.lightprod[n]. (r,g,b,a) light n / back material 2174 back.diffuse diffuse color product 2175 state.lightprod[n]. (r,g,b,a) light n / back material 2176 back.specular specular color product 2177 2178 Table X.2.3: Light Property Bindings. <n> indicates a light 2179 number. 2180 2181 If a program parameter binding matches "state.light[n].ambient", 2182 "state.light[n].diffuse", or "state.light[n].specular", the "x", 2183 "y", "z", and "w" components of the program parameter variable are 2184 filled with the "r", "g", "b", and "a" components, respectively, of 2185 the corresponding light color. 2186 2187 If a program parameter binding matches "state.light[n].position", 2188 the "x", "y", "z", and "w" components of the program parameter 2189 variable are filled with the "x", "y", "z", and "w" components, 2190 respectively, of the light position. 2191 2192 If a program parameter binding matches "state.light[n].attenuation", 2193 the "x", "y", and "z" components of the program parameter variable 2194 are filled with the constant, linear, and quadratic attenuation 2195 parameters of the specified light, respectively (section 2.13.1). 2196 The "w" component of the program parameter variable is filled with 2197 the spot light exponent of the specified light. 2198 2199 If a program parameter binding matches 2200 "state.light[n].spot.direction", the "x", "y", and "z" components of 2201 the program parameter variable are filled with the "x", "y", and "z" 2202 components of the spot light direction of the specified light, 2203 respectively (section 2.13.1). The "w" component of the program 2204 parameter variable is filled with the cosine of the spot light 2205 cutoff angle of the specified light. 2206 2207 If a program parameter binding matches "state.light[n].half", the 2208 "x", "y", and "z" components of the program parameter variable are 2209 filled with the x, y, and z components, respectively, of the 2210 normalized infinite half-angle vector 2211 2212 h_inf = || P + (0, 0, 1) ||. 2213 2214 The "w" component is filled with 1. In the computation of h_inf, P 2215 consists of the x, y, and z coordinates of the normalized vector 2216 from the eye position P_e to the eye-space light position P_pli 2217 (section 2.13.1). h_inf is defined to correspond to the normalized 2218 half-angle vector when using an infinite light (w coordinate of the 2219 position is zero) and an infinite viewer (v_bs is FALSE). For local 2220 lights or a local viewer, h_inf is well-defined but does not match 2221 the normalized half-angle vector, which will vary depending on the 2222 vertex position. 2223 2224 If a program parameter binding matches "state.lightmodel.ambient", 2225 the "x", "y", "z", and "w" components of the program parameter 2226 variable are filled with the "r", "g", "b", and "a" components of 2227 the light model ambient color, respectively. 2228 2229 If a program parameter binding matches "state.lightmodel.scenecolor" 2230 or "state.lightmodel.front.scenecolor", the "x", "y", and "z" 2231 components of the program parameter variable are filled with the 2232 "r", "g", and "b" components respectively of the "front scene color" 2233 2234 c_scene = a_cs * a_cm + e_cm, 2235 2236 where a_cs is the light model ambient color, a_cm is the front 2237 ambient material color, and e_cm is the front emissive material 2238 color. The "w" component of the program parameter variable is 2239 filled with the alpha component of the front diffuse material color. 2240 If a program parameter binding matches 2241 "state.lightmodel.back.scenecolor", a similar back scene color, 2242 computed using back-facing material properties, is used. The front 2243 and back scene colors match the values that would be assigned to 2244 vertices using conventional lighting if all lights were disabled. 2245 2246 If a program parameter binding matches anything beginning with 2247 "state.lightprod[n]", the "x", "y", and "z" components of the 2248 program parameter variable are filled with the "r", "g", and "b" 2249 components, respectively, of the corresponding light product. The 2250 three light product components are the products of the corresponding 2251 color components of the specified material property and the light 2252 color of the specified light (see Table X.2.3). The "w" component 2253 of the program parameter variable is filled with the alpha component 2254 of the specified material property. 2255 2256 Light products depend on material properties, which can be changed 2257 inside a Begin/End pair. Such property changes are not guaranteed 2258 to take effect until the following End command. Program parameter 2259 variables bound to light products whose corresponding material 2260 property changes inside a Begin/End pair are undefined until the 2261 following End command. 2262 2263 2264 Texture Environment Property Bindings 2265 2266 Binding Components Underlying State 2267 ------------------------- ---------- ---------------------------- 2268 state.texenv[n].color (r,g,b,a) texture environment n color 2269 2270 Table X.2.4: Texture Environment Property Bindings. "[n]" is 2271 optional -- texture unit <n> is used if specified; texture unit 0 2272 is used otherwise. 2273 2274 If a program parameter binding matches "state.texenv[n].color", the 2275 "x", "y", "z", and "w" components of the program parameter variable 2276 are filled with the "r", "g", "b", and "a" components, respectively, 2277 of the corresponding texture environment color. Note that only 2278 "legacy" texture units, as queried by MAX_TEXTURE_UNITS, include 2279 texture environment state. Texture image units and texture 2280 coordinate sets do not have associated texture environment state. 2281 2282 2283 Fog Property Bindings 2284 2285 Binding Components Underlying State 2286 --------------------------- ---------- ---------------------------- 2287 state.fog.color (r,g,b,a) RGB fog color (section 3.11) 2288 state.fog.params (d,s,e,r) fog density, linear start 2289 and end, and 1/(end-start) 2290 (section 3.11) 2291 2292 Table X.2.5: Fog Property Bindings 2293 2294 If a program parameter binding matches "state.fog.color", the "x", 2295 "y", "z", and "w" components of the program parameter variable are 2296 filled with the "r", "g", "b", and "a" components, respectively, of 2297 the fog color (section 3.11). 2298 2299 If a program parameter binding matches "state.fog.params", the "x", 2300 "y", and "z" components of the program parameter variable are filled 2301 with the fog density, linear fog start, and linear fog end 2302 parameters (section 3.11), respectively. The "w" component is 2303 filled with 1/(end-start), where end and start are the linear fog 2304 end and start parameters, respectively. 2305 2306 2307 Depth Property Bindings 2308 2309 Binding Components Underlying State 2310 --------------------------- ---------- ---------------------------- 2311 state.depth.range (n,f,d,1) Depth range near, far, and 2312 (far-near) (section 2.10.1) 2313 2314 Table X.2.6: Depth Property Bindings 2315 2316 If a program parameter binding matches "state.depth.range", the "x" 2317 and "y" components of the program parameter variable are filled with 2318 the mappings of near and far clipping planes to window coordinates, 2319 respectively. The "z" component is filled with the difference of 2320 the mappings of near and far clipping planes, far minus near. The 2321 "w" component is filled with 1. 2322 2323 2324 Matrix Property Bindings 2325 2326 Binding Underlying State 2327 ------------------------------------ --------------------------- 2328 * state.matrix.modelview[n] modelview matrix n 2329 state.matrix.projection projection matrix 2330 state.matrix.mvp modelview-projection matrix 2331 * state.matrix.texture[n] texture matrix n 2332 state.matrix.palette[n] modelview palette matrix n 2333 state.matrix.program[n] program matrix n 2334 2335 Table X.2.7: Base Matrix Property Bindings. The "[n]" syntax 2336 indicates a specific matrix number. For modelview and texture 2337 matrices, a matrix number is optional, and matrix zero will be 2338 used if the matrix number is omitted. These base bindings may 2339 further be modified by a inverse/transpose selector and a row 2340 selector. 2341 2342 If the beginning of a program parameter binding matches any of the 2343 matrix binding names listed in Table X.2.7, the binding corresponds 2344 to a 4x4 matrix. If the parameter binding is followed by 2345 ".inverse", ".transpose", or ".invtrans" (<stateMatModifier> grammar 2346 rule), the inverse, transpose, or transpose of the inverse, 2347 respectively, of the matrix specified in Table X.2.7 is selected. 2348 Otherwise, the matrix specified in Table X.2.7 is selected. If the 2349 specified matrix is poorly-conditioned (singular or nearly so), its 2350 inverse matrix is undefined. The binding name "state.matrix.mvp" 2351 refers to the product of modelview matrix zero and the projection 2352 matrix, defined as 2353 2354 MVP = P * M0, 2355 2356 where P is the projection matrix and M0 is modelview matrix zero. 2357 2358 If the selected matrix is followed by ".row[<a>]" (matching the 2359 <stateMatrixRow> grammar rule), the "x", "y", "z", and "w" 2360 components of the program parameter variable are filled with the 2361 four entries of row <a> of the selected matrix. In the example, 2362 2363 PARAM m0 = state.matrix.modelview[1].row[0]; 2364 PARAM m1 = state.matrix.projection.transpose.row[3]; 2365 2366 the variable "m0" is set to the first row (row 0) of modelview 2367 matrix 1 and "m1" is set to the last row (row 3) of the transpose of 2368 the projection matrix. 2369 2370 For program parameter array bindings, multiple rows of the selected 2371 matrix can be bound via the <stateMatrixRows> grammar rule. If the 2372 selected matrix binding is followed by ".row[<a>..<b>]", the result 2373 is equivalent to specifying matrix rows <a> through <b>, in order. 2374 A program will fail to load if <a> is greater than <b>. If no row 2375 selection is specified (<optMatrixRows> matches ""), matrix rows 0 2376 through 3 are bound in order. In the example, 2377 2378 PARAM m2[] = { state.matrix.program[0].row[1..2] }; 2379 PARAM m3[] = { state.matrix.program[0].transpose }; 2380 2381 the array "m2" has two entries, containing rows 1 and 2 of program 2382 matrix zero, and "m3" has four entries, containing all four rows of 2383 the transpose of program matrix zero. 2384 2385 2386 Program Parameter Arrays 2387 2388 A program parameter array variable can be declared explicitly by 2389 matching the <PARAM_multipleStmt> grammar rule. Programs can 2390 optionally specify the number of individual program parameters in 2391 the array, using the <optArraySize> grammar rule. Program parameter 2392 arrays may not be declared implicity. 2393 2394 Individual parameter variables in a program parameter array are 2395 bound to GL state vectors or constant vectors as specified by the 2396 grammar rule <paramMultInitList>. Each individual parameter in the 2397 array is bound in turn as described above. 2398 2399 The total number of entries in the array is equal to the number of 2400 parameters bound in the initializer list. A fragment program that 2401 specifies an array size (<optArraySize> matches <integer>) that does 2402 not match the number of parameter bindings in the initialization 2403 list will fail to load. 2404 2405 Program parameter array variables may only be accessed using 2406 absolute addressing by matching the <progParamArrayAbs> grammar 2407 rule. Array accesses are checked against the limits of the array. 2408 If any fragment program instruction accesses a program parameter 2409 array with an out-of-range index (greater than or equal to the size 2410 of the array), the fragment program will fail to load. 2411 2412 Individual state vectors can have no more than one unique binding in 2413 any given program. The GL will automatically combine multiple 2414 bindings of the same state vector into a single unique binding. 2415 2416 2417 3.11.3.3 Fragment Program Temporaries 2418 2419 Fragment program temporary variables are a set of four-component 2420 floating-point vectors used to hold temporary results during 2421 fragment program execution. Temporaries do not persist between 2422 program invocations, and are undefined at the beginning of each 2423 fragment program invocation. 2424 2425 Fragment program temporary variables can be declared explicitly 2426 using the <TEMP_statement> grammar rule. Each such statement can 2427 declare one or more temporaries. Fragment program temporary 2428 variables can not be declared implicitly. 2429 2430 2431 3.11.3.4 Fragment Program Results 2432 2433 Fragment program result variables are a set of four component 2434 floating-point vectors used to hold the final results of a fragment 2435 program. Fragment program result variables are write-only during 2436 fragment program execution. 2437 2438 Fragment program result variables can be declared explicitly using 2439 the <OUTPUT_statement> grammar rule, or implicitly using the 2440 <resultBinding> grammar rule in an executable instruction. Each 2441 fragment program result variable is bound to a fragment attribute 2442 used in subsequent back-end processing. The set of fragment program 2443 result variable bindings is given in Table X.3. 2444 2445 Binding Components Description 2446 ----------------------------- ---------- ---------------------------- 2447 result.color (r,g,b,a) color 2448 result.depth (*,*,d,*) depth coordinate 2449 2450 Table X.3: Fragment Result Variable Bindings. Components labeled 2451 "*" are unused. 2452 2453 If a result variable binding matches "result.color", updates to the 2454 "x", "y", "z", and "w" components of the result variable modify the 2455 "r", "g", "b", and "a" components, respectively, of the fragment's 2456 output color. If "result.color" is not both bound by the fragment 2457 program and written by some instruction of the program, the output 2458 color of the fragment program is undefined. 2459 2460 If a result variable binding matches "result.depth", updates to the 2461 "z" component of the result variable modify the fragment's output 2462 depth value. If "result.depth" is not both bound by the fragment 2463 program and written by some instruction of the program, the 2464 interpolated depth value produced by rasterization is used as if 2465 fragment program mode is not enabled. Writes to any component of 2466 depth other than the "z" component have no effect. 2467 2468 2469 3.11.3.5 Fragment Program Aliases 2470 2471 Fragment programs can create aliases by matching the 2472 <ALIAS_statement> grammar rule. Aliases allow programs to use 2473 multiple variable names to refer to a single underlying variable. 2474 For example, the statement 2475 2476 ALIAS var1 = var0 2477 2478 establishes a variable name named "var1". Subsequent references to 2479 "var1" in the program text are treated as references to "var0". The 2480 left hand side of an ALIAS statement must be a new variable name, 2481 and the right hand side must be an established variable name. 2482 2483 Aliases are not considered variable declarations, so do not count 2484 against the limits on the number of variable declarations allowed in 2485 the program text. 2486 2487 2488 3.11.3.6 Fragment Program Resource Limits 2489 2490 The fragment program execution environment provides implementation- 2491 dependent resource limits on the number of ALU instructions, texture 2492 instructions, total instructions (ALU or texture), temporary 2493 variable declarations, program parameter bindings, or texture 2494 indirections. A program that exceeds any of these resource limits 2495 will fail to load. The resource limits for fragment programs can be 2496 queried by calling GetProgramiv (section 6.1.12) with a target of 2497 FRAGMENT_PROGRAM_ARB. 2498 2499 The limit on fragment program ALU instructions can be queried with 2500 a <pname> of MAX_PROGRAM_ALU_INSTRUCTIONS_ARB, and must be at least 2501 48. Each ALU instruction in the program (matches of the 2502 <ALUInstruction> grammar rule) counts against this limit. 2503 2504 The limit on fragment program texture instructions can be queried 2505 with a <pname> of MAX_PROGRAM_TEX_INSTRUCTIONS_ARB, and must be at 2506 least 24. Each texture instruction in the program (matches of the 2507 <TexInstruction> grammar rule) counts against this limit. 2508 2509 The limit on fragment program total instructions can be queried with 2510 a <pname> of MAX_PROGRAM_INSTRUCTIONS_ARB, and must be at least 72. 2511 Each instruction in the program (matching the <instruction> grammar 2512 rule) counts against this limit. Note that the limit on total 2513 instructions is not necessarily equal to the sum of the limits on 2514 ALU instructions and texture instructions. 2515 2516 The limit on fragment program texture indirections can be queried 2517 with a <pname> of MAX_PROGRAM_TEX_INDIRECTIONS_ARB, and must be at 2518 least 4. Texture indirections are described in 3.11.6. If an 2519 implementation has no limit on texture indirections, the limit will 2520 be equal to the limit on texture instructions. 2521 2522 The limit on fragment program temporary variable declarations can be 2523 queried with a <pname> of MAX_PROGRAM_TEMPORARIES_ARB, and must be at 2524 least 16. Each temporary declared in the program, using the 2525 <TEMP_statement> grammar rule, counts against this limit. Aliases 2526 of declared temporaries do not. 2527 2528 The limit on fragment program attribute bindings can be queried with 2529 a <pname> of MAX_PROGRAM_ATTRIBS_ARB and must be at least 10. Each 2530 distinct vertex attribute bound explicitly or implicitly in the 2531 program counts against this limit; vertex attributes bound multiple 2532 times count only once. 2533 2534 The limit on fragment program parameter bindings can be queried with 2535 a <pname> of MAX_PROGRAM_PARAMETERS_ARB, and must be at least 24. 2536 Each distinct GL state vector bound explicitly or implicitly in the 2537 program counts against this limit; GL state vectors bound multiple 2538 times count only once. Every other constant vector bound in the 2539 program is counted if and only if an identical constant vector has 2540 not already been counted. Two constant vectors are considered 2541 identical if the four component values are numerically equivalent. 2542 Recall that scalar constants bound in a program are treated as 2543 vector constants with the scalar value replicated. 2544 2545 In addition to the limits described above, the GL provides a similar 2546 set of implementation-dependent native resource limits. These 2547 limits, specified in Section 6.1.12, provide guidance as to whether 2548 the program is small enough to use a "native" mode where fragment 2549 programs may be executed with higher performance. The native 2550 resource limits and usage counts are implementation-dependent and 2551 may not exactly correspond to limits and counts described above. 2552 A program's native resource consumption may be reduced by program 2553 optimizations performed by the GL. Native resource consumption may 2554 be increased due to emulation of instructions or any other program 2555 features not natively supported by an implementation. Notably, an 2556 additional texture indirection may be consumed due to an 2557 implementation's lack of native support for texture instructions 2558 with source coordinate swizzles or parameter source coordinates, 2559 which may require emulation by prepending ALU instructions. An 2560 implementation may also fail to natively support all combinations of 2561 attributes described in Table X.1, even if the total number of 2562 bound attributes is fewer than the native attribute limit. In this 2563 case the program is still considered to exceed the native resource 2564 limits, as queried by PROGRAM_UNDER_NATIVE_LIMITS_ARB (section 2565 6.1.12). 2566 2567 To assist in resource counting, the GL additionally provides 2568 GetProgram queries to determine the resource usage and native 2569 resource usage of the currently bound program, and to determine 2570 whether the bound program exceeds any native resource limit. 2571 2572 Programs that exceed any native resource limit may or may not load 2573 depending on the implementation. 2574 2575 2576 3.11.4 Fragment Program Execution Environment 2577 2578 If fragment program mode is enabled, the currently bound fragment 2579 program is executed when any fragment is produced by rasterization. 2580 2581 If fragment program mode is enabled and the currently bound program 2582 object does not contain a valid fragment program, the error 2583 INVALID_OPERATION will be generated by Begin, RasterPos, and any 2584 command that implicitly calls Begin (e.g., DrawArrays). 2585 2586 Fragment programs execute a sequence of instructions without 2587 branching. Fragment programs begin by executing the first 2588 instruction in the program, and execute instructions in the order 2589 specified in the program until the last instruction is completed. 2590 2591 There are 33 fragment program instructions. The instructions and 2592 their respective input and output parameters are summarized in 2593 Table X.5. 2594 2595 Instruction Inputs Output Description 2596 ----------- ------ ------ -------------------------------- 2597 ABS v v absolute value 2598 ADD v,v v add 2599 CMP v,v,v v compare 2600 COS s ssss cosine with reduction to [-PI,PI] 2601 DP3 v,v ssss 3-component dot product 2602 DP4 v,v ssss 4-component dot product 2603 DPH v,v ssss homogeneous dot product 2604 DST v,v v distance vector 2605 EX2 s ssss exponential base 2 2606 FLR v v floor 2607 FRC v v fraction 2608 KIL v v kill fragment 2609 LG2 s ssss logarithm base 2 2610 LIT v v compute light coefficients 2611 LRP v,v,v v linear interpolation 2612 MAD v,v,v v multiply and add 2613 MAX v,v v maximum 2614 MIN v,v v minimum 2615 MOV v v move 2616 MUL v,v v multiply 2617 POW s,s ssss exponentiate 2618 RCP s ssss reciprocal 2619 RSQ s ssss reciprocal square root 2620 SCS s ss-- sine/cosine without reduction 2621 SGE v,v v set on greater than or equal 2622 SIN s ssss sine with reduction to [-PI,PI] 2623 SLT v,v v set on less than 2624 SUB v,v v subtract 2625 SWZ v v extended swizzle 2626 TEX v,u,t v texture sample 2627 TXB v,u,t v texture sample with bias 2628 TXP v,u,t v texture sample with projection 2629 XPD v,v v cross product 2630 2631 Table X.5: Summary of fragment program instructions. "v" 2632 indicates a floating-point vector input or output, "s" indicates a 2633 floating-point scalar input, "ssss" indicates a scalar output 2634 replicated across a 4-component result vector, "ss--" indicates 2635 two scalar outputs in the first two components, "u" indicates a 2636 texture image unit identifier, and "t" indicates a texture target. 2637 2638 2639 3.11.4.1 Fragment Program Operands 2640 2641 Most fragment program instructions operate on floating-point vectors 2642 or scalars, as indicated by the grammar rules <vectorSrcReg> and 2643 <scalarSrcReg>, respectively. 2644 2645 Vector and scalar operands can be obtained from fragment attribute, 2646 program parameter, or temporary registers, as indicated by the 2647 <srcReg> rule. For scalar operands, a single vector component is 2648 selected by the <scalarSuffix> rule, where the characters "x", "y", 2649 "z", and "w", or "r", "g", "b", and "a" select the first, second, 2650 third, and fourth components, respectively, of the vector. 2651 2652 Vector operands can be swizzled according to the <optionalSuffix> 2653 rule. In its most general form, the <optionalSuffix> rule matches 2654 the pattern ".????" where each question mark is replaced with one of 2655 "x", "y", "z", "w", "r", "g", "b", or "a". For such patterns, the 2656 first, second, third, and fourth components of the operand are taken 2657 from the vector components named by the first, second, third, and 2658 fourth character of the pattern, respectively. For example, if the 2659 swizzle suffix is ".yzzx" or ".gbbr" and the specified source 2660 contains {2,8,9,0}, the swizzled operand used by the instruction is 2661 {8,9,9,2}. 2662 2663 If the <optionalSuffix> rule matches "", it is treated as though it 2664 were ".xyzw". If the <optionalSuffix> rule matches (ignoring 2665 whitespace) ".x", ".y", ".z", or ".w", these are treated the same as 2666 ".xxxx", ".yyyy", ".zzzz", and ".wwww" respectively. Likewise, if 2667 the <optionalSuffix> rule matches ".r", ".g", ".b", or ".a", these 2668 are treated the same as ".rrrr", ".gggg", ".bbbb", and ".aaaa" 2669 respectively. 2670 2671 Floating-point scalar or vector operands can optionally be negated 2672 according to the <optionalSign> rule in <scalarSrcReg> and 2673 <vectorSrcReg>. If the <optionalSign> matches "-", each operand or 2674 operand component is negated. 2675 2676 The following pseudo-code spells out the operand generation process. 2677 In the example, "float" is a floating-point scalar type, while 2678 "floatVec" is a four-component vector. "source" refers to the 2679 register used for the operand, matching the <srcReg> rule. "negate" 2680 is TRUE if the <optionalSign> rule in <scalarSrcReg> or 2681 <vectorSrcReg> matches "-" and FALSE otherwise. The ".c***", 2682 ".*c**", ".**c*", ".***c" modifiers refer to the x, y, z, and w 2683 components obtained by the swizzle operation; the ".c" modifier 2684 refers to the single component selected for a scalar load. 2685 2686 floatVec VectorLoad(floatVec source) 2687 { 2688 floatVec operand; 2689 2690 operand.x = source.c***; 2691 operand.y = source.*c**; 2692 operand.z = source.**c*; 2693 operand.w = source.***c; 2694 if (negate) { 2695 operand.x = -operand.x; 2696 operand.y = -operand.y; 2697 operand.z = -operand.z; 2698 operand.w = -operand.w; 2699 } 2700 2701 return operand; 2702 } 2703 2704 float ScalarLoad(floatVec source) 2705 { 2706 float operand; 2707 2708 operand = source.c; 2709 if (negate) { 2710 operand = -operand; 2711 } 2712 2713 return operand; 2714 } 2715 2716 2717 3.11.4.2 Fragment Program Parameter Arrays 2718 2719 A fragment program can load a single element of a program parameter 2720 array using only absolute addressing. Program parameter arrays are 2721 accessed when the <progParamArrayAbs> rule is matched. The offset 2722 of the selected entry in the array is given by the number matching 2723 <progParamRegNum>. If the offset exceeds the size of the 2724 array, the results of the access are undefined, but may not lead to 2725 program or GL termination. 2726 2727 2728 3.11.4.3 Fragment Program Destination Register Update 2729 2730 Fragment program instructions write a 4-component result vector to a 2731 single temporary or fragment result register. Writes to individual 2732 components of the destination register are controlled by individual 2733 component write masks specified as part of the instruction. 2734 Optional clamping of each component of the destination register to 2735 the range [0,1] is controlled by an opcode modifier. 2736 2737 The component write mask is specified by the <optionalMask> rule 2738 found in the <maskedDstReg> rule. If the optional mask is "", all 2739 components are enabled. Otherwise, the optional mask names the 2740 individual components to enable. The characters "x", "y", "z", and 2741 "w", or "r", "g", "b", and "a" match the first, second, third, and 2742 fourth components, respectively. For example, an optional mask of 2743 ".xzw" indicates that the x, z, and w components should be enabled 2744 for writing but the y component should not. The grammar requires 2745 that the destination register mask components must be listed in 2746 "xyzw", or "rgba" order. Component names from one set (xyzw or 2747 rgba) cannot be mixed with component names from another set. For 2748 example, ".rgw" is not a valid writemask. 2749 2750 Each component of the destination register is updated with the 2751 result of the fragment program instruction if and only if the 2752 component is enabled for writes by the component write mask. 2753 Otherwise, the component of the destination register remains 2754 unchanged. 2755 2756 If the instruction opcode has the "_SAT" suffix, requesting 2757 saturated result vectors, each component of the result vector 2758 enabled in the writemask is clamped to the range [0,1] before being 2759 updated in the destination register. 2760 2761 The following pseudocode illustrates the process of writing a result 2762 vector to the destination register. In the pseudocode, "instrmask" 2763 refers to the component write mask given by the <optionalMask> rule. 2764 "clamp" is TRUE if the instruction specifies that the result should 2765 be clamped. "result" and "destination" refer to the result vector 2766 and the register selected by <dstReg>, respectively. 2767 2768 void UpdateDestination(floatVec destination, floatVec result) 2769 { 2770 floatVec merged; 2771 2772 // Clamp the result vector components to [0,1], if requested. 2773 if (instrClamp) { 2774 if (result.x < 0) result.x = 0; 2775 else if (result.x > 1) result.x = 1; 2776 if (result.y < 0) result.y = 0; 2777 else if (result.y > 1) result.y = 1; 2778 if (result.z < 0) result.z = 0; 2779 else if (result.z > 1) result.z = 1; 2780 if (result.w < 0) result.w = 0; 2781 else if (result.w > 1) result.w = 1; 2782 } 2783 2784 // Merge the converted result into the destination register, 2785 // under control of the compile-time write mask. 2786 merged = destination; 2787 if (instrMask.x) { 2788 merged.x = result.x; 2789 } 2790 if (instrMask.y) { 2791 merged.y = result.y; 2792 } 2793 if (instrMask.z) { 2794 merged.z = result.z; 2795 } 2796 if (instrMask.w) { 2797 merged.w = result.w; 2798 } 2799 2800 // Write out the new destination register. 2801 destination = merged; 2802 } 2803 2804 2805 3.11.4.4 Fragment Program Result Processing 2806 2807 As a fragment program executes, it will write to either one or two 2808 result registers that are mapped to the fragment's color and depth. 2809 2810 The fragment's color components are first clamped to the range [0,1] 2811 then converted to fixed point as in section 2.13.9. If the fragment 2812 program does not write result.color, the color will be undefined in 2813 subsequent stages. 2814 2815 If the fragment program contains an instruction to write to 2816 result.depth, the fragment's depth is replaced by the value of the 2817 "z" component of result.depth. This z value is first clamped to the 2818 range [0,1] then converted to fixed-point as if it were a window z 2819 value (section 2.10.1). If the fragment program does not write 2820 result.depth, the fragment's original depth is unmodified. 2821 2822 2823 3.11.4.5 Fragment Program Options 2824 2825 The <optionSequence> grammar rule provides a mechanism for programs 2826 to indicate that one or more extended language features are used by 2827 the program. All program options used by the program must be 2828 declared at the beginning of the program string. Each program 2829 option specified in a program string will modify the syntactic or 2830 semantic rules used to interpet the program and the execution 2831 environment used to execute the program. Program options not 2832 present in the program string are ignored, even if they are 2833 supported by the GL. 2834 2835 The <identifier> token in the <option> rule must match the name of a 2836 program option supported by the implementation. To avoid option 2837 name conflicts, option identifiers are required to begin with a 2838 vendor prefix. A program will fail to load if it specifies a 2839 program option not supported by the GL. 2840 2841 Fragment program options should confine their semantic changes to 2842 the domain of fragment programs. Support for a fragment program 2843 option should not change the specification and behavior of fragment 2844 programs not requesting use of that option. 2845 2846 2847 3.11.4.5.1 Fog Application Fragment Program Options 2848 2849 If a fragment program specifies one of the options "ARB_fog_exp", 2850 "ARB_fog_exp2", or "ARB_fog_linear", the program will apply fog to 2851 the program's final clamped color using a fog mode of EXP, EXP2, or 2852 LINEAR, respectively, as described in section 3.10. 2853 2854 When a fog option is specified in a fragment program, semantic 2855 restrictions are added to indicate that a fragment program 2856 will fail to load if the number of temporaries it contains exceeds 2857 the implementation-dependent limit minus 1, if the number of 2858 attributes it contains exceeds the implementation-dependent limit 2859 minus 1, or if the number of parameters it contains exceeds the 2860 implementation-dependent limit minus 2. 2861 2862 Additionally, when the ARB_fog_exp option is specified in a fragment 2863 program, a semantic restriction is added to indicate that a fragment 2864 program will fail to load if the number of instructions or ALU 2865 instructions it contains exceeds the implementation-dependent limit 2866 minus 3. When the ARB_fog_exp2 option is specified in a fragment 2867 program, a semantic restriction is added to indicate that a fragment 2868 program will fail to load if the number of instructions or ALU 2869 instructions it contains exceeds the implementation-dependent limit 2870 minus 4. When the ARB_fog_linear option is specified in a fragment 2871 program, a semantic restriction is added to indicate that a fragment 2872 program will fail to load if the number of instructions or ALU 2873 instructions it contains exceeds the implementation-dependent limit 2874 minus 2. 2875 2876 Only one fog application option may be specified by any given 2877 fragment program. A fragment program that specifies more than one 2878 of the program options "ARB_fog_exp", "ARB_fog_exp2", and 2879 "ARB_fog_linear", will fail to load. 2880 2881 2882 3.11.4.5.2 Precision Hint Options 2883 2884 Fragment program computations are carried out at an implementation- 2885 dependent precision. However, some implementations may be able to 2886 perform fragment program computations at more than one precision, 2887 and may be able to trade off computation precision for performance. 2888 2889 If a fragment program specifies the "ARB_precision_hint_fastest" 2890 program option, implementations should select precision to minimize 2891 program execution time, with possibly reduced precision. If a 2892 fragment program specifies the "ARB_precision_hint_nicest" program 2893 option, implementations should maximize the precision, with possibly 2894 increased execution time. 2895 2896 Only one precision control option may be specified by any given 2897 fragment program. A fragment program that specifies both the 2898 "ARB_precision_hint_fastest" and "ARB_precision_hint_nicest" program 2899 options will fail to load. 2900 2901 2902 3.11.5 Fragment Program ALU Instruction Set 2903 2904 The following sections describe the set of supported fragment 2905 program instructions. Each section contains pseudocode describing 2906 the instruction. Instructions will have up to three operands, 2907 referred to as "op0", "op1", and "op2". The operands are loaded 2908 using the mechanisms specified in section 3.11.4.1. The variables 2909 "tmp", "tmp0", "tmp1", and "tmp2" describe scalars or vectors used 2910 to hold intermediate results in the instruction. Instructions will 2911 generate a result vector called "result". The result vector is then 2912 written to the destination register specified in the instruction as 2913 described in section 3.11.4.3. 2914 2915 2916 3.11.5.1 ABS: Absolute Value 2917 2918 The ABS instruction performs a component-wise absolute value 2919 operation on the single operand to yield a result vector. 2920 2921 tmp = VectorLoad(op0); 2922 result.x = fabs(tmp.x); 2923 result.y = fabs(tmp.y); 2924 result.z = fabs(tmp.z); 2925 result.w = fabs(tmp.w); 2926 2927 2928 3.11.5.2 ADD: Add 2929 2930 The ADD instruction performs a component-wise add of the two 2931 operands to yield a result vector. 2932 2933 tmp0 = VectorLoad(op0); 2934 tmp1 = VectorLoad(op1); 2935 result.x = tmp0.x + tmp1.x; 2936 result.y = tmp0.y + tmp1.y; 2937 result.z = tmp0.z + tmp1.z; 2938 result.w = tmp0.w + tmp1.w; 2939 2940 The following rules apply to addition: 2941 2942 1. <x> + <y> == <y> + <x>, for all <x> and <y>. 2943 2. <x> + 0.0 == <x>, for all <x>. 2944 2945 2946 3.11.5.3 CMP: Compare 2947 2948 The CMP instructions performs a component-wise comparison of the 2949 first operand against zero, and copies the values of the second or 2950 third operands based on the results of the compare. 2951 2952 tmp0 = VectorLoad(op0); 2953 tmp1 = VectorLoad(op1); 2954 tmp2 = VectorLoad(op2); 2955 result.x = (tmp0.x < 0.0) ? tmp1.x : tmp2.x; 2956 result.y = (tmp0.y < 0.0) ? tmp1.y : tmp2.y; 2957 result.z = (tmp0.z < 0.0) ? tmp1.z : tmp2.z; 2958 result.w = (tmp0.w < 0.0) ? tmp1.w : tmp2.w; 2959 2960 2961 3.11.5.4 COS: Cosine 2962 2963 The COS instruction approximates the trigonometric cosine of the 2964 angle specified by the scalar operand and replicates it to all four 2965 components of the result vector. The angle is specified in radians 2966 and does not have to be in the range [-PI,PI]. 2967 2968 tmp = ScalarLoad(op0); 2969 result.x = ApproxCosine(tmp); 2970 result.y = ApproxCosine(tmp); 2971 result.z = ApproxCosine(tmp); 2972 result.w = ApproxCosine(tmp); 2973 2974 2975 3.11.5.5 DP3: Three-Component Dot Product 2976 2977 The DP3 instruction computes a three-component dot product of the 2978 two operands (using the first three components) and replicates the 2979 dot product to all four components of the result vector. 2980 2981 tmp0 = VectorLoad(op0); 2982 tmp1 = VectorLoad(op1); 2983 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + (tmp0.z * tmp1.z); 2984 result.x = dot; 2985 result.y = dot; 2986 result.z = dot; 2987 result.w = dot; 2988 2989 2990 3.11.5.6 DP4: Four-Component Dot Product 2991 2992 The DP4 instruction computes a four-component dot product of the two 2993 operands and replicates the dot product to all four components of 2994 the result vector. 2995 2996 tmp0 = VectorLoad(op0); 2997 tmp1 = VectorLoad(op1): 2998 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + 2999 (tmp0.z * tmp1.z) + (tmp0.w * tmp1.w); 3000 result.x = dot; 3001 result.y = dot; 3002 result.z = dot; 3003 result.w = dot; 3004 3005 3006 3.11.5.7 DPH: Homogeneous Dot Product 3007 3008 The DPH instruction computes a three-component dot product of the 3009 two operands (using the x, y, and z components), adds the w 3010 component of the second operand, and replicates the sum to all four 3011 components of the result vector. This is equivalent to a four- 3012 component dot product where the w component of the first operand is 3013 forced to 1.0. 3014 3015 tmp0 = VectorLoad(op0); 3016 tmp1 = VectorLoad(op1): 3017 dot = (tmp0.x * tmp1.x) + (tmp0.y * tmp1.y) + 3018 (tmp0.z * tmp1.z) + tmp1.w; 3019 result.x = dot; 3020 result.y = dot; 3021 result.z = dot; 3022 result.w = dot; 3023 3024 3025 3.11.5.8 DST: Distance Vector 3026 3027 The DST instruction computes a distance vector from two specially- 3028 formatted operands. The first operand should be of the form [NA, 3029 d^2, d^2, NA] and the second operand should be of the form [NA, 1/d, 3030 NA, 1/d], where NA values are not relevant to the calculation and d 3031 is a vector length. If both vectors satisfy these conditions, the 3032 result vector will be of the form [1.0, d, d^2, 1/d]. 3033 3034 The exact behavior is specified in the following pseudo-code: 3035 3036 tmp0 = VectorLoad(op0); 3037 tmp1 = VectorLoad(op1); 3038 result.x = 1.0; 3039 result.y = tmp0.y * tmp1.y; 3040 result.z = tmp0.z; 3041 result.w = tmp1.w; 3042 3043 Given an arbitrary vector, d^2 can be obtained using the DP3 3044 instruction (using the same vector for both operands) and 1/d can be 3045 obtained from d^2 using the RSQ instruction. 3046 3047 This distance vector is useful for per-fragment light attenuation 3048 calculations: a DP3 operation using the distance vector and an 3049 attenuation constants vector as operands will yield the attenuation 3050 factor. 3051 3052 3053 3.11.5.9 EX2: Exponential Base 2 3054 3055 The EX2 instruction approximates 2 raised to the power of the scalar 3056 operand and replicates the approximation to all four components of 3057 the result vector. 3058 3059 tmp = ScalarLoad(op0); 3060 result.x = Approx2ToX(tmp); 3061 result.y = Approx2ToX(tmp); 3062 result.z = Approx2ToX(tmp); 3063 result.w = Approx2ToX(tmp); 3064 3065 3066 3.11.5.10 FLR: Floor 3067 3068 The FLR instruction performs a component-wise floor operation on the 3069 operand to generate a result vector. The floor of a value is 3070 defined as the largest integer less than or equal to the value. The 3071 floor of 2.3 is 2.0; the floor of -3.6 is -4.0. 3072 3073 tmp = VectorLoad(op0); 3074 result.x = floor(tmp.x); 3075 result.y = floor(tmp.y); 3076 result.z = floor(tmp.z); 3077 result.w = floor(tmp.w); 3078 3079 3080 3.11.5.11 FRC: Fraction 3081 3082 The FRC instruction extracts the fractional portion of each 3083 component of the operand to generate a result vector. The 3084 fractional portion of a component is defined as the result after 3085 subtracting off the floor of the component (see FLR), and is always 3086 in the range [0.0, 1.0). 3087 3088 For negative values, the fractional portion is NOT the number 3089 written to the right of the decimal point -- the fractional portion 3090 of -1.7 is not 0.7 -- it is 0.3. 0.3 is produced by subtracting the 3091 floor of -1.7 (-2.0) from -1.7. 3092 3093 tmp = VectorLoad(op0); 3094 result.x = fraction(tmp.x); 3095 result.y = fraction(tmp.y); 3096 result.z = fraction(tmp.z); 3097 result.w = fraction(tmp.w); 3098 3099 3100 3.11.5.12 LG2: Logarithm Base 2 3101 3102 The LG2 instruction approximates the base 2 logarithm of the scalar 3103 operand and replicates it to all four components of the result 3104 vector. 3105 3106 tmp = ScalarLoad(op0); 3107 result.x = ApproxLog2(tmp); 3108 result.y = ApproxLog2(tmp); 3109 result.z = ApproxLog2(tmp); 3110 result.w = ApproxLog2(tmp); 3111 3112 If the scalar operand is zero or negative, the result is undefined. 3113 3114 3115 3.11.5.13 LIT: Light Coefficients 3116 3117 The LIT instruction accelerates per-fragment lighting by computing 3118 lighting coefficients for ambient, diffuse, and specular light 3119 contributions. The "x" component of the single operand is assumed 3120 to hold a diffuse dot product (n dot VP_pli, as in the vertex 3121 lighting equations in Section 2.13.1). The "y" component of the 3122 operand is assumed to hold a specular dot product (n dot h_i). The 3123 "w" component of the operand is assumed to hold the specular 3124 exponent of the material (s_rm), and is clamped to the range (-128, 3125 +128) exclusive. 3126 3127 The "x" component of the result vector receives the value that 3128 should be multiplied by the ambient light/material product (always 3129 1.0). The "y" component of the result vector receives the value 3130 that should be multiplied by the diffuse light/material product 3131 (n dot VP_pli). The "z" component of the result vector receives the 3132 value that should be multiplied by the specular light/material 3133 product (f_i * (n dot h_i) ^ s_rm). The "w" component of the result 3134 is the constant 1.0. 3135 3136 Negative diffuse and specular dot products are clamped to 0.0, as is 3137 done in the standard per-vertex lighting operations. In addition, 3138 if the diffuse dot product is zero or negative, the specular 3139 coefficient is forced to zero. 3140 3141 tmp = VectorLoad(op0); 3142 if (tmp.x < 0) tmp.x = 0; 3143 if (tmp.y < 0) tmp.y = 0; 3144 if (tmp.w < -(128.0-epsilon)) tmp.w = -(128.0-epsilon); 3145 else if (tmp.w > 128-epsilon) tmp.w = 128-epsilon; 3146 result.x = 1.0; 3147 result.y = tmp.x; 3148 result.z = (tmp.x > 0) ? RoughApproxPower(tmp.y, tmp.w) : 0.0; 3149 result.w = 1.0; 3150 3151 The exponentiation approximation function may be defined in terms of 3152 the base 2 exponentiation and logarithm approximation operations in 3153 the EX2 and LG2 instructions, where 3154 3155 ApproxPower(a,b) = ApproxExp2(b * ApproxLog2(a)). 3156 3157 In particular, the approximation may not be any more accurate than 3158 the underlying EX2 and LG2 operations. 3159 3160 Also, since 0^0 is defined to be 1, RoughApproxPower(0.0, 0.0) will 3161 produce 1.0. 3162 3163 3164 3.11.5.14 LRP: Linear Interpolation 3165 3166 The LRP instruction performs a component-wise linear interpolation 3167 between the second and third operands using the first operand as the 3168 blend factor. 3169 3170 tmp0 = VectorLoad(op0); 3171 tmp1 = VectorLoad(op1); 3172 tmp2 = VectorLoad(op2); 3173 result.x = tmp0.x * tmp1.x + (1 - tmp0.x) * tmp2.x; 3174 result.y = tmp0.y * tmp1.y + (1 - tmp0.y) * tmp2.y; 3175 result.z = tmp0.z * tmp1.z + (1 - tmp0.z) * tmp2.z; 3176 result.w = tmp0.w * tmp1.w + (1 - tmp0.w) * tmp2.w; 3177 3178 3179 3.11.5.15 MAD: Multiply and Add 3180 3181 The MAD instruction performs a component-wise multiply of the first two 3182 operands, and then does a component-wise add of the product to the 3183 third operand to yield a result vector. 3184 3185 tmp0 = VectorLoad(op0); 3186 tmp1 = VectorLoad(op1); 3187 tmp2 = VectorLoad(op2); 3188 result.x = tmp0.x * tmp1.x + tmp2.x; 3189 result.y = tmp0.y * tmp1.y + tmp2.y; 3190 result.z = tmp0.z * tmp1.z + tmp2.z; 3191 result.w = tmp0.w * tmp1.w + tmp2.w; 3192 3193 The multiplication and addition operations in this instruction are 3194 subject to the same rules as described for the MUL and ADD 3195 instructions. 3196 3197 3198 3.11.5.16 MAX: Maximum 3199 3200 The MAX instruction computes component-wise maximums of the values 3201 in the two operands to yield a result vector. 3202 3203 tmp0 = VectorLoad(op0); 3204 tmp1 = VectorLoad(op1); 3205 result.x = (tmp0.x > tmp1.x) ? tmp0.x : tmp1.x; 3206 result.y = (tmp0.y > tmp1.y) ? tmp0.y : tmp1.y; 3207 result.z = (tmp0.z > tmp1.z) ? tmp0.z : tmp1.z; 3208 result.w = (tmp0.w > tmp1.w) ? tmp0.w : tmp1.w; 3209 3210 3211 3.11.5.17 MIN: Minimum 3212 3213 The MIN instruction computes component-wise minimums of the values 3214 in the two operands to yield a result vector. 3215 3216 tmp0 = VectorLoad(op0); 3217 tmp1 = VectorLoad(op1); 3218 result.x = (tmp0.x > tmp1.x) ? tmp1.x : tmp0.x; 3219 result.y = (tmp0.y > tmp1.y) ? tmp1.y : tmp0.y; 3220 result.z = (tmp0.z > tmp1.z) ? tmp1.z : tmp0.z; 3221 result.w = (tmp0.w > tmp1.w) ? tmp1.w : tmp0.w; 3222 3223 3224 3.11.5.18 MOV: Move 3225 3226 The MOV instruction copies the value of the operand to yield a 3227 result vector. 3228 3229 result = VectorLoad(op0); 3230 3231 3232 3.11.5.19 MUL: Multiply 3233 3234 The MUL instruction performs a component-wise multiply of the two 3235 operands to yield a result vector. 3236 3237 tmp0 = VectorLoad(op0); 3238 tmp1 = VectorLoad(op1); 3239 result.x = tmp0.x * tmp1.x; 3240 result.y = tmp0.y * tmp1.y; 3241 result.z = tmp0.z * tmp1.z; 3242 result.w = tmp0.w * tmp1.w; 3243 3244 The following rules apply to multiplication: 3245 3246 1. <x> * <y> == <y> * <x>, for all <x> and <y>. 3247 2. +/-0.0 * <x> = +/-0.0, at least for all <x> that correspond to 3248 representable numbers (IEEE "not a number" and "infinity" 3249 encodings may be exceptions). 3250 3. +1.0 * <x> = <x>, for all <x>. 3251 3252 Multiplication by zero and one should be invariant, as it may be 3253 used to evaluate conditional expressions without branching. 3254 3255 3256 3.11.5.20 POW: Exponentiate 3257 3258 The POW instruction approximates the value of the first scalar 3259 operand raised to the power of the second scalar operand and 3260 replicates it to all four components of the result vector. 3261 3262 tmp0 = ScalarLoad(op0); 3263 tmp1 = ScalarLoad(op1); 3264 result.x = ApproxPower(tmp0, tmp1); 3265 result.y = ApproxPower(tmp0, tmp1); 3266 result.z = ApproxPower(tmp0, tmp1); 3267 result.w = ApproxPower(tmp0, tmp1); 3268 3269 The exponentiation approximation function may be implemented using 3270 the base 2 exponentiation and logarithm approximation operations in 3271 the EX2 and LG2 instructions. In particular, 3272 3273 ApproxPower(a,b) = ApproxExp2(b * ApproxLog2(a)). 3274 3275 Note that a logarithm may be involved even for cases where the 3276 exponent is an integer. This means that it may not be possible to 3277 exponentiate correctly with a negative base. In constrast, it is 3278 possible in a "normal" mathematical formulation to raise negative 3279 numbers to integral powers (e.g., (-3)^2== 9, and (-0.5)^-2==4). 3280 3281 3282 3.11.5.21 RCP: Reciprocal 3283 3284 The RCP instruction approximates the reciprocal of the scalar 3285 operand and replicates it to all four components of the result 3286 vector. 3287 3288 tmp = ScalarLoad(op0); 3289 result.x = ApproxReciprocal(tmp); 3290 result.y = ApproxReciprocal(tmp); 3291 result.z = ApproxReciprocal(tmp); 3292 result.w = ApproxReciprocal(tmp); 3293 3294 The following rule applies to reciprocation: 3295 3296 1. ApproxReciprocal(+1.0) = +1.0. 3297 3298 3299 3.11.5.22 RSQ: Reciprocal Square Root 3300 3301 The RSQ instruction approximates the reciprocal of the square root 3302 of the absolute value of the scalar operand and replicates it to all 3303 four components of the result vector. 3304 3305 tmp = fabs(ScalarLoad(op0)); 3306 result.x = ApproxRSQRT(tmp); 3307 result.y = ApproxRSQRT(tmp); 3308 result.z = ApproxRSQRT(tmp); 3309 result.w = ApproxRSQRT(tmp); 3310 3311 3312 3.11.5.23 SCS: Sine/Cosine 3313 3314 The SCS instruction approximates the trigonometric sine and cosine 3315 of the angle specified by the scalar operand and places the cosine 3316 in the x component and the sine in the y component of the result 3317 vector. The z and w components of the result vector are undefined. 3318 The angle is specified in radians and must be in the range [-PI,PI]. 3319 3320 tmp = ScalarLoad(op0); 3321 result.x = ApproxCosine(tmp); 3322 result.y = ApproxSine(tmp); 3323 3324 If the scalar operand is not in the range [-PI,PI], the result 3325 vector is undefined. 3326 3327 3328 3.11.5.24 SGE: Set On Greater or Equal Than 3329 3330 The SGE instruction performs a component-wise comparison of the two 3331 operands. Each component of the result vector is 1.0 if the 3332 corresponding component of the first operands is greater than or 3333 equal that of the second, and 0.0 otherwise. 3334 3335 tmp0 = VectorLoad(op0); 3336 tmp1 = VectorLoad(op1); 3337 result.x = (tmp0.x >= tmp1.x) ? 1.0 : 0.0; 3338 result.y = (tmp0.y >= tmp1.y) ? 1.0 : 0.0; 3339 result.z = (tmp0.z >= tmp1.z) ? 1.0 : 0.0; 3340 result.w = (tmp0.w >= tmp1.w) ? 1.0 : 0.0; 3341 3342 3343 3.11.5.25 SIN: Sine 3344 3345 The SIN instruction approximates the trigonometric sine of the angle 3346 specified by the scalar operand and replicates it to all four 3347 components of the result vector. The angle is specified in radians 3348 and does not have to be in the range [-PI,PI]. 3349 3350 tmp = ScalarLoad(op0); 3351 result.x = ApproxSine(tmp); 3352 result.y = ApproxSine(tmp); 3353 result.z = ApproxSine(tmp); 3354 result.w = ApproxSine(tmp); 3355 3356 3357 3.11.5.26 SLT: Set On Less Than 3358 3359 The SLT instruction performs a component-wise comparison of the two 3360 operands. Each component of the result vector is 1.0 if the 3361 corresponding component of the first operand is less than that of 3362 the second, and 0.0 otherwise. 3363 3364 tmp0 = VectorLoad(op0); 3365 tmp1 = VectorLoad(op1); 3366 result.x = (tmp0.x < tmp1.x) ? 1.0 : 0.0; 3367 result.y = (tmp0.y < tmp1.y) ? 1.0 : 0.0; 3368 result.z = (tmp0.z < tmp1.z) ? 1.0 : 0.0; 3369 result.w = (tmp0.w < tmp1.w) ? 1.0 : 0.0; 3370 3371 3372 3.11.5.27 SUB: Subtract 3373 3374 The SUB instruction performs a component-wise subtraction of the 3375 second operand from the first to yield a result vector. 3376 3377 tmp0 = VectorLoad(op0); 3378 tmp1 = VectorLoad(op1); 3379 result.x = tmp0.x - tmp1.x; 3380 result.y = tmp0.y - tmp1.y; 3381 result.z = tmp0.z - tmp1.z; 3382 result.w = tmp0.w - tmp1.w; 3383 3384 3385 3.11.5.28 SWZ: Extended Swizzle 3386 3387 The SWZ instruction loads the single vector operand, and performs a 3388 swizzle operation more powerful than that provided for loading 3389 normal vector operands to yield an instruction vector. 3390 3391 After the operand is loaded, the "x", "y", "z", and "w" components 3392 of the result vector are selected by the first, second, third, and 3393 fourth matches of the <xyzwExtSwizComp> or <rgbaExtSwizComp> pattern 3394 in the <extendedSwizzle> rule. 3395 3396 A result component can be selected from any of the four components 3397 of the operand or the constants 0.0 and 1.0. The result component 3398 can also be optionally negated. The following pseudocode describes 3399 the component selection method. "operand" refers to the vector 3400 operand. "select" is an enumerant where the values ZERO, ONE, X, Y, 3401 Z, and W correspond to the <xyzwExtSwizSel> rule matching "0", "1", "x", 3402 "y", "z", and "w", respectively, or the <rgbaExtSwizSel> rule 3403 matching "0", 1", "r", "g", "b", and "a", respectively. "negate" is 3404 TRUE if and only if the <optionalSign> rule in <xyzwExtSwizComp> 3405 or <rgbaExtSwizComp> matches "-". 3406 3407 float ExtSwizComponent(floatVec operand, enum select, boolean negate) 3408 { 3409 float result; 3410 switch (select) { 3411 case ZERO: result = 0.0; break; 3412 case ONE: result = 1.0; break; 3413 case X: result = operand.x; break; 3414 case Y: result = operand.y; break; 3415 case Z: result = operand.z; break; 3416 case W: result = operand.w; break; 3417 } 3418 if (negate) { 3419 result = -result; 3420 } 3421 return result; 3422 } 3423 3424 The entire extended swizzle operation is then defined using the 3425 following pseudocode: 3426 3427 tmp = VectorLoad(op0); 3428 result.x = ExtSwizComponent(tmp, xSelect, xNegate); 3429 result.y = ExtSwizComponent(tmp, ySelect, yNegate); 3430 result.z = ExtSwizComponent(tmp, zSelect, zNegate); 3431 result.w = ExtSwizComponent(tmp, wSelect, wNegate); 3432 3433 "xSelect", "xNegate", "ySelect", "yNegate", "zSelect", "zNegate", 3434 "wSelect", and "wNegate" correspond to the "select" and "negate" 3435 values above for the four <xyzwExtSwizComp> or <rgbaExtSwizComp> 3436 matches. 3437 3438 Since this instruction allows for component selection and negation 3439 for each individual component, the grammar does not allow the use of 3440 the normal swizzle and negation operations allowed for vector 3441 operands in other instructions. 3442 3443 3444 3.11.5.29 XPD: Cross Product 3445 3446 The XPD instruction computes the cross product using the first three 3447 components of its two vector operands to generate the x, y, and z 3448 components of the result vector. The w component of the result 3449 vector is undefined. 3450 3451 tmp0 = VectorLoad(op0); 3452 tmp1 = VectorLoad(op1); 3453 result.x = tmp0.y * tmp1.z - tmp0.z * tmp1.y; 3454 result.y = tmp0.z * tmp1.x - tmp0.x * tmp1.z; 3455 result.z = tmp0.x * tmp1.y - tmp0.y * tmp1.x; 3456 3457 3458 3.11.6 Fragment Program Texture Instruction Set 3459 3460 The first three texture instructions described below specify the 3461 mapping of 4-tuple vectors to colors of an image. The sampling of 3462 the texture works as described in section 3.8, except that texture 3463 environments and texture functions are not applicable, and the 3464 texture enables hierarchy is replaced by explicit references to 3465 the desired texture target (i.e., 1D, 2D, 3D, cube map, rectangle). 3466 These texture instructions specify how the 4-tuple is mapped into 3467 the coordinates used for sampling. The following function is used 3468 to describe the texture sampling in the descriptions below: 3469 3470 vec4 TextureSample(float s, float t, float r, float lodBias, 3471 int texImageUnit, enum texTarget); 3472 3473 Note that not all three texture coordinates, s, t, and r, are 3474 used by all texture targets. In particular, 1D texture targets only 3475 use the s component, and 2D and rectangle (non-power-of-two) texture 3476 targets only use the s and t components. The descriptions of the 3477 texture instructions below supply all three components, as would be 3478 the case with 3D or cube map targets. 3479 3480 If a fragment program samples from a texture target on a texture 3481 image unit where the bound texture object is not complete, as 3482 defined in section 3.8.9, the result will be the vector 3483 (R, G, B, A) = (0, 0, 0, 1). 3484 3485 A fragment program will fail to load if it attempts to sample from 3486 multiple texture targets on the same texture image unit. For 3487 example, the following program would fail to load: 3488 3489 !!ARBfp1.0 3490 TEX result.color, fragment.texcoord[0], texture[0], 2D; 3491 TEX result.depth, fragment.texcoord[1], texture[0], 3D; 3492 END 3493 3494 The fourth texture instruction described below, KIL, does not sample 3495 from a texture, but rather prevents further processing of the 3496 current fragment if any component of its 4-tuple vector is less than 3497 zero. 3498 3499 A dependent texture instruction is one that samples using a texture 3500 coordinate residing in a temporary, rather than in an attribute or 3501 a parameter. A program may have a chain of dependent texture 3502 instructions, where the result of the first texture instruction is 3503 used as the coordinate for a second texture instruction, which is in 3504 turn used as the coordinate for a third texture instruction, and so 3505 on. Each node in this chain is termed an indirection, and can be 3506 thought of as a set of texture samples that execute in parallel 3507 followed by a sequence of ALU instructions. 3508 3509 Some implementations may have limitations on how long the dependency 3510 chain may be, and so indirections are counted as a resource just 3511 like instructions or temporaries are counted. All programs have at 3512 least one indirection, or one node in this chain, even if the 3513 program performs no texture operation. Each instruction encountered 3514 is included in this node until a texture instruction is encountered 3515 3516 - whose texture coordinate is a temporary that has been previously 3517 written in the current node; or 3518 3519 - whose result vector is a temporary that is also the operand or 3520 result vector of a previous ALU instruction in the current node. 3521 3522 A new node is then started, including the texture instruction and 3523 all subsequent instructions, and the process repeats for all 3524 instructions in the program. Note that for simplicity in counting, 3525 result writemasks and operand suffixes are not taken into 3526 consideration when counting indirections. 3527 3528 3529 3.11.6.1 TEX: Map coordinate to color 3530 3531 The TEX instruction takes the first three components of 3532 its source vector, and maps them to s, t, and r. These coordinates 3533 are used to sample from the specified texture target on the 3534 specified texture image unit in a manner consistent with its 3535 parameters. The resulting sample is mapped to RGBA as described in 3536 table 3.21 and written to the result vector. 3537 3538 tmp = VectorLoad(op0); 3539 result = TextureSample(tmp.x, tmp.y, tmp.z, 0.0, op1, op2); 3540 3541 3542 3.11.6.2 TXP: Project coordinate and map to color 3543 3544 The TXP instruction divides the first three components of its source 3545 vector by the fourth component and maps the results to s, t, and r. 3546 These coordinates are used to sample from the specified texture 3547 target on the specified texture image unit in a manner consistent 3548 with its parameters. The resulting sample is mapped to RGBA as 3549 described in table 3.21 and written to the result vector. If the 3550 value of the fourth component of the source vector is less than or 3551 equal to zero, the result vector is undefined. 3552 3553 tmp = VectorLoad(op0); 3554 tmp.x = tmp.x / tmp.w; 3555 tmp.y = tmp.y / tmp.w; 3556 tmp.z = tmp.z / tmp.w; 3557 result = TextureSample(tmp.x, tmp.y, tmp.z, 0.0, op1, op2); 3558 3559 3560 3.11.6.3 TXB: Map coordinate to color while biasing its LOD 3561 3562 The TXB instruction takes the first three components of its source 3563 vector and maps them to s, t, and r. These coordinates are used to 3564 sample from the specified texture target on the specified texture 3565 image unit in a manner consistent with its parameters. 3566 Additionally, the fourth component of the source vector is applied 3567 to equation 3.14 as fragment_bias below to further bias the level of 3568 detail. 3569 3570 lambda'(x,y) = log2[p(x,y)] + 3571 clamp(texobj_bias + texunit_bias + fragment_bias) 3572 3573 The resulting sample is mapped to RGBA as described in table 3.21 3574 and written to the result vector. 3575 3576 tmp = VectorLoad(op0); 3577 result = TextureSample(tmp.x, tmp.y, tmp.z, tmp.w, op1, op2); 3578 3579 3580 3.11.6.4 KIL: Kill fragment 3581 3582 Rather than mapping a coordinate set to a color, this function 3583 prevents a fragment from receiving any future processing. If any 3584 component of its source vector is negative, the processing of this 3585 fragment will be discontinued and no further outputs to this 3586 fragment will occur. Subsequent stages of the GL pipeline will be 3587 skipped for this fragment. 3588 3589 tmp = VectorLoad(op0); 3590 if ((tmp.x < 0) || (tmp.y < 0) || 3591 (tmp.z < 0) || (tmp.w < 0)) 3592 { 3593 exit; 3594 } 3595 3596 3597 3.11.7 Program Matrices 3598 3599 In addition to GL's conventional matrices, several additional 3600 program matrices are available for use as program parameters. These 3601 matrices have names of the form MATRIX<i>_ARB where <i> is between 3602 zero and <n>-1 where <n> is the value of the implementation- 3603 dependent constant MAX_PROGRAM_MATRICES_ARB. The MATRIX<i>_ARB 3604 constants obey MATRIX<i>_ARB = MATRIX0_ARB + <i>. The value of 3605 MAX_PROGRAM_MATRICES_ARB must be at least eight. The maximum stack 3606 depth for program matrices is defined by the 3607 MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB and must be at least 1. 3608 3609 3610 3.11.8 Required Fragment Program State 3611 3612 The state required to support program objects of all targets 3613 consists of: 3614 3615 an integer for the program error position, initially -1; 3616 3617 an array of ubytes for the program error string, initially empty; 3618 3619 and the state that must be maintained to indicate which integers 3620 are currently in use as program object names. 3621 3622 The state required to support the fragment program target consists 3623 of: 3624 3625 a bit indicating whether or not fragment program mode is enabled, 3626 initially disabled; 3627 3628 a set of MAX_PROGRAM_ENV_PARAMETERS_ARB four-component floating- 3629 point program environment parameters, initially set to (0,0,0,0); 3630 3631 an unsigned integer naming the currently bound fragment program, 3632 initially zero; 3633 3634 The state required for each fragment program object consists of: 3635 3636 an unsigned integer indicating the program object name; 3637 3638 an array of type ubyte containing the program string, initially 3639 empty; 3640 3641 an unsigned integer holding the length of the program string, 3642 initially zero; 3643 3644 an enum indicating the program string format, initially 3645 PROGRAM_FORMAT_ASCII_ARB; 3646 3647 a bit indicating whether or not the program exceeds the native 3648 limits; 3649 3650 six unsigned integers holding the number of instruction (ALU, 3651 texture, and total), texture indirection, temporary variable, and 3652 program parameter binding resources used by the program, initially 3653 all zero; 3654 3655 six unsigned integers holding the number of native instruction 3656 (ALU, texture, and total), texture indirection, temporary 3657 variable, and program parameter binding resources used by the 3658 program, initially all zero; 3659 3660 and a set of MAX_PROGRAM_LOCAL_PARAMETERS_ARB four-component 3661 floating-point program local parameters, initially set to 3662 (0,0,0,0). 3663 3664 Initially, no fragment program objects exist. 3665 3666 3667Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment 3668Operations and the Frame Buffer) 3669 3670 None 3671 3672 3673Additions to Chapter 5 of the OpenGL 1.3 Specification (Special 3674Functions) 3675 3676 Modify Section 5.4, Display Lists (p. 191) 3677 3678 (modify third paragraph, p. 195) ... These are IsList, GenLists, 3679 ..., IsProgramARB, GenProgramsARB, and DeleteProgramsARB, as well as 3680 IsEnabled and all the Get commands (chapter 6). 3681 3682 3683Additions to Chapter 6 of the OpenGL 1.3 Specification (State and 3684State Requests) 3685 3686 Modify Section 6.1.2, Data Conversions (p. 198) 3687 3688 (add before last paragraph, p. 198) The matrix selected by the 3689 current matrix mode can be queried by calling GetBooleanv, 3690 GetIntegerv, GetFloatv, and GetDoublev with <pname> set to 3691 CURRENT_MATRIX_ARB; the matrix will be returned in transposed form 3692 with <pname> set to TRANSPOSE_CURRENT_MATRIX_ARB. The depth of the 3693 selected matrix stack can be queried with <pname> set to 3694 CURRENT_MATRIX_STACK_DEPTH_ARB. Querying CURRENT_MATRIX_ARB and 3695 CURRENT_MATRIX_STACK_DEPTH_ARB is the only means for querying the 3696 matrix and matrix stack depth of the program matrices described in 3697 section 3.11.7. 3698 3699 3700 (add to end of last paragraph, p. 199) Queries of texture state 3701 variables corresponding to texture coordinate processing unit 3702 (namely, TexGen state and enables, and matrices) will produce an 3703 INVALID_OPERATION error if the value of ACTIVE_TEXTURE is greater 3704 than or equal to MAX_TEXTURE_COORDS_ARB. All other texture state 3705 queries will result in an INVALID_OPERATION error if the value of 3706 ACTIVE_TEXTURE is greater than or equal to 3707 MAX_TEXTURE_IMAGE_UNITS_ARB. 3708 3709 3710 Modify Section 6.1.11, Pointer and String Queries (p. 206) 3711 3712 (modify last paragraph, p. 206) ... The possible values for <name> 3713 are VENDOR, RENDERER, VERSION, EXTENSIONS, and 3714 PROGRAM_ERROR_STRING_ARB. 3715 3716 3717 (add after last paragraph of section, p. 207) Queries of 3718 PROGRAM_ERROR_STRING_ARB return a pointer to an implementation- 3719 dependent program load error string. If the last call to 3720 ProgramStringARB failed to load a program, the returned string 3721 describes at least one reason why the program failed to load. If 3722 the last call to ProgramStringARB successfully loaded a program, the 3723 returned string may be empty (containing only a zero terminator) or 3724 may contain one or more implementation-dependent warning messages. 3725 The contents of the error string are guaranteed to remain constant 3726 only until the next ProgramStringARB command, which may overwrite 3727 the error string. 3728 3729 3730 Insert a new Section 6.1.12, Program Queries (p. 207), between 3731 existing sections 6.1.11 and 6.1.12. 3732 3733 6.1.12 Program Queries 3734 3735 The commands 3736 3737 void GetProgramEnvParameterdvARB(enum target, uint index, 3738 double *params); 3739 void GetProgramEnvParameterfvARB(enum target, uint index, 3740 float *params); 3741 3742 obtain the current value for the program environment parameter 3743 numbered <index> for the given program target <target>, and places 3744 the information in the array <params>. The error INVALID_ENUM is 3745 generated if <target> specifies a nonexistent program target or a 3746 program target that does not support program environment parameters. 3747 The error INVALID_VALUE is generated if <index> is greater than or 3748 equal to the implementation-dependent number of supported program 3749 environment parameters for the program target. 3750 3751 When <target> is FRAGMENT_PROGRAM_ARB, each program parameter 3752 returned is an array of four values. 3753 3754 The commands 3755 3756 void GetProgramLocalParameterdvARB(enum target, uint index, 3757 double *params); 3758 void GetProgramLocalParameterfvARB(enum target, uint index, 3759 float *params); 3760 3761 obtain the current value for the program local parameter numbered 3762 <index> belonging to the program object currently bound to <target>, 3763 and places the information in the array <params>. The error 3764 INVALID_ENUM is generated if <target> specifies a nonexistent 3765 program target or a program target that does not support program 3766 local parameters. The error INVALID_VALUE is generated if <index> 3767 is greater than or equal to the implementation-dependent number of 3768 supported program local parameters for the program target. 3769 3770 When the program target type is FRAGMENT_PROGRAM_ARB, each program 3771 local parameter returned is an array of four values. 3772 3773 The command 3774 3775 void GetProgramivARB(enum target, enum pname, int *params); 3776 3777 obtains program state for the program target <target>, writing the 3778 state into the array given by <params>. GetProgramivARB can be used 3779 to determine the properties of the currently bound program object or 3780 implementation limits for <target>. 3781 3782 If <pname> is PROGRAM_LENGTH_ARB, PROGRAM_FORMAT_ARB, or 3783 PROGRAM_BINDING_ARB, GetProgramivARB returns one integer holding the 3784 program string length (in bytes), program string format, and program 3785 name, respectively, for the program object currently bound to 3786 <target>. 3787 3788 If <pname> is MAX_PROGRAM_LOCAL_PARAMETERS_ARB or 3789 MAX_PROGRAM_ENV_PARAMETERS_ARB, GetProgramivARB returns one integer 3790 holding the maximum number of program local parameters or program 3791 environment parameters, respectively, supported for the program 3792 target <target>. 3793 3794 If <pname> is MAX_PROGRAM_INSTRUCTIONS_ARB, 3795 MAX_PROGRAM_ALU_INSTRUCTIONS_ARB, MAX_PROGRAM_TEX_INSTRUCTIONS_ARB, 3796 MAX_PROGRAM_TEX_INDIRECTIONS_ARB, MAX_PROGRAM_TEMPORARIES_ARB, 3797 MAX_PROGRAM_PARAMETERS_ARB, or MAX_PROGRAM_ATTRIBS_ARB, 3798 GetProgramivARB returns a single integer giving the maximum number 3799 of total instructions, ALU instructions, texture instructions, 3800 texture indirections, temporaries, parameters, and attributes that 3801 can be used by a program of type <target>. If <pname> is 3802 PROGRAM_INSTRUCTIONS_ARB, PROGRAM_ALU_INSTRUCTIONS_ARB, 3803 PROGRAM_TEX_INSTRUCTIONS_ARB, PROGRAM_TEX_INDIRECTIONS_ARB, 3804 PROGRAM_TEMPORARIES_ARB, PROGRAM_PARAMETERS_ARB, or 3805 PROGRAM_ATTRIBS_ARB, GetProgramivARB returns a single integer giving 3806 the number of total instructions, ALU instructions, texture 3807 instructions, texture indirections, temporaries, parameters, and 3808 attributes used by the current program for <target>. 3809 3810 If <pname> is MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB, 3811 MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB, 3812 MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB, 3813 MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB, 3814 MAX_PROGRAM_NATIVE_TEMPORARIES_ARB, 3815 MAX_PROGRAM_NATIVE_PARAMETERS_ARB, or 3816 MAX_PROGRAM_NATIVE_ATTRIBS_ARB, GetProgramivARB returns a single 3817 integer giving the maximum number of native instruction, ALU 3818 instruction, texture instruction, texture indirection, temporary, 3819 parameter, and attribute resources available to a program of type 3820 <target>. If <pname> is PROGRAM_NATIVE_INSTRUCTIONS_ARB, 3821 PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB, 3822 PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB, 3823 PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB, 3824 PROGRAM_NATIVE_TEMPORARIES_ARB, PROGRAM_NATIVE_PARAMETERS_ARB, or 3825 PROGRAM_NATIVE_ATTRIBS_ARB, GetProgramivARB returns a single integer 3826 giving the number of native instruction, ALU instruction, texture 3827 instruction, texture indirection, temporary, parameter, and 3828 attribute resources consumed by the program currently bound to 3829 <target>. Native resource counts will reflect the results of 3830 implementation-dependent scheduling and optimization algorithms 3831 applied by the GL, as well as emulation of non-native features. If 3832 <pname> is PROGRAM_UNDER_NATIVE_LIMITS_ARB, GetProgramivARB returns 3833 0 if the native resource consumption of the program currently bound 3834 to <target> exceeds the number of available resources for any 3835 resource type, and 1 otherwise. 3836 3837 The command 3838 3839 void GetProgramStringARB(enum target, enum pname, void *string); 3840 3841 obtains the program string for the program object bound to <target> 3842 and places the information in the array <string>. <pname> must be 3843 PROGRAM_STRING_ARB. <n> ubytes are returned into the array program 3844 where <n> is the length of the program in ubytes, as returned by 3845 GetProgramivARB when <pname> is PROGRAM_LENGTH_ARB. The program 3846 string is always returned using the format given when the program 3847 string was specified. 3848 3849 The command 3850 3851 boolean IsProgramARB(uint program); 3852 3853 returns TRUE if <program> is the name of a program object. If 3854 <program> is zero or is a non-zero value that is not the name of a 3855 program object, or if an error condition occurs, IsProgramARB 3856 returns FALSE. A name returned by GenProgramsARB, but not yet 3857 bound, is not the name of a program object. 3858 3859 3860 Modify Section 6.2, State Tables (p. 216) 3861 3862 (add to caption of Table 6.5) When accessing the current texture 3863 coordinates (CURRENT_TEXTURE_COORDS) or the texture coordinates 3864 associated with raster position (CURRENT_RASTER_TEXTURE_COORDS), the 3865 active texture unit selector (ACTIVE_TEXTURE) must be less than the 3866 implementation dependent maximum number of texture coordinate sets 3867 (MAX_TEXTURE_COORDS_ARB). 3868 3869 (add to caption of Table 6.8) When accessing the texture matrix 3870 stack (TEXTURE_MATRIX, TRANSPOSE_TEXTURE_MATRIX) or the texture 3871 matrix stack pointer (TEXTURE_STACK_DEPTH), the active texture unit 3872 selector (ACTIVE_TEXTURE) must be less than the implementation 3873 dependent maximum number of texture coordinate sets 3874 (MAX_TEXTURE_COORDS_ARB). 3875 3876 (split Table 6.17 into two tables, Texture Environment and Texture 3877 Coordinate Generation; move active texture unit selector and texture 3878 coordinate generation state to table 6.18; renumber subsequent 3879 tables) 3880 3881 (add to captions of Tables 6.14, 6.15, 6.16) The active texture unit 3882 selector (ACTIVE_TEXTURE) identifies which texture object is 3883 accessed, and must be less than the implementation dependent maximum 3884 number of texture image units (MAX_TEXTURE_IMAGE_UNITS_ARB). 3885 3886 (add to caption of Table 6.18) With the exception of ACTIVE_TEXTURE, 3887 the active texture unit selector (ACTIVE_TEXTURE) identifies which 3888 texture coordinate set is accessed, and must be less than the 3889 implementation dependent maximum number of texture coordinate sets 3890 (MAX_TEXTURE_COORDS_ARB). 3891 3892Additions to Appendix A of the OpenGL 1.3 Specification (Invariance) 3893 3894 Add to end of Section A.3 (p. 242): 3895 3896 Rule 4. Fragment program instructions not relevant to the 3897 calculation of any result must have no effect on that result. 3898 3899 Rule 5. Fragment program instructions relevant to the calculation 3900 of any result must always produce the identical result. 3901 3902 Instructions relevant to the calculation of a result are any 3903 instructions in a sequence of instructions that eventually determine 3904 the source values for the calculation under consideration. 3905 3906 There is no guaranteed invariance between fragment colors generated 3907 by conventional GL texturing mode and fragment colors generated by 3908 fragment program mode. Multi-pass rendering algorithms that require 3909 rendering invariances to operate correctly should not mix 3910 conventional GL fragment texturing mode with fragment program mode 3911 for different rendering passes. However, such algorithms will 3912 operate correctly if the algorithms limit themselves to a single 3913 mode of fragment color generation. 3914 3915 There is no guaranteed invariance between the final z window 3916 coordinates of fragments processed by fragment programs that write 3917 depth values and fragments processed by any other means, even if the 3918 fragment programs in question simply copy the z value from the 3919 "fragment.position" binding. Multi-pass rendering algorithms that 3920 use depth-replacing fragment programs should use depth-replacing 3921 fragment programs on each pass to guarantee identical z values. 3922 3923 The texture sample chosen for a fragment of a primitive must be 3924 invariant between fragment program mode and conventional texture 3925 application mode subject to these conditions: 3926 3927 1. All state with the exception of fragment program state is 3928 identical 3929 3930 2. The primitives generating the fragments are identical 3931 3932 3. The sample in the fragment program mode is the result of a 3933 'TEX' instruction (or a 'TXP' instruction with a unity q) 3934 3935 4. The texture coordinate operand for the texture instruction uses 3936 the same texture coordinate set as the conventional mode sample 3937 3938 5. The texture coordinate operand for the texture instruction has 3939 not been the result of any other operations in the fragment 3940 program 3941 3942 3943Additions to the AGL/GLX/WGL Specifications 3944 3945 Program objects are shared between AGL/GLX/WGL rendering contexts if 3946 and only if the rendering contexts share display lists. No change 3947 is made to the AGL/GLX/WGL API. 3948 3949 Changes to program objects shared between multiple rendering 3950 contexts will be serialized (i.e., the changes will occur in a 3951 specific order). 3952 3953 Changes to a program object made by one rendering context are not 3954 guaranteed to take effect in another rendering context until the 3955 other calls BindProgram to bind the program object. 3956 3957 When a program object is deleted by one rendering context, the 3958 object itself is not destroyed until it is no longer the current 3959 program object in any context. However, the name of the deleted 3960 object is removed from the program object name space, so the next 3961 attempt to bind a program using the same name will create a new 3962 program object. Recall that destroying a program object bound in 3963 the current rendering context effectively unbinds the object being 3964 destroyed. 3965 3966 3967Dependencies on OpenGL 1.4 3968 3969 If OpenGL 1.4 is not supported, the modified equation for the 3970 calculation of level of detail by the TXB instruction in 3.11.6.3 3971 should read 3972 3973 lambda'(x,y) = log2[p(x,y)] + 3974 clamp(texunit_bias + fragment_bias) 3975 3976Dependencies on EXT_vertex_weighting and ARB_vertex_blend 3977 3978 If EXT_vertex_weighting and ARB_vertex_blend are both not supported, 3979 all discussions of multiple modelview matrices should be removed. 3980 3981 In particular, the line in the grammar 3982 3983 <stateMatrixName> ::= "modelview" <stateOptModMatNum> 3984 3985 should be changed to 3986 3987 <stateMatrixName> ::= "modelview" 3988 3989 and the rules <stateOptModMatNum> and <stateModMatNum> should be 3990 deleted. The first line of Table X.2.7 should be modified to read: 3991 3992 Binding Underlying State 3993 ------------------------------------ --------------------------- 3994 state.matrix.modelview modelview matrix 3995 3996 The caption for Table X.2.7 should be modified to exclude optional 3997 modelview matrix number. Subsequent references to "modelview matrix 3998 zero" and "modelview matrix 1" should be changed to "modelview 3999 matrix" and the example "state.matrix.modelview[1].row[0]" should be 4000 changed to "state.matrix.modelview.row[0]". 4001 4002 4003Dependencies on ARB_matrix_palette: 4004 4005 If ARB_matrix_palette is not supported, all discussions of the 4006 matrix palette should be removed. 4007 4008 In particular, the line 4009 4010 "palette" "[" <statePaletteMatNum> "]" 4011 4012 should be removed from the <stateMatrixName> grammar rule, and the 4013 <statePaletteMatNum> grammar rule should be removed entirely. 4014 "state.matrix.palette[n]" should be removed from Table X.2.7. 4015 4016 4017Dependencies on ARB_transpose_matrix 4018 4019 If ARB_transpose_matrix is not supported, the discussion of 4020 TRANSPOSE_CURRENT_MATRIX_ARB in the edits to section 6.1.2 should be 4021 removed. 4022 4023 4024Dependencies on EXT_fog_coord 4025 4026 If EXT_fog_coord is not supported, references to "fog coordinate" 4027 in the definition of the "fragment.fogcoord" attribute should be 4028 removed. 4029 4030Dependencies on EXT_texture_rectangle 4031 4032 If NV_texture_rectangle is not supported, the discussion of the 4033 rectangle (non-power-of-two) texture target in section 3.11.6 should 4034 be removed, and the line 4035 4036 "RECT" 4037 4038 should be removed from the <texTarget> grammar rule. 4039 4040 4041Interactions with ARB_shadow 4042 4043 The texture comparison introduced by ARB_shadow can be expressed in 4044 terms of a fragment program, and in fact use the same internal 4045 resources on some implementations. Therefore, if fragment program 4046 mode is enabled, the GL behaves as if TEXTURE_COMPARE_MODE_ARB is 4047 NONE. 4048 4049 4050Interactions with ARB_vertex_program 4051 4052 The program object management entrypoints described in sections 4053 2.14.1 (for vertex programs) and 3.11.1 (for fragment programs) 4054 are shared by both program targets. The PROGRAM_ERROR_STRING_ARB 4055 and program queries in sections 6.1.11 and 6.1.12 are also shared, 4056 as are all common tokens. 4057 4058 The Errors section should be modified to generate INVALID_OPERATION 4059 from the Get command with argument CURRENT_MATRIX_ARB, 4060 TRANSPOSE_CURRENT_MATRIX_ARB, and CURRENT_MATRIX_STACK_DEPTH_ARB 4061 when the current matrix mode is TEXTURE. 4062 4063 In the presence of ARB_vertex_program, ARB_fragment_program must 4064 recognize and return appropriate values for the GetProgram <pname> 4065 tokens introduced in that spec but not otherwise shared by 4066 ARB_fragment_program: 4067 4068 PROGRAM_ADDRESS_REGISTERS_ARB 0x88B0 4069 MAX_PROGRAM_ADDRESS_REGISTERS_ARB 0x88B1 4070 PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 0x88B2 4071 MAX_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 0x88B3 4072 4073 The following tables list new program object state and 4074 implementation-dependent state: 4075 4076 Get Value Type Get Command Initial Value Description Sec Attrib 4077 -------------------- ----- ------------------- --------------- ---------------------- -------- ------ 4078 PROGRAM_ADDRESS_REGISTERS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4079 address registers 4080 PROGRAM_NATIVE_ADDRESS_ Z+ GetProgramivARB 0 bound program native 6.1.12 - 4081 REGISTERS_ARB address registers 4082 4083 Table X.7. Program Object State. Program object queries return attributes of 4084 the program object currently bound to the program target <target>. 4085 4086 4087 Minimum 4088 Get Value Type Get Command Value Description Sec. Attrib 4089 --------- ---- ----------- ------- ----------- ---- ------ 4090 MAX_PROGRAM_ADDRESS_REGISTERS_ARB Z+ GetProgramivARB 0 maximum program 6.1.12 - 4091 address registers 4092 MAX_PROGRAM_NATIVE_ADDRESS_ Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4093 REGISTERS_ARB address registers 4094 4095 Table X.10. New Implementation-Dependent Values Introduced by 4096 ARB_vertex_program. 4097 4098 4099 In the presence of ARB_fragment_program, ARB_vertex_program must 4100 recognize and return appropriate values for the GetProgram <pname> 4101 tokens introduced in this spec. The following tables list new 4102 program object state and implementation-dependent state: 4103 4104 Get Value Type Get Command Initial Value Description Sec Attrib 4105 -------------------- ----- ------------------- --------------- ---------------------- -------- ------ 4106 PROGRAM_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program 6.1.12 - 4107 ALU instructions 4108 PROGRAM_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program 6.1.12 - 4109 texture instructions 4110 PROGRAM_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 maximum program 6.1.12 - 4111 texture indirections 4112 PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4113 ALU instructions 4114 PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4115 texture instructions 4116 PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4117 texture indirections 4118 4119 Table X.7. Program Object State. Program object queries return attributes of 4120 the program object currently bound to the program target <target>. 4121 4122 4123 Minimum 4124 Get Value Type Get Command Value Description Sec. Attrib 4125 --------- ---- ----------- ------- ----------- ---- ------ 4126 MAX_PROGRAM_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 Number of frag. prg. 6.1.12 - 4127 ALU instructions 4128 MAX_PROGRAM_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 Number of frag. prg. 6.1.12 - 4129 texture instructions 4130 MAX_PROGRAM_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 Number of frag. prg. 6.1.12 - 4131 texture indirections 4132 MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4133 ALU instructions 4134 MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4135 texture instructions 4136 MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 maximum program native 6.1.12 - 4137 texture indirections 4138 4139 Table X.10. New Implementation-Dependent Values Introduced by 4140 ARB_fragment_program. 4141 4142 4143Interactions with ATI_fragment_shader 4144 4145 The existing ATI_fragment_shader extension, if supported, also 4146 provides a similar fragment programming model. Mixing the two 4147 models in a single application is possible but not recommended. 4148 FRAGMENT_PROGRAM_ARB has priority over FRAGMENT_SHADER_ATI if 4149 both are enabled. 4150 4151 4152Interactions with NV_fragment_program 4153 4154 The NV_fragment_program extension, if supported, also provides a 4155 similar programming model. This extension is incompatible with 4156 NV_fragment_program in a number of different ways. Mixing the two 4157 models in a single application is possible but not recommended. The 4158 interactions between the extensions are defined below. 4159 4160 Functions, enumerants, and programs defined in NV_fragment_program 4161 are called "NV functions", "NV enumerants", and "NV programs," 4162 respectively. Functions, enumerants, and programs defined in 4163 ARB_fragment_program are called "ARB functions", "ARB enumerants", 4164 and "ARB programs," respectively. 4165 4166 The following GL state is identical in the two extensions: 4167 4168 - Fragment program mode enable. The NV and ARB enumerants have 4169 different values, but the same effect. 4170 4171 - Program error position. 4172 4173 - Program error string. 4174 4175 - NV_fragment_program and ARB_fragment_program "program local 4176 parameters." 4177 4178 - Fragment program names, targets, formats, program string, 4179 program string lengths, and residency information. The ARB and 4180 NV query functions operate differently. The ARB query function 4181 does not allow queries of target (passed in to the query) and 4182 residency information. The NV query function does not allow 4183 queries of program name (passed in to the query) or format. The 4184 format of NV programs is always PROGRAM_FORMAT_ASCII_ARB. 4185 4186 - Program object name space. Program objects are created 4187 differently in the NV and ARB specs. Under the NV spec, program 4188 objects are created by calling LoadProgramNV. Under the ARB 4189 spec, program objects are created by calling BindProgramARB with 4190 an unused program name. 4191 4192 The following state is provided only by ARB_fragment_program: 4193 4194 - Program environment parameters. 4195 4196 - Implementation-dependent limits on the number of instructions, 4197 ALU instructions, texture instructions, texture indirections, 4198 program parameters, fragment attributes, resource counts, and 4199 native resource counts. The instruction limit is baked into the 4200 NV spec. Implementations supporting NV_fragment_program have no 4201 specific restrictions on the number of ALU instructions, texture 4202 instructions, texture indirections, or fragment attributes used. 4203 Such implementations also have no limit on program parameters 4204 used, except that no more than one may be used by any single 4205 program instruction. 4206 4207 The following state is provided only by NV_fragment_program: 4208 4209 - Named program parameters (variables defined in the program text 4210 and updated by name). 4211 4212 The following are additional functional differences between 4213 ARB_fragment_program and NV_fragment_program: 4214 4215 - NV programs use a set of register names, with no support for 4216 user-defined variables (other than parameters in the program). 4217 ARB programs provide no support for fixed variable names; all 4218 variables must be declared, explicitly or implicitly, in the 4219 program. 4220 4221 - ARB programs support parameter variables that can be bound to 4222 selected GL state variables, and are updated automatically when 4223 the underlying state changes. NV programs provide no such 4224 support; applications must set program parameters themselves. 4225 4226 - ARB_fragment_program doesn't provide explicit support for 4227 multiple data types (fx12, fp16, fp32) described in 4228 NV_fragment_program, and provides no mechanism for controlling 4229 the precision used to carry out arithmetic operations. 4230 4231 - ARB_fragment_program doesn't support condition codes, 4232 conditional writemasks, or the "C" instruction suffix that 4233 specifies a condition code update. 4234 4235 - ARB_fragment_program doesn't support an absolute value operator 4236 that can be applied to a source vector as it is loaded. 4237 4238 - ARB_fragment_program doesn't define behavior for many floating- 4239 point special cases. On platforms where NV_fragment_program is 4240 supported, ARB programs will have the same special-case 4241 behavior. 4242 4243 - Language to declare program parameters is slightly different 4244 (NV_fragment_program has "DECLARE" and "DEFINE"; 4245 ARB_fragment_program has "PARAM"). 4246 4247 - NV_fragment_program provides a number of instructions not found 4248 in ARB_fragment_program: 4249 4250 * DDX, DDY: partial derivatives relative to x and y. 4251 4252 * "PK*" and "UP*": packing and unpacking instructions. 4253 4254 * RFL: reflection vector. 4255 4256 * SEQ, SFL, SGT, SLE, SNE, STR: set on equal, false, greater 4257 than, less than or equal, not equal, and true, respectively. 4258 4259 * TXD: texture lookup w/partials. 4260 4261 * X2D: 2D coordinate transformation. 4262 4263 - ARB_fragment_program provides several instructions not found in 4264 NV_fragment_program, and there are a few instruction set 4265 differences: 4266 4267 * ABS: absolute value. ABS instructions are unnecessary in 4268 NV_fragment_program because of the free absolute value on 4269 input operator. Equivalent to: 4270 4271 MOV dst, |src|; 4272 4273 * CMP: compare. Roughly equivalent to the following 4274 sequence, but may be optimized further: 4275 4276 SLT tmp, src0; 4277 LRP dst, tmp, src1, src2; 4278 4279 * DPH: homogenous dot product. Equivalent to: 4280 4281 DP3 tmp, src0, src1; 4282 ADD dst, tmp, src0.w; 4283 4284 * KIL: kill fragment. Both extensions support this 4285 instruction, but the ARB instruction takes a vector 4286 operand rather than a condition code. 4287 4288 * SCS: sine/cosine. Emulated using the separate SIN and COS 4289 instructions in NV_fragment_program, which also have no 4290 restriction on the input values. 4291 4292 * SWZ: extended swizzle. On NV_fragment_program platforms, 4293 this instruction will be emulated using a single MAD 4294 instruction and a program parameter constant. 4295 4296 * TXB: texture sample with bias. Not exposed in the 4297 NV_fragment_program API. 4298 4299 * XPD: cross product. Emulated using a MUL and a MAD 4300 instruction. 4301 4302 4303GLX Protocol 4304 4305 The following rendering commands are sent to the server as part of 4306 a glXRender request: 4307 4308 BindProgramARB 4309 2 12 rendering command length 4310 2 4180 rendering command opcode 4311 4 ENUM target 4312 4 CARD32 program 4313 4314 ProgramEnvParameter4fvARB 4315 2 32 rendering command length 4316 2 4184 rendering command opcode 4317 4 ENUM target 4318 4 CARD32 index 4319 4 FLOAT32 params[0] 4320 4 FLOAT32 params[1] 4321 4 FLOAT32 params[2] 4322 4 FLOAT32 params[3] 4323 4324 ProgramEnvParameter4dvARB 4325 2 44 rendering command length 4326 2 4185 rendering command opcode 4327 4 ENUM target 4328 4 CARD32 index 4329 8 FLOAT64 params[0] 4330 8 FLOAT64 params[1] 4331 8 FLOAT64 params[2] 4332 8 FLOAT64 params[3] 4333 4334 ProgramLocalParameter4fvARB 4335 2 32 rendering command length 4336 2 4215 rendering command opcode 4337 4 ENUM target 4338 4 CARD32 index 4339 4 FLOAT32 params[0] 4340 4 FLOAT32 params[1] 4341 4 FLOAT32 params[2] 4342 4 FLOAT32 params[3] 4343 4344 ProgramLocalParameter4dvARB 4345 2 44 rendering command length 4346 2 4216 rendering command opcode 4347 4 ENUM target 4348 4 CARD32 index 4349 8 FLOAT64 params[0] 4350 8 FLOAT64 params[1] 4351 8 FLOAT64 params[2] 4352 8 FLOAT64 params[3] 4353 4354 The ProgramStringARB is potentially large, and hence can be sent in 4355 a glXRender or glXRenderLarge request. 4356 4357 ProgramStringARB 4358 2 16+len+p rendering command length 4359 2 4217 rendering command opcode 4360 4 ENUM target 4361 4 ENUM format 4362 4 sizei len 4363 len LISTofBYTE program 4364 p unused, p=pad(len) 4365 4366 If the command is encoded in a glxRenderLarge request, the 4367 command opcode and command length fields above are expanded to 4368 4 bytes each: 4369 4370 4 16+len+p rendering command length 4371 4 4217 rendering command opcode 4372 4373 The remaining commands are non-rendering commands. These commands 4374 are sent separately (i.e., not as part of a glXRender or 4375 glXRenderLarge request), using the glXVendorPrivateWithReply 4376 request: 4377 4378 DeleteProgramsARB 4379 1 CARD8 opcode (X assigned) 4380 1 17 GLX opcode (glXVendorPrivateWithReply) 4381 2 4+n request length 4382 4 1294 vendor specific opcode 4383 4 GLX_CONTEXT_TAG context tag 4384 4 INT32 n 4385 n*4 LISTofCARD32 programs 4386 4387 GenProgramsARB 4388 1 CARD8 opcode (X assigned) 4389 1 17 GLX opcode (glXVendorPrivateWithReply) 4390 2 4 request length 4391 4 1295 vendor specific opcode 4392 4 GLX_CONTEXT_TAG context tag 4393 4 INT32 n 4394 => 4395 1 1 reply 4396 1 unused 4397 2 CARD16 sequence number 4398 4 n reply length 4399 24 unused 4400 n*4 LISTofCARD322 programs 4401 4402 GetProgramEnvParameterfvARB 4403 1 CARD8 opcode (X assigned) 4404 1 17 GLX opcode (glXVendorPrivateWithReply) 4405 2 6 request length 4406 4 1296 vendor specific opcode 4407 4 GLX_CONTEXT_TAG context tag 4408 4 ENUM target 4409 4 CARD32 index 4410 4 ENUM pname 4411 => 4412 1 1 reply 4413 1 unused 4414 2 CARD16 sequence number 4415 4 m reply length, m=(n==1?0:n) 4416 4 unused 4417 4 CARD32 n (number of parameter components) 4418 4419 if (n=1) this follows: 4420 4421 4 FLOAT32 params 4422 12 unused 4423 4424 otherwise this follows: 4425 4426 16 unused 4427 n*4 LISTofFLOAT32 params 4428 4429 GetProgramEnvParameterdvARB 4430 1 CARD8 opcode (X assigned) 4431 1 17 GLX opcode (glXVendorPrivateWithReply) 4432 2 6 request length 4433 4 1297 vendor specific opcode 4434 4 GLX_CONTEXT_TAG context tag 4435 4 ENUM target 4436 4 CARD32 index 4437 4 ENUM pname 4438 => 4439 1 1 reply 4440 1 unused 4441 2 CARD16 sequence number 4442 4 m reply length, m=(n==1?0:n*2) 4443 4 unused 4444 4 CARD32 n (number of parameter components) 4445 4446 if (n=1) this follows: 4447 4448 8 FLOAT64 params 4449 8 unused 4450 4451 otherwise this follows: 4452 4453 16 unused 4454 n*8 LISTofFLOAT64 params 4455 4456 GetProgramLocalParameterfvARB 4457 1 CARD8 opcode (X assigned) 4458 1 17 GLX opcode (glXVendorPrivateWithReply) 4459 2 6 request length 4460 4 1305 vendor specific opcode 4461 4 GLX_CONTEXT_TAG context tag 4462 4 ENUM target 4463 4 CARD32 index 4464 4 ENUM pname 4465 => 4466 1 1 reply 4467 1 unused 4468 2 CARD16 sequence number 4469 4 m reply length, m=(n==1?0:n) 4470 4 unused 4471 4 CARD32 n (number of parameter components) 4472 4473 if (n=1) this follows: 4474 4475 4 FLOAT32 params 4476 12 unused 4477 4478 otherwise this follows: 4479 4480 16 unused 4481 n*4 LISTofFLOAT32 params 4482 4483 GetProgramLocalParameterdvARB 4484 1 CARD8 opcode (X assigned) 4485 1 17 GLX opcode (glXVendorPrivateWithReply) 4486 2 6 request length 4487 4 1306 vendor specific opcode 4488 4 GLX_CONTEXT_TAG context tag 4489 4 ENUM target 4490 4 CARD32 index 4491 4 ENUM pname 4492 => 4493 1 1 reply 4494 1 unused 4495 2 CARD16 sequence number 4496 4 m reply length, m=(n==1?0:n*2) 4497 4 unused 4498 4 CARD32 n (number of parameter components) 4499 4500 if (n=1) this follows: 4501 4502 8 FLOAT64 params 4503 8 unused 4504 4505 otherwise this follows: 4506 4507 16 unused 4508 n*8 LISTofFLOAT64 params 4509 4510 GetProgramivARB 4511 1 CARD8 opcode (X assigned) 4512 1 17 GLX opcode (glXVendorPrivateWithReply) 4513 2 5 request length 4514 4 1307 vendor specific opcode 4515 4 GLX_CONTEXT_TAG context tag 4516 4 ENUM target 4517 4 ENUM pname 4518 => 4519 1 1 reply 4520 1 unused 4521 2 CARD16 sequence number 4522 4 m reply length, m=(n==1?0:n) 4523 4 unused 4524 4 CARD32 n 4525 4526 if (n=1) this follows: 4527 4528 4 INT32 params 4529 12 unused 4530 4531 otherwise this follows: 4532 4533 16 unused 4534 n*4 LISTofINT32 params 4535 4536 GetProgramStringARB 4537 1 CARD8 opcode (X assigned) 4538 1 17 GLX opcode (glXVendorPrivateWithReply) 4539 2 5 request length 4540 4 1308 vendor specific opcode 4541 4 GLX_CONTEXT_TAG context tag 4542 4 ENUM target 4543 4 ENUM pname 4544 => 4545 1 1 reply 4546 1 unused 4547 2 CARD16 sequence number 4548 4 (n+p)/4 reply length 4549 4 unused 4550 4 CARD32 n 4551 16 unused 4552 n STRING program 4553 p unused, p=pad(n) 4554 4555 IsProgramARB 4556 1 CARD8 opcode (X assigned) 4557 1 17 GLX opcode (glXVendorPrivateWithReply) 4558 2 4 request length 4559 4 1304 vendor specific opcode 4560 4 GLX_CONTEXT_TAG context tag 4561 4 INT32 n 4562 => 4563 1 1 reply 4564 1 unused 4565 2 CARD16 sequence number 4566 4 0 reply length 4567 4 BOOL32 return value 4568 20 unused 4569 4570 4571Errors 4572 4573 The error INVALID_OPERATION is generated by ProgramStringARB if the 4574 program string <string> is syntactically incorrect or violates any 4575 semantic restriction of the execution environment of the specified 4576 program target <target>. The error INVALID_OPERATION may also be 4577 generated by ProgramStringARB if the specified program would exceed 4578 native resource limits of the implementation. 4579 4580 The error INVALID_OPERATION is generated by BindProgramARB if 4581 <program> is the name of a program whose target does not match 4582 <target>. 4583 4584 The error INVALID_VALUE is generated by commands 4585 ProgramEnvParameter{fd}ARB, ProgramEnvParameter{fd}vARB, and 4586 GetProgramEnvParameter{fd}vARB if <index> is greater than or equal 4587 to the value of MAX_PROGRAM_ENV_PARAMETERS_ARB corresponding to the 4588 program target <target>. 4589 4590 The error INVALID_VALUE is generated by commands 4591 ProgramLocalParameter4{fd}ARB, ProgramLocalParameter4{fd}vARB, and 4592 GetProgramLocalParameter{fd}vARB if <index> is greater than or equal 4593 to the value of MAX_PROGRAM_LOCAL_PARAMETERS_ARB corresponding to 4594 the program target <target>. 4595 4596 The error INVALID_OPERATION is generated if Begin, RasterPos, or any 4597 command that performs an explicit Begin is called when fragment 4598 program mode is enabled and the currently bound fragment program 4599 object does not contain a valid fragment program. 4600 4601 The error INVALID_OPERATION is generated by any command accessing 4602 texture coordinate processing state if the texture unit number 4603 corresponding to the current value of ACTIVE_TEXTURE is greater than 4604 or equal to the implementation-dependent constant 4605 MAX_TEXTURE_COORDS_ARB. Such commands include: GetTexGen{if}v; 4606 TexGen{ifd}, TexGen{ifd}v; Disable, Enable, IsEnabled with argument 4607 TEXTURE_GEN_{STRQ}; Get with argument CURRENT_TEXTURE_COORDS, 4608 CURRENT_RASTER_TEXTURE_COORDS, TEXTURE_STACK_DEPTH, TEXTURE_MATRIX, 4609 TRANSPOSE_TEXTURE_MATRIX; when the current matrix mode is TEXTURE, 4610 Frustum, LoadIdentity, LoadMatrix{fd}, LoadTransposeMatrix{fd}, 4611 MultMatrix{fd}, MultTransposeMatrix{fd}, Ortho, PopMatrix, 4612 PushMatrix, Rotate{fd}, Scale{fd}, Translate{fd}. 4613 4614 The error INVALID_OPERATION is generated by any command accessing 4615 texture image processing state if the texture unit number 4616 corresponding to the current value of ACTIVE_TEXTURE is greater than 4617 or equal to the implementation-dependent constant 4618 MAX_TEXTURE_IMAGE_UNITS_ARB. Such commands include: BindTexture; 4619 GetCompressedTexImage, GetTexEnv{if}v, GetTexImage, 4620 GetTexLevelParameter{if}v, GetTexParameter{if}v; TexEnv{if}, 4621 TexEnv{if}v, TexParameter{if}, TexParameter{if}v; Disable, Enable, 4622 IsEnabled with argument TEXTURE_{123}D, TEXTURE_CUBE_MAP; Get with 4623 argument TEXTURE_BINDING_{123}D, TEXTURE_BINDING_CUBE_MAP; 4624 CompressedTexImage{123}D, CompressedTexSubImage{123}D, 4625 CopyTexImage{12}D, CopyTexSubImage{123}D, TexImage{123}D, 4626 TexSubImage{123}D. 4627 4628 4629New State 4630 4631 4632 Get Value Type Get Command Initial Value Description Section Attribute 4633 ------------------------------- ------ ------------- ------------- ------------------ ------------ ------------ 4634 FRAGMENT_PROGRAM_ARB B IsEnabled False fragment program 3.8 enable 4635 enable 4636 - 24+xR4 GetProgramEnv- (0,0,0,0) program environment 3.11.1 - 4637 ParameterARB parameters 4638 PROGRAM_ERROR_POSITION_ARB Z GetIntegerv -1 last program error 3.11.1 - 4639 position 4640 PROGRAM_ERROR_STRING_ARB 0+xub GetString "" last program error 3.11.1 - 4641 string 4642 4643 Table X.6. New Accessible State Introduced by ARB_fragment_program. 4644 4645 4646 Get Value Type Get Command Initial Value Description Sec Attrib 4647 -------------------- ----- ------------------- --------------- ---------------------- -------- ------ 4648 PROGRAM_BINDING_ARB Z+ GetProgramivARB object-specific bound program name 6.1.12 - 4649 PROGRAM_LENGTH_ARB Z+ GetProgramivARB 0 bound program length 6.1.12 - 4650 PROGRAM_FORMAT_ARB Z1 GetProgramivARB PROGRAM_FORMAT_ bound program format 6.1.12 - 4651 ASCII_ARB 4652 PROGRAM_STRING_ARB ubxn GetProgramStringARB (empty) bound program string 6.1.12 - 4653 PROGRAM_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4654 total instructions 4655 PROGRAM_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4656 ALU instructions 4657 PROGRAM_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4658 texture instructions 4659 PROGRAM_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4660 texture indirections 4661 PROGRAM_TEMPORARIES_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4662 temporaries 4663 PROGRAM_PARAMETERS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4664 parameter bindings 4665 PROGRAM_ATTRIBS_ARB Z+ GetProgramivARB 0 bound program 6.1.12 - 4666 attribute bindings 4667 PROGRAM_NATIVE_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4668 instructions 4669 PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4670 ALU instructions 4671 PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4672 texture instructions 4673 PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4674 texture indirections 4675 PROGRAM_NATIVE_TEMPORARIES_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4676 temporaries 4677 PROGRAM_NATIVE_PARAMETERS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4678 parameter bindings 4679 PROGRAM_NATIVE_ATTRIBS_ARB Z+ GetProgramivARB 0 bound program native 6.1.12 - 4680 attribute bindings 4681 PROGRAM_UNDER_NATIVE_LIMITS_ARB B GetProgramivARB 0 bound program under 6.1.12 - 4682 native resource limits 4683 - 24+xR4 GetProgramLocal- (0,0,0,0) bound program local 3.11.1 - 4684 ParameterARB parameter value 4685 4686 Table X.7. Program Object State. Program object queries return attributes of 4687 the program object currently bound to the program target <target>. 4688 4689 4690 Get Value Type Get Command Initial Value Description Sec Attribute 4691 --------- ------ ----------- ------------- ------------------------- -------- --------- 4692 - 16+xR4 - undefined temporary registers 3.11.3.3 - 4693 - 2xR4 - undefined fragment result registers 3.11.3.4 - 4694 4695 Table X.8. Fragment Program Per-fragment Execution State. All per-fragment 4696 execution state registers are uninitialized at the beginning of program 4697 execution. 4698 4699 4700 Get Value Type Get Command Initial Value Description Sec Attribute 4701 ------------------------------ -------- -------------- ------------- ------------------- ------- --------- 4702 CURRENT_MATRIX_ARB m*n*xM^4 GetFloatv Identity current matrix 6.1.2 - 4703 CURRENT_MATRIX_STACK_DEPTH_ARB m*Z+ GetIntegerv 1 current stack depth 6.1.2 - 4704 4705 Table X.9. Current matrix state where m is the total number of matrices 4706 including texture matrices and program matrices and n is the number of 4707 matrices on each particular matrix stack. Note that this state is aliased 4708 with existing matrix state. 4709 4710 4711New Implementation Dependent State 4712 Minimum 4713 Get Value Type Get Command Value Description Sec. Attrib 4714 --------- ---- ----------- ------- ----------- ---- ------ 4715 MAX_TEXTURE_COORDS_ARB Z+ GetIntegerv 2 number of texture 2.7 - 4716 coordinate sets 4717 MAX_TEXTURE_IMAGE_UNITS_ARB Z+ GetIntegerv 2 number of texture 2.10.2 - 4718 image units 4719 MAX_PROGRAM_ENV_PARAMETERS_ARB Z+ GetProgramivARB 24 maximum program 3.11.1 - 4720 env parameters 4721 MAX_PROGRAM_LOCAL_PARAMETERS_ARB Z+ GetProgramivARB 24 maximum program 3.11.1 - 4722 local parameters 4723 MAX_PROGRAM_MATRICES_ARB Z+ GetIntegerv 8 (not to maximum number of 3.11.7 - 4724 exceed 32) program matrices 4725 MAX_PROGRAM_MATRIX_STACK_DEPTH_ARB Z+ GetIntegerv 1 maximum program 3.11.7 - 4726 matrix stack depth 4727 MAX_PROGRAM_INSTRUCTIONS_ARB Z+ GetProgramivARB 72 maximum program 6.1.12 - 4728 total instructions 4729 MAX_PROGRAM_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB 48 number of frag. prg. 6.1.12 - 4730 ALU instructions 4731 MAX_PROGRAM_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB 24 number of frag. prg. 6.1.12 - 4732 texture instructions 4733 MAX_PROGRAM_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB 4 number of frag. prg. 6.1.12 - 4734 texture indirections 4735 MAX_PROGRAM_TEMPORARIES_ARB Z+ GetProgramivARB 16 maximum program 6.1.12 - 4736 temporaries 4737 MAX_PROGRAM_PARAMETERS_ARB Z+ GetProgramivARB 24 maximum program 6.1.12 - 4738 parameter bindings 4739 MAX_PROGRAM_ATTRIBS_ARB Z+ GetProgramivARB 10 maximum program 6.1.12 - 4740 attribute bindings 4741 MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4742 total instructions 4743 MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4744 ALU instructions 4745 MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4746 texture instructions 4747 MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4748 texture indirections 4749 MAX_PROGRAM_NATIVE_TEMPORARIES_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4750 temporaries 4751 MAX_PROGRAM_NATIVE_PARAMETERS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4752 parameter bindings 4753 MAX_PROGRAM_NATIVE_ATTRIBS_ARB Z+ GetProgramivARB - maximum program native 6.1.12 - 4754 attribute bindings 4755 4756 Table X.10. New Implementation-Dependent Values Introduced by 4757 ARB_fragment_program. Values queried by GetProgram require a <pname> of 4758 FRAGMENT_PROGRAM_ARB. 4759 4760 4761Sample Usage 4762 4763 The following program shows how to perform a simple modulation 4764 between the interpolated color and a single texture: 4765 4766 !!ARBfp1.0 4767 # Simple program to show how to code up the default texture environment 4768 4769 ATTRIB tex = fragment.texcoord; #first set of texture coordinates 4770 ATTRIB col = fragment.color.primary; #diffuse interpolated color 4771 4772 OUTPUT outColor = result.color; 4773 4774 TEMP tmp; 4775 4776 TXP tmp, tex, texture, 2D; #sample the texture 4777 4778 MUL outColor, tmp, col; #perform the modulation 4779 4780 END 4781 4782 The following is an example the simulates a chrome surface: 4783 4784 !!ARBfp1.0 4785 4786 ######################## 4787 # Input Textures: 4788 #----------------------- 4789 # Texture 0 contains the default 2D texture used for general mapping 4790 # Texture 2 contains a 1D pointlight falloff map 4791 # Texture 3 contains a 2D map for calculating specular lighting 4792 # Texture 4 contains normalizer cube map 4793 # 4794 # Input Texture Coordinates: 4795 #----------------------- 4796 # TexCoord1 contains the calculated normal 4797 # TexCoord2 contains the light to vertex vector 4798 # TexCoord3 contains the half-vector in tangent space 4799 # TexCoord4 contains the light vector in tangent space 4800 # TexCoord5 contains the eye vector in tangent space 4801 ######################## 4802 4803 TEMP NdotH, lV, L; 4804 4805 ALIAS diffuse = L; 4806 PARAM half = { 0.5, 0.5, 0.5, 0.5 }; 4807 ATTRIB norm_tc = fragment.texcoord[1]; 4808 ATTRIB lv_tc = fragment.texcoord[2]; 4809 ATTRIB half_tc = fragment.texcoord[3]; 4810 ATTRIB light_tc = fragment.texcoord[4]; 4811 ATTRIB eye_tc = fragment.texcoord[5]; 4812 OUTPUT oCol = result.color; 4813 4814 TEX L, light_tc, texture[4], CUBE; # Sample cube map normalizer 4815 4816 # Calculate diffuse lighting (N.L) 4817 SUB L, L, half; # Bias L and then multiply by 2 4818 ADD L, L, L; 4819 DP3 diffuse, norm_tc, L; # N.L 4820 4821 # Calculate specular lighting component { (N.H), |H|^2 } 4822 DP3 NdotH.x, norm_tc, half_tc; 4823 DP3 NdotH.y, half_tc, half_tc; 4824 4825 DP3 lV.x, lv_tc, lv_tc; # lV = (|light to vertex|)^2 4826 4827 4828 ############# 4829 # Pass 2 4830 ############# 4831 4832 TEMP base, specular; 4833 ALIAS atten = lV; 4834 4835 TEX base, eye_tc, texture[0], 2D; # sample enviroment map using eye vector 4836 TEX atten, lV, texture[2], 1D; # Sample attenuation map 4837 TEX specular, NdotH, texture[3], 2D; # Sample specular NHHH map= (N.H)^256 4838 4839 # specular = (N.H)^256 * (N.L) 4840 # this ensures a pixel is only lit if facing the light (since the specular 4841 # exponent makes negative N.H positive we must do this) 4842 MUL specular, specular, diffuse; 4843 4844 # specular = specular * environment map 4845 MUL specular, base, specular; 4846 4847 # diffuse = diffuse * environment map 4848 MUL diffuse, base, diffuse; 4849 4850 # outColor = (specular * environment map) + (diffuse * environment map) 4851 ADD base, specular, diffuse; 4852 4853 # Apply point light attenutaion 4854 MUL oCol, base, atten.r; 4855 4856 END 4857 4858 4859Revision History 4860 4861 Date: 10/08/2013 4862 Revision: 28 4863 - Change GLvoid -> void (Bug 10412). 4864 4865 Date: 11/04/2006 4866 Revision: 27 4867 - Updated contact info after ATI/AMD merger. 4868 4869 Date: 8/22/2003 4870 Revision: 26 4871 - Added list of commands generating errors when active texture 4872 unit selector is out of range. 4873 - Fixed typo in <stateMatrixItem> rule. 4874 - Clarified behavior of fragment.position.z with respect to depth 4875 offset. 4876 4877 Date: 2/26/2003 4878 Revision: 25 4879 - Fixed description of KIL instruction to reflect less than zero 4880 test, not less than or equal to zero. 4881 - Clarified the processing of incoming and outgoing depths and 4882 colors to reflect the conversion to floating-point on input and 4883 the conversion to fixed-point on output. 4884 4885 Date: 1/10/2003 4886 Revision: 24 4887 - Fixed bug where "state.matrix.mvp" was specified incorrectly. 4888 It should be P*M0 rather than M0*P. 4889 - Added issue warning about CMP opcode's order of operands. 4890 4891 Date: 10/22/2002 4892 Revision: 23 4893 - Fixed reference to <extSwizComp> rule in 3.11.5.28. Instead 4894 reference both <xyzwExtSwizComp> and <rgbaExtSwizComp> rules. 4895 4896 Date: 10/02/2002 4897 Revision: 22 4898 - Fixed typo in section 3.11.1, where 8 program environment and 4899 8 program local parameters are listed as the minimums instead 4900 of 24 of each. Table X.10 had the correct values. 4901 - Fixed <stateTexEnvItem> to refer to legacy texture units. 4902 - Fixed typos in issue 29 pseudo-code, added some clarification. 4903 4904 Date: 9/19/2002 4905 Revision: 21 4906 - Added clarifying paragraph for native texture indirection 4907 counting, offering examples of possible cases where texture 4908 indirections may be increased. 4909 - Fixed typos in issues 25 and 29. 4910 4911 Date: 9/16/2002 4912 Revision: 20 4913 - Added precision hint program options. 4914 - Fixed various typos, reworded some parts for consistency. 4915 - Updated issues list. 4916 4917 Date: 9/13/2002 4918 Revision: 19 4919 - Promoted minimum precision of texture coordinates in 2.1.1. 4920 - Added ARB_fog_* program options. 4921 - Removed modification to 3.9, put clamps in 3.11.4.4. 4922 - Made 'texture' a reserved keyword in the grammar. 4923 - Fixed various typos. 4924 - Updated section 3.11.6. 4925 - Updated issues list. 4926 4927 Date: 9/11/2002 4928 Revision: 18 4929 - Updated for consistency with ARB_vertex_program revision 36. 4930 - Depth output moved to 3rd component of result.depth. 4931 - Fixed various typos, reworded things in many places. 4932 - Added NV_fragment_program interactions. 4933 - Updated issues list. 4934 4935 Date: 9/09/2002 4936 Revision: 17 4937 - Added fogcoord and position attributes. 4938 - Moved fragment program section to 3.11, after fog. 4939 - Changed MAX_TEXTURE_UNITS/MAX_AUX_TEXTURE_UNITS to 4940 MAX_TEXTURE_COORDS/MAX_TEXTURE_IMAGE_UNITS. 4941 - Removed TRC and MOD instructions. 4942 - Added SIN and COS instructions. 4943 - Added more clarity to resource consumption wording. 4944 - Added invariance wording concerning depth-replacement. 4945 - Added rule that a program that fails to load must always fail to 4946 load, regardless of GL state. 4947 - Updated issues list. 4948 4949 Date: 8/30/2002 4950 Revision: 16 4951 - Improved texture indirection description. 4952 - Defined result of sample from incomplete texture as (0,0,0,1). 4953 - Removed PROGRAMS_LOAD_OVER_NATIVE_LIMITS_ARB per-target query. 4954 - Allowed ProgramStringARB to fail on non-native programs. 4955 - Updated issues list. 4956 4957 Date: 8/28/2002 4958 Revision: 15 4959 - Updated for consistency with ARB_vertex_program revision 35. 4960 - Added PROGRAMS_LOAD_OVER_NATIVE_LIMITS_ARB per-target query. 4961 - Changed MAX_AUX_TEXTURE_UNITS_ARB enum value. 4962 - Updated issues list. 4963 4964 Date: 8/22/2002 4965 Revision: 14 4966 - Added sine/cosine instruction (SCS). 4967 - Updated texture sample grammar, replaced texenables hierarchy. 4968 - Added EXT_vertex_weighting and ARB_vertex_blend dependency. 4969 - Updated issues list. 4970 4971 Date: 8/14/2002 4972 Revision: 13 4973 - Fixed <paramConstant> grammar rule. 4974 - Updated issues list. 4975 4976 Date: 8/06/2002 4977 Revision: 12 4978 - Fixed various typos. 4979 - Updated issues list. 4980 - Added wording to 3.10.3.6 to reflect that native resource 4981 consumption may increase due to emulated instructions. 4982 4983 Date: 7/29/2002 4984 Revision: 11 4985 - Updated for consistency with ARB_vertex_program revision 34. 4986 - Added support for matrix binding. 4987 - Removed precision queries. 4988 - Updated issues list. 4989 4990 Date: 7/16/2002 4991 Revision: 10 4992 - Updated for consistency with ARB_vertex_program revision 31. 4993 - Added fog params and depth range bindings to grammar. 4994 - Removed stpq writemasks and swizzles from grammar. 4995 - Required swizzle components to come from same set, xyzw or rgba. 4996 4997 Date: 7/10/2002 4998 Revision: 9 4999 - Made fog params and depth range bindable. 5000 - Changed texture instruction names to match 3-letter format. 5001 - Made texture instructions more consistent with ALU instructions. 5002 - Increased minimums for implementation-dependent values. 5003 - Re-introduced 4-components swizzles and the SWZ instruction. 5004 - Updated issues list. 5005 5006 Date: 7/03/2002 5007 Revision: 8 5008 - Fixed typos. 5009 - Added DST, LIT, SGE, SLT instructions. 5010 - Changed FRC definition to match ARB_vertex_program, added MOD 5011 instruction to expose fmod(arg, 1.0) behavior. 5012 5013 Date: 6/25/2002 5014 Revision: 7 5015 - Updated for consistency with ARB_vertex_program revision 29. 5016 5017 Date: 6/19/2002 5018 Revision: 6 5019 - Updated for consistency with ARB_vertex_program revision 28. 5020 - Changed from ATI to ARB prefix/suffix. 5021 - Started using single integer revision number. 5022 - Added a few more issues to the list. 5023 5024 Date: 6/14/2002 5025 Revision: 1.4 5026 - Updated for consistency with ARB_vertex_program revision 27. 5027 - Added a few more issues to the list. 5028 5029 Date: 6/05/2002 5030 Revision: 1.3 5031 - Updated for consistency with ARB_vertex_program revision 26. 5032 - Incorporated program object management, removing dependency on 5033 ARB_vertex_program. 5034 - Added interaction with ARB_shadow. 5035 5036 Date: 6/03/2002 5037 Revision: 1.2 5038 - Updated for consistency with ARB_vertex_program revision 25. 5039 - Fixed TexInstructions to use <texSrcReg>, i.e. no parameters. 5040 - Added TRC, POW, DPH instructions, updated FRC and LRP. 5041 - Added fog color parameter binding. 5042 5043 Date: 5/23/2002 5044 Revision: 1.1 5045 - Updated for consistency with ARB_vertex_program revision 24. 5046 - Added GetProgramfvATI entrypoint for querying precision values. 5047 5048 Date: 5/10/2002 5049 Revision: 1.0 5050 - First draft for circulation. 5051