1Name 2 3 ATI_fragment_shader 4 5Name Strings 6 7 GL_ATI_fragment_shader 8 9Contributors 10 11 Dan Ginsburg 12 Evan Hart 13 Jason Mitchell 14 15Contact 16 17 Benj Lipchak, AMD (benj.lipchak 'at' amd.com) 18 19Status 20 21 Shipping (version 1.0) 22 23Version 24 25 Last Modified Date: November 4, 2006 26 Author Revision: 1.8 27 28Number 29 30 245 31 32Dependencies 33 34 ARB_multitexture is required by this extension. 35 ARB_shadow interacts with this extension. 36 The extension is written against the OpenGL 1.2.1 Specification. 37 38Overview 39 40 This extension exposes a powerful fragment shading model which 41 provides a very general means of expressing fragment color blending 42 and dependent texture address modification. The programming is 43 a register-based model in which there is a fixed number of 44 instructions, texture lookups, read/write registers, and constants. 45 46 The fragment shader extension provides a unified instruction set 47 for operating on address or color data and eliminates the 48 distinction between the two. This extension provides all the 49 interfaces necessary to fully expose this programmable fragment 50 shader in GL. 51 52 Although conceived as a device-independent extension which would 53 expose the capabilities of future generations of hardware, changing 54 trends in programmable hardware have affected the lifespan of this 55 extension. For this reason you will now find a fixed set of 56 features and resources exposed, and the queries to determine this 57 set have been deprecated. 58 59Issues 60 61 None 62 63 64New Procedures and Functions 65 66 uint GenFragmentShadersATI (uint range); 67 68 void BindFragmentShaderATI (uint id); 69 70 void DeleteFragmentShaderATI (uint id); 71 72 void BeginFragmentShaderATI (void); 73 74 void EndFragmentShaderATI (void); 75 76 void PassTexCoordATI (uint dst, uint coord, enum swizzle); 77 78 void SampleMapATI (uint dst, uint interp, enum swizzle); 79 80 void ColorFragmentOp1ATI (enum op, uint dst, uint dstMask, 81 uint dstMod, uint arg1, uint arg1Rep, 82 uint arg1Mod); 83 84 void ColorFragmentOp2ATI (enum op, uint dst, uint dstMask, 85 uint dstMod, uint arg1, uint arg1Rep, 86 uint arg1Mod, uint arg2, uint arg2Rep, 87 uint arg2Mod); 88 89 void ColorFragmentOp3ATI (enum op, uint dst, uint dstMask, 90 uint dstMod, uint arg1, uint arg1Rep, 91 uint arg1Mod, uint arg2, uint arg2Rep, 92 uint arg2Mod, uint arg3, uint arg3Rep, 93 uint arg3Mod); 94 95 void AlphaFragmentOp1ATI (enum op, uint dst, uint dstMod, 96 uint arg1, uint arg1Rep, uint arg1Mod); 97 98 void AlphaFragmentOp2ATI (enum op, uint dst, uint dstMod, 99 uint arg1, uint arg1Rep, uint arg1Mod, 100 uint arg2, uint arg2Rep, uint arg2Mod); 101 102 void AlphaFragmentOp3ATI (enum op, uint dst, uint dstMod, 103 uint arg1, uint arg1Rep, uint arg1Mod, 104 uint arg2, uint arg2Rep, uint arg2Mod, 105 uint arg3, uint arg3Rep, uint arg3Mod); 106 107 void SetFragmentShaderConstantATI (uint dst, const float *value); 108 109 110New Tokens 111 112 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, 113 and by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 114 and GetDoublev: 115 116 FRAGMENT_SHADER_ATI 0x8920 117 118 Accepted by the <dst> and <argN> parameters of 119 ColorFragmentOp[1..3]ATI and AlphaFragmentOp[1..3]ATI, and by the 120 <dst> and <coord> parameters of PassTexCoordATI, and by the <dst> 121 and <interp> parameters of SampleMapATI: 122 123 REG_0_ATI 0x8921 124 REG_1_ATI 0x8922 125 REG_2_ATI 0x8923 126 REG_3_ATI 0x8924 127 REG_4_ATI 0x8925 128 REG_5_ATI 0x8926 129 130 Accepted by the <dst> parameter of SetFragmentShaderConstantATI and 131 the <argN> parameter of ColorFragmentOp[1..3]ATI and 132 AlphaFragmentOp[1..3]ATI: 133 134 CON_0_ATI 0x8941 135 CON_1_ATI 0x8942 136 CON_2_ATI 0x8943 137 CON_3_ATI 0x8944 138 CON_4_ATI 0x8945 139 CON_5_ATI 0x8946 140 CON_6_ATI 0x8947 141 CON_7_ATI 0x8948 142 143 Accepted by the <op> parameter of ColorFragmentOp1ATI and 144 AlphaFragmentOp1ATI: 145 146 MOV_ATI 0x8961 147 148 Accepted by the <op> parameter of ColorFragmentOp2ATI and 149 AlphaFragmentOp2ATI: 150 151 ADD_ATI 0x8963 152 MUL_ATI 0x8964 153 SUB_ATI 0x8965 154 DOT3_ATI 0x8966 155 DOT4_ATI 0x8967 156 157 Accepted by the <op> parameter of ColorFragmentOp3ATI and 158 AlphaFragmentOp3ATI: 159 160 MAD_ATI 0x8968 161 LERP_ATI 0x8969 162 CND_ATI 0x896A 163 CND0_ATI 0x896B 164 DOT2_ADD_ATI 0x896C 165 166 Accepted by the <argN> parameter of ColorFragmentOp[1..3]ATI and 167 AlphaFragmentOp[1..3]ATI: 168 169 ZERO 170 ONE 171 PRIMARY_COLOR_ARB 172 SECONDARY_INTERPOLATOR_ATI 0x896D 173 174 Accepted by the <interp> parameter of SampleMapATI and the <coord> 175 parameter of PassTexCoordATI: 176 177 TEXTURE0_ARB 178 TEXTURE1_ARB 179 TEXTURE2_ARB 180 TEXTURE3_ARB 181 TEXTURE4_ARB 182 TEXTURE5_ARB 183 TEXTURE6_ARB 184 TEXTURE7_ARB 185 186 Accepted by the <swizzle> parameter of SampleMapATI and 187 PassTexCoordATI: 188 189 SWIZZLE_STR_ATI 0x8976 190 SWIZZLE_STQ_ATI 0x8977 191 SWIZZLE_STR_DR_ATI 0x8978 192 SWIZZLE_STQ_DQ_ATI 0x8979 193 194 Accepted by the <dstMask> parameter of ColorFragmentOp[1..3]ATI: 195 196 NONE 197 RED_BIT_ATI 0x00000001 198 GREEN_BIT_ATI 0x00000002 199 BLUE_BIT_ATI 0x00000004 200 201 Accepted by the <argNRep> parameter of ColorFragmentOp[1..3]ATI and 202 AlphaFragmentOp[1..3]ATI: 203 204 NONE 205 RED 206 GREEN 207 BLUE 208 ALPHA 209 210 Accepted by the <dstMod> parameter of ColorFragmentOp[1..3]ATI and 211 AlphaFragmentOp[1..3]ATI: 212 213 NONE 214 2X_BIT_ATI 0x00000001 215 4X_BIT_ATI 0x00000002 216 8X_BIT_ATI 0x00000004 217 HALF_BIT_ATI 0x00000008 218 QUARTER_BIT_ATI 0x00000010 219 EIGHTH_BIT_ATI 0x00000020 220 SATURATE_BIT_ATI 0x00000040 221 222 223 Accepted by the <argNMod> parameter of ColorFragmentOp[1..3]ATI and 224 AlphaFragmentOp[1..3]ATI: 225 226 2X_BIT_ATI 0x00000001 227 COMP_BIT_ATI 0x00000002 228 NEGATE_BIT_ATI 0x00000004 229 BIAS_BIT_ATI 0x00000008 230 231 232Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL 233Operation) 234 235 None 236 237 238Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 239 240 Add New Subsection after 3.8.10, (p. 138) 241 242 3.8.11 Fragment Shaders 243 244 By default, the current texture environment is used to determine 245 how textures are combined for rasterization. However, by enabling 246 FRAGMENT_SHADER_ATI, the currently bound fragment shader is used to 247 determine how textures are combined. The fragment shader replaces 248 the traditional texture environment by exposing a fragment shading 249 model which provides a very general means of expressing fragment 250 color blending and dependent texture address modification. The 251 distinction between texture address and color data becomes 252 irrelevant in the fragment shader as the two can be used 253 interchangeably. 254 255 A shader is defined between a BeginFragmentShaderATI and 256 EndFragmentShaderATI block. These commands are defined as follows: 257 258 void BeginFragmentShaderATI(void); 259 void EndFragmentShaderATI(void); 260 261 Although there is no restriction as to which GL operations may be 262 specified between BeginFragmentShaderATI and EndFragmentShaderATI, 263 only the following operations will be compiled into a shader: 264 PassTexCoordATI, SampleMapATI, ColorFragmentOp[1..3]ATI, 265 AlphaFragmentOp[1..3]ATI, and SetFragmentShaderContantATI. 266 267 In addition to a default fragment shader, named shaders can be 268 created. The namespace for shaders is unsigned integers with zero 269 reserved by the GL. A shader is created by binding an unused name 270 using: 271 272 void BindFragmentShaderATI(uint id); 273 274 where <id> is the unused name. Once a shader has been created it 275 can be rebound as the active shader by calling 276 BindFragmentShaderATI. A shader can be deleted, freeing the name, 277 by calling: 278 279 void DeleteFragmentShaderATI(uint id); 280 281 where <id> is the name to be deleted. Unique names can be generated 282 using: 283 284 uint GenFragmentShadersATI(uint range); 285 286 where <range> is the number of contiguous ids that should be 287 created. It returns an integer n such that <range> contiguous empty 288 shader ids, with values n, n+1, ..., n+<range>-1, are created. If 289 <range> is 0, if there is no group of <range> contiguous names 290 available, or if any error is generated, no shaders are generated, 291 and 0 is returned. 292 293 If FRAGMENT_SHADER_ATI is enabled, but the currently bound shader is 294 invalid, the results of drawing commands are undefined. A shader 295 may be invalid because it is currently being specified (i.e., a 296 drawing command within a Begin/EndFragmentShader pair), or due to 297 some error during the specification of a shader. 298 299 There are three types of data that can be in a fragment shader: 300 registers, constants, and interpolators. The 6 REG_x_ATI registers 301 can be used as source or destination in any color or alpha 302 instruction. The final result of the shader is whatever value is in 303 REG_0_ATI. This value will be the final color of the output 304 fragment passed. 305 306 There are 8 constant registers available, CON_0_ATI through 307 CON_7_ATI. CON_x_ATI constants can be used as source in any color 308 or alpha instruction, but at most 2 different constants may be used 309 as source arguments in each instruction. 310 311 Additionally, the primary and secondary color interpolators are 312 available as source in any color or alpha instruction, but only in 313 the last pass of the shader (i.e., the only pass of a one-pass 314 shader or the second pass of a two-pass shader). 315 316 Either one or two passes may be specified in a shader. Each pass 317 may use up to 8 pairs of instructions for a total of at most 16 318 pairs in the shader. A pair consists of one color instruction and 319 one alpha instruction. 320 321 The first instructions specified in each pass of a shader are "free" 322 instructions in that they don't count against the 8 instructions 323 available in each pass. They are routing instructions which specify 324 from where the contents of the registers come. The first occurance 325 of one of these free instructions marks the beginning of a pass in 326 the shader. They are specified with SampleMapATI and 327 PassTexCoordATI. 328 329 The entry point: 330 331 void PassTexCoordATI (uint dst, uint coord, enum swizzle); 332 333 specifies that the value present in <coord> is passed directly into 334 the contents of <dst> (one of the registers REG_x_ATI). This value 335 is then available for use as a source argument to subsequent color 336 and alpha instructions following in the same pass. <coord> may 337 either be the texture coordinates on a texture unit (TEXTUREx_ARB), 338 or in the case of a two-pass shader's second pass, it may be the 339 value of a register set in the first pass (REG_x_ATI). 340 341 Note that in order to preserve the contents of a register from the 342 first pass to the second, there must be a PassTexCoordATI 343 instruction in the setup for the second pass that assigns that 344 register to itself. For example: 345 346 PassTexCoordATI(REG_1_ATI, REG_1_ATI, SWIZZLE_STR_ATI); 347 348 will preserve the first 3 components of REG_1_ATI for use in the 349 second pass. 350 351 The entry point: 352 353 void SampleMapATI (uint dst, uint interp, enum swizzle); 354 355 specifies that the value present in the texture data bound on the 356 unit associated with <dst> will be written to that register. A 357 value for <dst> of REG_x_ATI means that TEXTUREx_ARB will be 358 sampled, and the result written to REG_x_ATI. The <interp> 359 parameter specifies which texture coordinate interpolator is used to 360 sample the map. A value of REG_x_ATI for <interp> in the second 361 pass of a two-pass shader will do dependent texture read sampling 362 using the value in register x. Otherwise, specifying TEXTUREx_ARB 363 will sample the map using the texture coordinates on unit x. 364 365 Only the first 3 components of <coord> or <interp> are used in 366 PassTexCoordATI and SampleMapATI, respectively. The swizzle 367 parameter is used to select which of the 4 original components of 368 the source register or texture coordinates will be mapped to the 3 369 available positions, and whether or not a projection will occur. 370 371 Table 3.20 shows the <swizzle> modes: 372 373 374 Coordinates Used for 1D or Coordinates Used for 375 Swizzle 2D SampleMap and PassTexCoord 3D or cubemap SampleMap 376 ------- ----------------------------- ----------------------- 377 SWIZZLE_STR_ATI (s, t, r, undefined) (s, t, r, undefined) 378 SWIZZLE_STQ_ATI (s, t, q, undefined) (s, t, q, undefined) 379 SWIZZLE_STR_DR_ATI (s/r, t/r, 1/r, undefined) (undefined) 380 SWIZZLE_STQ_DQ_ATI (s/q, t/q, 1/q, undefined) (undefined) 381 382 Table 3.20 Coordinate swizzles 383 384 385 Each texture coordinate source (TEXTUREx_ARB) used as a <coord> 386 and/or <interp> can only draw upon STR or STQ components throughout 387 the shader. For example, if TEXTURE2_ARB is used in a SampleMapATI 388 with <swizzle> SWIZZLE_STR_ATI, it cannot be used again later with a 389 <swizzle> of SWIZZLE_STQ_ATI. The projection, however, may vary. 390 It would be okay to later use TEXTURE2_ARB with a <swizzle> of 391 SWIZZLE_STR_DR_ATI. 392 393 Additionally, when the <coord> or <interp> is a register (in the 394 second pass of a two-pass shader), only SWIZZLE_STR_ATI and 395 SWIZZLE_STR_DR_ATI are allowed. Note that if this is a 396 PassTexCoord, the fourth component (alpha channel if the register 397 contains RGBA) is not passed along and the fourth component of <dst> 398 becomes undefined. 399 400 The color and alpha instructions performed in the shader are 401 specified with the following entry points: 402 403 void ColorFragmentOp1ATI (enum op, uint dst, uint dstMask, uint dstMod, 404 uint arg1, uint arg1Rep, uint arg1Mod); 405 void ColorFragmentOp2ATI (enum op, uint dst, uint dstMask, uint dstMod, 406 uint arg1, uint arg1Rep, uint arg1Mod, 407 uint arg2, uint arg2Rep, uint arg2Mod); 408 void ColorFragmentOp3ATI (enum op, uint dst, uint dstMask, uint dstMod, 409 uint arg1, uint arg1Rep, uint arg1Mod, 410 uint arg2, uint arg2Rep, uint arg2Mod, 411 uint arg3, uint arg3Rep, uint arg3Mod); 412 void AlphaFragmentOp1ATI (enum op, uint dst, uint dstMod, 413 uint arg1, uint arg1Rep, uint arg1Mod); 414 void AlphaFragmentOp2ATI (enum op, uint dst, uint dstMod, 415 uint arg1, uint arg1Rep, uint arg1Mod, 416 uint arg2, uint arg2Rep, uint arg2Mod); 417 void AlphaFragmentOp3ATI (enum op, uint dst, uint dstMod, 418 uint arg1, uint arg1Rep, uint arg1Mod, 419 uint arg2, uint arg2Rep, uint arg2Mod, 420 uint arg3, uint arg3Rep, uint arg3Mod); 421 422 A ColorFragmentOp[1..3]ATI followed by an AlphaFragmentOp[1..3]ATI 423 is considered to be an instruction pair, and 8 such pairs may be 424 specified per pass. The color and alpha instructions of a pair are 425 executed in parallel: the result of the color instruction cannot 426 affect the source arguments of the alpha instruction. Both a color 427 and an alpha instruction need not be specified for every pair; the 428 necessary color or alpha no-op is automatically inserted by the GL 429 to complete each instruction pair. 430 431 The <op> parameter specifies the instruction to perform on the 432 sources. 433 434 Table 3.21 shows the effect of each <op>. R(d), G(d), and B(d) are 435 the destination values when using the instruction on color and A(d) 436 is the destination value when using the instruction on alpha. 437 438 439 Op Result 440 -- ------ 441 ADD_ATI R(d) = R(a1) + R(a2) 442 G(d) = G(a1) + G(a2) 443 B(d) = B(a1) + B(a2) 444 A(d) = A(a1) + A(a2) 445 446 SUB_ATI R(d) = R(a1) - R(a2) 447 G(d) = G(a1) - G(a2) 448 B(d) = B(a1) - B(a2) 449 A(d) = A(a1) - A(a2) 450 451 MUL_ATI R(d) = R(a1) * R(a2) 452 G(d) = G(a1) * G(a2) 453 B(d) = B(a1) * B(a2) 454 A(d) = A(a1) * A(a2) 455 456 MAD_ATI R(d) = R(a1) * R(a2) + R(a3) 457 G(d) = G(a1) * G(a2) + G(a3) 458 B(d) = B(a1) * B(a2) + B(a3) 459 A(d) = A(a1) * A(a2) + A(a3) 460 461 LERP_ATI*** R(d) = R(a1) * R(a2) + (1 - R(a1)) * R(a3) 462 G(d) = G(a1) * G(a2) + (1 - G(a1)) * G(a3) 463 B(d) = B(a1) * B(a2) + (1 - B(a1)) * B(a3) 464 A(d) = A(a1) * A(a2) + (1 - A(a1)) * A(a3) 465 466 MOV_ATI R(d) = R(a1) 467 G(d) = G(a1) 468 B(d) = B(a1) 469 A(d) = A(a1) 470 471 CND_ATI R(d) = (R(a3) > 0.5) ? R(a1) : R(a2) 472 G(d) = (G(a3) > 0.5) ? G(a1) : G(a2) 473 B(d) = (B(a3) > 0.5) ? B(a1) : B(a2) 474 A(d) = (A(a3) > 0.5) ? A(a1) : A(a2) 475 476 CND0_ATI R(d) = (R(a3) >= 0) ? R(a1) : R(a2) 477 G(d) = (G(a3) >= 0) ? G(a1) : G(a2) 478 B(d) = (B(a3) >= 0) ? B(a1) : B(a2) 479 A(d) = (A(a3) >= 0) ? A(a1) : A(a2) 480 481 DOT2_ADD_ATI* R(d) = G(d) = B(d) = A(d) = R(a1) * R(a2) + 482 G(a1) * G(a2) + 483 B(a3) 484 485 DOT3_ATI* R(d) = G(d) = B(d) = A(d) = R(a1) * R(a2) + 486 G(a1) * G(a2) + 487 B(a1) * B(a2) 488 489 DOT4_ATI* ** R(d) = G(d) = B(d) = A(d) = R(a1) * R(a2) + 490 G(a1) * G(a2) + 491 B(a1) * B(a2) + 492 A(a1) * A(a2) 493 494 Table 3.21 Color and Alpha Fragment Shader Instructions 495 496 Special Notes: 497 * - DOT2_ADD_ATI/DOT3_ATI/DOT4_ATI can only be specified as 498 an alpha instruction directly after being specified as 499 a color instruction. When specified as an alpha 500 instruction, the parameters are ignored, although they 501 should be valid enumerants in order to compile. The 502 result of the color instruction will simply be placed 503 in the alpha <dst>. 504 505 ** - After a DOT4_ATI color instruction is specified, the 506 only alpha instruction that can immediately follow is a 507 DOT4_ATI. This is because the DOT4 color instruction 508 implicitely uses an alpha instruction to calculate the 509 result. If another type of alpha instruction is 510 desired after a DOT4_ATI color instruction is issued, 511 there are two choices: either issue another color 512 instruction first, or issue the DOT4_ATI alpha 513 instruction followed by the desired alpha instruction. 514 515 *** - The blend factor (a1) of LERP_ATI must be in the range 516 [0,1] or the results are undefined. 517 518 The <dst> parameter specifies to which register (REG_x_ATI) the 519 result of the instruction is written. 520 521 The <dstMask> parameter specifies which of the color components in 522 <dst> will be written (ColorFragmentOp[1..3]ATI only). This can 523 either be NONE, in which case there is no mask and everything is 524 written, or the bitwise-or of RED_BIT_ATI, GREEN_BIT_ATI, and 525 BLUE_BIT_ATI. 526 527 The <dstMod> parameter specifies which modifications are performed 528 on each component of the destination. The result can be modulated 529 by specifying either 2X_BIT_ATI, 4X_BIT_ATI, 8X_BIT_ATI, 530 HALF_BIT_ATI, QUARTER_BIT_ATI, or EIGHTH_BIT_ATI. These are all 531 mutually exclusive, and can optionally be bitwise-or'd with 532 SATURATE_BIT_ATI, which clamps the result after any modulation 533 occurs. 534 535 Table 3.22 shows the result of each <dstMod> modification. 536 537 538 Modifier Result 539 -------- ------ 540 NONE d = d 541 2X_BIT_ATI d = 2 * d 542 4X_BIT_ATI d = 4 * d 543 8X_BIT_ATI d = 8 * d 544 HALF_BIT_ATI d = d / 2 545 QUARTER_BIT_ATI d = d / 4 546 EIGHTH_BIT_ATI d = d / 8 547 SATURATE_BIT_ATI d = clamp(d) to range [0, 1] 548 549 Table 3.22 Result of destination modification 550 551 552 Note that the internal precision of the fragment shader allows 553 values in the range [-8, 8]. 554 555 The <argN> parameter specifies the source argument. The source can 556 come from REG_x_ATI, CON_x_ATI, ZERO, ONE, PRIMARY_COLOR_ARB, or 557 SECONDARY_INTERPOLATOR_ATI. Note that in a two-pass shader, 558 PRIMARY_COLOR_ARB and SECONDARY_INTERPOLATOR_ATI cannot be used in 559 the first pass of the shader. 560 561 Each argument has an <argNRep> parameter which specifies the 562 replication of each component. 563 564 Table 3.23 shows the result of each <argNRep> source replication. 565 566 567 Replication Result 568 ----------- ----- 569 NONE R(s) = R(s) 570 G(s) = G(s) 571 B(s) = B(s) 572 A(s) = A(s) 573 574 RED R(s) = R(s) 575 G(s) = R(s) 576 B(s) = R(s) 577 A(s) = R(s) 578 579 GREEN R(s) = G(s) 580 G(s) = G(s) 581 B(s) = G(s) 582 A(s) = G(s) 583 584 BLUE R(s) = B(s) 585 G(s) = B(s) 586 B(s) = B(s) 587 A(s) = B(s) 588 589 ALPHA R(s) = A(s) 590 G(s) = A(s) 591 B(s) = A(s) 592 A(s) = A(s) 593 594 Table 3.23 Result of source replication 595 596 597 Each argument also has an <argNMod> parameter which specifies 598 modifiers to each component. A value of NONE specifies that no 599 modifiers are present. Otherwise, the bitwise-or of NEGATE_BIT_ATI, 600 BIAS_BIT_ATI, and 2X_BIT_ATI can be specified as modifiers. 601 602 Table 3.24 shows the result of each <argNMod> source modifier. 603 604 605 Modifier Result 606 -------- ------ 607 NONE s = s 608 NEGATE_BIT_ATI s = -s 609 COMP_BIT_ATI s = 1 - s 610 BIAS_BIT_ATI s = s - 0.5 611 2X_BIT_ATI s = 2 * s 612 613 Table 3.24 Result of source modification 614 615 616 If multiple source modifiers are applied, the order of operations is 617 COMP, BIAS, SCALE, then NEGATE. The following equation shows the 618 order of operations if all modifiers were to be applied: 619 620 s = -(2 * ((1.0 - s) - 0.5)) 621 622 In order to set the constants that can be used by shader 623 instructions, the entry point: 624 625 void SetFragmentShaderConstantATI (uint dst, const float *value); 626 627 is used. The <dst> parameter specifies which of the constants 628 (CON_x_ATI) to set. The <value> pointer must contain four floating 629 point values in the range [0, 1] to set the components of the 630 constant. Constant registers loaded with floating point values 631 outside of this range will have undefined values. Calls to this 632 function which occur inside a shader definition are automatically 633 bound when the shader is bound. This means that shader constants 634 have scope: if SetFragmentShaderConstantATI is called outside a 635 shader definition, it is bound globally. However, if that same 636 shader constant is set inside the shader, it overrides the global 637 definition when bound. 638 639 640Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 641Operations and the Framebuffer) 642 643 None 644 645 646Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special 647Functions) 648 649 Modify Section 5.4, Display Lists (p. 175) 650 651 (modify last paragraph, p. 178) ... These are: IsList, GenLists, 652 ..., GenFragmentShadersATI, DeleteFragmentShadersATI, 653 BeginFragmentShaderATI, EndFragmentShaderATI, PassTexCoordATI, 654 SampleMapATI, ColorFragmentOp[1..3]ATI, AlphaFragmentOp[1..3]ATI, 655 as well as IsEnabled and all of the Get commands (see Chapter 6). 656 657 658Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and 659State Requests) 660 661 None 662 663 664Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) 665 666 None 667 668 669Additions to the AGL/GLX/WGL Specifications 670 671 None 672 673 674Interactions with ARB_shadow 675 676 The texture comparison introduced by ARB_shadow can be expressed in 677 terms of a fragment shader, and in fact use the same internal 678 resources on some implementations. Therefore, if fragment shader 679 mode is enabled, the GL behaves as if TEXTURE_COMPARE_MODE_ARB is 680 NONE. 681 682 683Errors 684 685 The error INVALID_VALUE is generated if GenFragmentShadersATI is 686 called where <range> is zero. 687 688 The error INVALID_OPERATION is generated if GenFragmentShadersATI, 689 BindFragmentShaderATI, DeleteFragmentShaderATI, or 690 BeginFragmentShaderATI are specified inside a 691 Begin/EndFragmentShaderATI pair. 692 693 The error INVALID_OPERATION is generated if EndFragmentShaderATI, 694 PassTexCoordATI, SampleMapATI, ColorFragmentOp[1..3]ATI, or 695 AlphaFragmentOp[1..3]ATI is specified outside a 696 Begin/EndFragmentShaderATI pair. 697 698 The error INVALID_OPERATION is generated by EndFragmentShaderATI if 699 <argN> passed to ColorFragmentOp[1..3]ATI or 700 AlphaFragmentOp[1..3]ATI is PRIMARY_COLOR_ARB or 701 SECONDARY_INTERPOLATOR_ATI on the first pass of a two-pass shader, 702 or if the shader cannot be compiled due to some other 703 implementation-dependent limitation. EndFragmentShaderATI will 704 still have a side-effect if this error is encountered: the 705 Begin/EndFragmentShaderATI pair will be closed, and the current 706 shader will be undefined. 707 708 The error INVALID_OPERATION is generated by PassTexCoordATI or 709 SampleMapATI if two shader passes have already been specified, or if 710 the same <dst> register is specified twice in the same pass. 711 712 The error INVALID_OPERATION is generated by PassTexCoordATI or 713 SampleMapATI if <coord> passed to PassTexCoordATI or <interp> passed 714 to SampleMapATI is a register in the first pass, or a register with 715 SWIZZLE_STQ_ATI or SWIZZLE_STQ_DQ_ATI <swizzle> in the second pass, 716 or if different <swizzle> parameters are specified for the same 717 <coord> or <interp> in the same pass. 718 719 The error INVALID_OPERATION is generated by ColorFragmentOp[1..3]ATI 720 or AlphaFragmentOp[1..3]ATI if more than 8 instructions have been 721 specified for a shader pass. 722 723 The error INVALID_OPERATION is generated by ColorFragmentOp[1..3]ATI 724 if <argN> is SECONDARY_INTERPOLATOR_ATI and <argNRep> is ALPHA, or 725 by AlphaFragmentOp[1..3]ATI if <argN> is SECONDARY_INTERPOLATOR_ATI 726 and <argNRep> is ALPHA or NONE, or by ColorFragmentOp2ATI if <op> is 727 DOT4_ATI and <argN> is SECONDARY_INTERPOLATOR_ATI and <argNRep> is 728 ALPHA or NONE. 729 730 The error INVALID_OPERATION is generated by ColorFragmentOp3ATI or 731 AlphaFragmentOp3ATI if all three <argN> parameters are constants, 732 and all three are different. 733 734 The error INVALID_OPERATION is generated by AlphaFragmentOp[2..3]ATI 735 if <op> is DOT3_ATI, DOT4_ATI, or DOT2_ADD_ATI and there was no 736 matching ColorFragmentOp[2..3]ATI immediately preceding, or if <op> 737 is not DOT4_ATI and the immediately preceding ColorFragmentOp2ATI 738 specifies an <op> of DOT4_ATI. 739 740 The error INVALID_ENUM is generated if <dst> passed to 741 PassTexCoordATI, SampleMapATI, ColorFragmentOp[1..3]ATI, or 742 AlphaFragmentOp[1..3]ATI is not a valid register or is greater than 743 the number of texture units available on the implementation. 744 745 The error INVALID_ENUM is generated if <coord> passed to 746 PassTexCoordATI or <interp> passed to SampleMapATI is not a valid 747 register or texture unit, or the register or texture unit is greater 748 than the number of texture units available on the implementation. 749 750 The error INVALID_ENUM is generated if <argN> passed to 751 ColorFragmentOp[1..3]ATI or AlphaFragmentOp[1..3]ATI is not a valid 752 constant, interpolator, or register. 753 754 The error INVALID_ENUM is generated if <dstMod> passed to 755 ColorFragmentOp[1..3]ATI or AlphaFragmentOp[1..3]ATI contains 756 multiple mutually exclusive modifier bits, not counting 757 SATURATE_BIT_ATI. 758 759 760New State 761 762 Initial 763 Get Value Type Get Command Value Description Sec. Attribute 764 --------- ---- ----------- ------- ----------- ------ --------- 765 FRAGMENT_SHADER_ATI B IsEnabled False Fragment shader enable 3.8.11 enable 766 767 Table X.6. New Accessible State Introduced by ATI_fragment_shader. 768 769 770 Get Value Type Get Command Initial Value Description Sec Attribute 771 --------- ------ ----------- ------------- ------------------- ------ --------- 772 - 6xR4 - undefined temporary registers 3.8.11 - 773 774 Table X.9. Fragment Shader Per-fragment Execution State. All per-fragment 775 execution state registers are uninitialized at the beginning of program 776 execution. 777 778 779New Implementation Dependent State 780 781 None 782 783 784Deprecated Functionality 785 786 The following queryable implementation-dependent constants are 787 described here for backward-compatibility. They are now specified 788 to always return fixed values on all implementations, and are thus 789 obsolete. 790 791 The number of available registers can be queried by doing a glGet on 792 NUM_FRAGMENT_REGISTERS_ATI. This refers to the number of 793 REG_x_ATI's, and is now fixed at 6. 794 795 The number of available constants can be queried by doing a glGet on 796 NUM_FRAGMENT_CONSTANTS. This refers to the number of CON_x_ATI's, 797 and is now fixed at 8. 798 799 The number of passes, instructions per pass, and total instructions 800 available to a shader can be queried using glGet. Querying for 801 NUM_PASSES_ATI returns the maximum number of passes that the shader 802 can perform, now fixed at 2. Querying for 803 NUM_INSTRUCTIONS_PER_PASS_ATI returns the maximum number of 804 instructions available on a given pass, now fixed at 8. Finally, 805 NUM_INSTRUCTIONS_TOTAL_ATI returns the maximum number of total 806 instructions available to a shader, now fixed at 16 (2 per pass). 807 808 COLOR_ALPHA_PAIRING_ATI can be queried by glGet to determine if each 809 ColorFragmentOp[1..3]ATI/AlphaFragmentOp[1..3]ATI pair counts as one 810 instruction against the limit, or if each color and alpha 811 instruction is counted individually (i.e., each pair counts as two 812 instructions). This query now always returns TRUE: each pair counts 813 as one instruction against the 8 instructions allowed per pass. 814 815 The number of components available in a coordinate interpolator, 816 passed in as <interp> to SampleMapATI or <coord> to PassTexCoord, 817 can be queried using NUM_INTERPOLATOR_COMPONENTS_ATI. This query 818 now always returns 3, meaning the fourth component is ignored. 819 820 The number of components passed in the registers via PassTexCoord 821 from the first pass to the second can be queried using 822 NUM_LOOPBACK_COMPONENTS_ATI. This query now always returns 3, 823 meaning the fourth component of <dst> is undefined. 824 825 826Sample Usage 827 828 The following is an example that simulates a chrome surface: 829 830 shadername = glGenFragmentShadersATI(1); 831 glBindFragmentShaderATI(shadername); 832 glBeginFragmentShaderATI(); 833 834 // Pass 1 835 glPassTexCoordATI(GL_REG_1_ATI, GL_TEXTURE1_ARB, GL_SWIZZLE_STR_ATI); // N 836 glPassTexCoordATI(GL_REG_2_ATI, GL_TEXTURE2_ARB, GL_SWIZZLE_STR_ATI); // light to vertex vector in light space 837 glPassTexCoordATI(GL_REG_3_ATI, GL_TEXTURE3_ARB, GL_SWIZZLE_STR_ATI); // H 838 glSampleMapATI(GL_REG_4_ATI, GL_TEXTURE4_ARB, GL_SWIZZLE_STR_ATI); // L (sample cubemap normalizer) 839 840 // reg4 = N.L 841 glColorFragmentOp2ATI(GL_DOT3_ATI, GL_REG_4_ATI, GL_NONE, GL_NONE, 842 GL_REG_1_ATI, GL_NONE, GL_NONE, 843 GL_REG_4_ATI, GL_NONE, GL_2X_BIT_ATI|GL_BIAS_BIT_ATI); 844 845 // reg1 = N.H 846 glColorFragmentOp2ATI(GL_DOT3_ATI, GL_REG_1_ATI, GL_NONE, GL_NONE, 847 GL_REG_1_ATI, GL_NONE, GL_NONE, 848 GL_REG_3_ATI, GL_NONE, GL_NONE); 849 850 // reg1(green) = H.H (aka |H|^2) 851 glColorFragmentOp2ATI(GL_DOT3_ATI, GL_REG_1_ATI, GL_GREEN_BIT_ATI, GL_NONE, 852 GL_REG_3_ATI, GL_NONE, GL_NONE, 853 GL_REG_3_ATI, GL_NONE, GL_NONE); 854 855 // reg2 = |light to vertex|^2 856 glColorFragmentOp2ATI(GL_DOT3_ATI, GL_REG_2_ATI, GL_NONE, GL_NONE, 857 GL_REG_2_ATI, GL_NONE, GL_NONE, 858 GL_REG_2_ATI, GL_NONE, GL_NONE); 859 860 // Pass 2 861 glSampleMapATI(GL_REG_0_ATI, GL_TEXTURE5_ARB, GL_SWIZZLE_STR_ATI); // sample enviroment map using eye vector 862 glSampleMapATI(GL_REG_2_ATI, GL_REG_2_ATI, GL_SWIZZLE_STR_ATI); // sample attenuation map 863 glSampleMapATI(GL_REG_3_ATI, GL_REG_1_ATI, GL_SWIZZLE_STR_ATI); // sample specular NHHH map = (N.H)^256 864 glPassTexCoordATI(GL_REG_4_ATI, GL_REG_4_ATI, GL_SWIZZLE_STR_ATI); // pass N.L through 865 866 // reg3 = (N.H)^256 * (N.L) 867 // this ensures a pixel is only lit if facing the light (since the specular exponent 868 // makes negative N.H positive we must do this) 869 glColorFragmentOp2ATI(GL_MUL_ATI, GL_REG_3_ATI, GL_NONE, GL_NONE, 870 GL_REG_3_ATI, GL_NONE, GL_NONE, 871 GL_REG_4_ATI, GL_NONE, GL_NONE); 872 873 // reg3 = specular * environment map 874 glColorFragmentOp2ATI(GL_MUL_ATI, GL_REG_3_ATI, GL_NONE, GL_NONE, 875 GL_REG_0_ATI, GL_NONE, GL_NONE, 876 GL_REG_3_ATI, GL_NONE, GL_NONE); 877 878 // reg4 = diffuse * environment map 879 glColorFragmentOp2ATI(GL_MUL_ATI, GL_REG_4_ATI, GL_NONE, GL_NONE, 880 GL_REG_0_ATI, GL_NONE, GL_NONE, 881 GL_REG_4_ATI, GL_NONE, GL_NONE); 882 883 // reg0 = (specular * environment map) + (diffuse * environment map) 884 glColorFragmentOp2ATI(GL_ADD_ATI, GL_REG_0_ATI, GL_NONE, GL_NONE, 885 GL_REG_3_ATI, GL_NONE, GL_NONE, 886 GL_REG_4_ATI, GL_NONE, GL_NONE); 887 888 // apply point light attenuation 889 glColorFragmentOp2ATI(GL_MUL_ATI, GL_REG_0_ATI, GL_NONE, GL_SATURATE_BIT_ATI, 890 GL_REG_0_ATI, GL_NONE, GL_NONE, 891 GL_REG_2_ATI, GL_RED, GL_NONE); 892 glEndFragmentShaderATI(); 893 894 895Revision History 896 897 Date: 11/4/2006 898 Revision: 1.8 899 - Updated contact info after ATI/AMD merger. 900 901 Date: 8/21/2002 902 Revision: 1.7 903 - Fixed lack of comma typo in glAlphaFragmentOp2ATI prototypes. 904 905 Date: 8/1/2002 906 Revision: 1.6 907 - Changed DeleteFragmentShaderATI behavior to silently ignore the 908 deletion of non-existent or default shaders. 909 910 Date: 6/5/2002 911 Revision: 1.5 912 - Added interaction with ARB_shadow. 913 914 Date: 5/30/2002 915 Revision: 1.4 916 - Specified that LERP's blend factor must be in the range [0,1]. 917 - Added error condition when trying to use secondary color in DOT4 918 color instruction when replication is GL_NONE or GL_ALPHA. 919 920 Date: 5/21/2002 921 Revision: 1.3 922 - Made number of registers (REG_x_ATI) explicit: 6. 923 - Changed CND0_ATI definition from >0 to >=0. 924 - Added wording to emphasize [0,1] range for constants. 925 - Added wording to reflect that EndFragmentShaderATI will close 926 Begin/End pair even if error is encountered. 927 - Added wording to reflect parallelism of color/alpha pairs. 928 - Added error condition when trying to use secondary color alpha. 929 - Added error condition when generating shader IDs with <range> 0. 930 - Added display list exclusion for everything except 931 BindFragmentShaderATI and SetFragmentShaderConstantATI. 932 - Cleaned up, fixed typos, and reformatted. 933 - Added New State section. 934 - Replaced sample code. 935 936 Date: 4/19/2002 937 Revision: 1.2 938 - Updated swizzle table to indicate that projected texcoords are 939 undefined when used in conjunction with cubemaps or 3D textures. 940 941 Date: 3/20/2002 942 Revision: 1.1 943 - Made resource availability explicit. 944 - Deprecated implementation-dependent constant queries. 945 - Added various error conditions described in prose of spec. 946 - Changed PRIMARY_COLOR_EXT to PRIMARY_COLOR_ARB. 947 - Cleaned up and fixed typos throughout. 948 949 Date: 1/2/2002 950 Revision: 1.02 951 - Added note that PRIMARY_COLOR_EXT and SECONDARY_INTERPOLATOR_ATI can not 952 be used on the first pass of a two pass shader. Also added error 953 for this case to Errors section. 954 - Added note that in order to save the contents of a register from the 955 first pass to the second, there has to be a PassTexCoordATI() on that 956 register to itself on the next pass. 957 - Changed PRIMARY_COLOR to PRIMARY_COLOR_EXT. 958 959 Date: 10/15/2001 960 Revision: 1.01 961 - Fixed typos in example program. 962 - Added language about the shader result being placed in REG_0_ATI. 963 - Specify range supported [-8..8]. 964 - Added notes on how to specify whether DOT4/DOT3/DOT2_ADD result 965 goes to alpha channel. 966 967 Date: 8/21/2001 968 Revision: 1.0 969 - Added equation for source modifiers. 970 971 Date: 8/6/2001 972 Revision: 0.6 973 - Added restraint that only SWIZZLE_STR_ATI and SWIZZLE_STR_DR_ATI 974 can be used on the second pass when the source is a register. 975 976 Date: 6/29/2001 977 Revision: 0.5 978 - Removed glTexProjectATI and change glSampleMapATI/glPassTexCoordATI to 979 take a <swizzle> parameter instead of <project>. 980 - Changed MAD_ATI from (a + b * c) to (a * b + c). 981 982 Date: 6/11/2001 983 Revision: 0.4 984 - Removed FRAC_ATI. 985 - Added <project> parameter to SampleMapATI and PassTexCoordATI to 986 match current implementation. 987 988 Date: 5/01/2001 989 Revision: 0.3 990 - Added COLOR_ALPHA_PAIRING_ATI. 991 - Attempted to clarify definition of SampleMapATI in the documentation 992 section. Changed <map> to <interp>. 993 - Added TexProjectATI and documented texture projection modes to allow 994 implementations that only support 3-tuples to select between (s, t, r) 995 and (s, t, q) coordinates. 996 997 Date: 4/19/2001 998 Revision: 0.2 999 - Removed <dstRot> from ColorFragmentOp[1..3]ATI. 1000 - Changed SHADER_ATI to FRAGMENT_SHADER_ATI. 1001 - Fixed the <op>'s in the New Tokens section to go to the proper 1002 Color/AlphaOp functions. 1003 - Added ZERO and ONE constants. 1004 - Made number of passes queryable: removed NUM_PASSn_INSTRUCTIONS_ATI, 1005 replaced with NUM_PASSES_ATI, NUM_INSTRUCTIONS_PER_PASS_ATI, and 1006 NUM_INSTRUCTIONS_TOTAL_ATI. 1007 - Documented when new pass starts (SampleMapATI/PassCoordATI). 1008 - Added NUM_INPUT_INTERPOLATOR_COMPONENTS_ATI/NUM_LOOPBACK_COMPONENTS_ATI. 1009 - Fixed sample usage to not do a dependent read on the base map. 1010 1011 Date: 4/16/2001 1012 Revision: 0.1 1013 - First draft 1014