1Name 2 3 APPLE_float_pixels 4 5Name Strings 6 7 GL_APPLE_float_pixels 8 9Contact 10 11 Geoff Stahl, Apple (gstahl 'at' apple.com) 12 Jeremy Sandmel, Apple (jsandmel 'at' apple.com) 13 14Status 15 16 Shipping Mac OS X v10.2.3 (version 1.0) 17 18Version 19 20 1.0 21 22Number 23 24 368 25 26Dependencies 27 28 Written based on the wording of the OpenGL 2.0 specification. 29 30 Depends on (but does not require) ARB_texture_float 31 32 Depends on (but does not require) ARB_color_buffer_float 33 34 Depends on (but does not require) ARB_half_float_pixel 35 36 Interacts with APPLEX_texture_float_16_filter. 37 38 Interacts with APPLEX_color_buffer_float_16_blend. 39 40Overview 41 42 This extensions adds texture types, texture internal formats and 43 color buffers composed of both 32 bit and 16 floating point numbers. 44 16 bit floats (half float) are very similar to the IEEE 45 single-precision floating-point standard, except that it has only 5 46 exponent bits and 10 mantissa bits. All floating point numbers are 47 clamped to the limits of the range representable by their respective 48 format. 49 50 Specifically, APPLE_float_pixels adds four pieces of functionality 51 to OpenGL. First, it provides an HALF_APPLE texture type allowing 52 clients to pass textures in the half float format. Second, it adds 53 12 additional sized internal formats to allow OpenGL to process and 54 maintain texture data in the requested format if possible. Next, it 55 provides the COLOR_FLOAT_APPLE pixel format to allow creation of 56 floating point and half float color buffers. Lastly, it provides an 57 additional query to allow clients to verify that they have a 58 floating point color buffer. 59 60 The HALF_APPLE texture type allows clients to use source textures 61 composed of half float color components. This constant is use in 62 the type parameter in DrawPixels, ReadPixels and texturing commands 63 with a corresponding GL half data type, which corresponds to a 16 64 bit half float, and has no special interpretation. 65 66 Clients can use the 12 additional (6 floating point and 6 half 67 float) sized internal texture formats to specify the mapping of R, 68 G, B and A values to texture components, as they would with any 69 other sized internal texture format. Note, as is the standard 70 practice with OpenGL, implementations should map the sized internal 71 texture R, G, B and A values to internal components with memory 72 allocations as close as possible to those specified in the sized 73 internal format. 74 75 Floating point color buffers are created by specifying the 76 appropriate color floating point pixel format attribute for the 77 windowing system API in use by the client. Both 128 bit and 64 bit 78 floating point color buffers can be supported, the former with full 79 32 bit floating point components and the latter with 16 bit half 80 float components. 81 82 Additionally, clients can query to see if they have a floating point 83 color buffer using GetBooleanv with COLOR_FLOAT_APPLE as the get 84 value. The number of bits per color buffer component can be 85 determined in the usual manner. 86 87Issues: 88 89 1. How is this extension different from the ARB floating point extensions? 90 91 Conceptually, this extension can be considered the union of the 92 feature sets from the following extensions: 93 94 ARB_texture_float 95 ARB_color_buffer_float 96 ARB_half_float_pixel 97 98 with the following EXCEPTIONS: 99 100 * this extension does not support the the per-component 101 query of TEXTURE_*_TYPE from ARB_texture_float. 102 103 * this extension only supports the half float pixel type 104 from ARB_half_float_pixel for {Draw|Read}|Pixels and 105 Tex{Sub}Image{1D|2D|3D}, and for color buffers as 106 described by ARB_color_buffer_float. (Note: unlike the 107 ARB_half_float extension, APPLE_float_pixels does not 108 support using 16 bit half float data with the imaging 109 subset routines that accept images, i.e., 110 ConvolutionFilter{1D|2D}, ColorTable, etc. 111 112 * this extension does not include the ClampColorARB routine 113 from ARB_color_buffer_float. It does, however, use the 114 default clamping behavior specified in the 115 ARB_color_buffer_float extension. 116 117 Note that this means the following in this extension: 118 119 - vertex color outputs are always clamped, regardless of 120 color buffer format 121 - fragment color outputs are clamped when writing to a 122 fixed point color buffer and unclamped when writing to 123 a floating point color buffer, and 124 - the read color returned by 125 ReadPixels/CopyPixels/GetTexImage/etc. is clamped when 126 reading from a fixed point format and unclamped when 127 reading from a floating point format. 128 129 * unlike ARB_texture_float, this extension only supports 130 GL_NEAREST filtering for float (and half float) textures. 131 132 * unlike ARB_color_buffer_float, this extension does not 133 support src/dst alpha blending on float (and half float) 134 destination color buffers. 135 136 2. Since this extension is more limited than the ARB floating point 137 extensions, what is the appropriate (and "future-proof") method 138 for an application to use to query for floating point color 139 buffer and texture support? 140 141 This extension and the related extensions 142 APPLEX_color_buffer_float_16_blend and 143 APPLEX_texture_float_16_filter, should be considered 144 "transitional" in nature. The limited functionality described by 145 these extensions is superseded by the more powerful ARB 146 extensions and as hardware becomes more capable, it is possible 147 that future revisions of OpenGL may deprecate or remove them 148 altogether. 149 150 As such, to allow for ease of transition to support of the ARB 151 floating point extensions, applications are *strongly* 152 encouraged to use the following algorithm to query for floating 153 point texture and color buffer support: 154 155 // any Floating Point Support at all? 156 bool supportsFloatColorBuffers = FALSE; 157 bool supportsFloatTextures = FALSE; 158 159 // 16 bit/component Floating Point Blend/Filter Support? 160 bool supportsFloat16ColorBufferBlending = FALSE; 161 bool supportsFloat16TextureFiltering = FALSE; 162 163 // 32 bit/component Floating Point Blend/Filter Support? 164 bool supportsFloat32ColorBufferBlending = FALSE; 165 bool supportsFloat32TextureFiltering = FALSE; 166 167 // =============================================== 168 // Check for floating point texture support 169 // 170 // * First check for full ARB_texture_float 171 // extension and only then check for more 172 // limited APPLE and APPLEX texture extensions 173 // =============================================== 174 if (extensionSupported("ARB_texture_float")) 175 { 176 supportsFloatTextures = TRUE; 177 supportsFloat16TextureFiltering = TRUE; 178 supportsFloat32TextureFiltering = TRUE; 179 } 180 else if (extensionSupported("APPLE_float_pixels")) 181 { 182 supportsFloatTextures = TRUE; 183 184 if (extensionSupported("APPLEX_texture_float_16_filter")) 185 { 186 supportsFloat16TextureFiltering = TRUE; 187 } 188 } 189 190 // =============================================== 191 // Check for floating point color buffer support 192 // 193 // * First check for full ARB_color_buffer_float 194 // extension and only then check for more 195 // limited APPLE and APPLEX color buffer extensions 196 // =============================================== 197 if (extensionSupported("ARB_color_buffer_float")) 198 { 199 supportsFloatColorBuffers = TRUE; 200 supportsFloat16ColorBufferBlending = TRUE; 201 supportsFloat32ColorBufferBlending = TRUE; 202 } 203 else if (extensionSupported("APPLE_float_pixels")) 204 { 205 supportsFloatColorBuffers = TRUE; 206 207 if (extensionSupported("APPLEX_color_buffer_float_16_blend")) 208 { 209 supportsFloat16ColorBufferBlending = TRUE; 210 } 211 } 212 213 214 3. Why does this extension (and the related APPLEX_*_float_* 215 extensions) even exist, given the existence of the ARB, ATI, and 216 NVIDIA floating point extensions? 217 218 A good question. This extension was developed contemporaneously 219 with the ATI and NVIDIA extensions and support for this 220 extension in Mac OS X's OpenGL implementation predates the 221 definition of the ARB extensions. In addition, this extension 222 specification attempts to document the behavior of the APPLE 223 extension to support use of floating point features on hardware 224 which may not support the full feature set described by the ARB 225 extensions. The behavior of the APPLE extension more closely 226 matches the feature set of this class of hardware and can be 227 used by applications to get a more accurate description of 228 native hardware support when falling back to software rendering 229 may not be appropriate. 230 231 It is expected that as hardware renderers becomes more capable 232 the Mac OS X OpenGL implementation will transition to supporting 233 the ARB extensions and may deprecate and/or remove these APPLE 234 extensions from the API. Please see issue #2 for details on how 235 to query for floating point support in a "future-proof" manner. 236 237 238 4. What will happen when the ARB floating point extensions are 239 supported? 240 241 The APPLE_float_pixels and the related 242 APPLEX_texture_float_16_filter and 243 APPLEX_color_buffer_float_16_blend extensions are intended as a 244 strict subset of the functionality in ARB_texture_float, 245 ARB_color_buffer_float, and ARB_half_float_pixel. 246 247 Consequently, an implementation could legally support all of 248 these extensions simulataneously, however once the ARB 249 extensions are supported there is no need to export the 250 APPLE{X}_* floating point extensions. 251 252 Consequently, it's possible that implementations may deprecate 253 or remove the APPLE_float_pixels, 254 APPLEX_texture_float_16_filter, and 255 APPLEX_color_buffer_float_16_blend extensions when the 256 corresponding ARB extensions are supported by the underlying 257 hardware. Applications should pay attention to issue #2 above 258 to prepare for this possibility. 259 260 261New Procedures and Functions 262 263 None 264 265New Tokens 266 267 Accepted by the parameters of DrawPixels, ReadPixels, TexImage1D, 268 TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D, and 269 GetTexImage: 270 271 HALF_APPLE 0x140B // Same as HALF_FLOAT_NV/ARB 272 273 Accepted by the GetBooleanv: 274 275 COLOR_FLOAT_APPLE 0x8A0F 276 277 Accepted by the parameter of TexImage1D, 278 TexImage2D, and TexImage3D: 279 280 RGBA_FLOAT32_APPLE 0x8814 // Same as RGBA_FLOAT32_ATI/ARB 281 RGB_FLOAT32_APPLE 0x8815 // Same as RGB_FLOAT32_ATI/ARB 282 ALPHA_FLOAT32_APPLE 0x8816 // Same as ALPHA_FLOAT32_ATI/ARB 283 INTENSITY_FLOAT32_APPLE 0x8817 // Same as INTENSITY_FLOAT32_ATI/ARB 284 LUMINANCE_FLOAT32_APPLE 0x8818 // Same as LUMINANCE_FLOAT32_ATI/ARB 285 LUMINANCE_ALPHA_FLOAT32_APPLE 0x8819 // Same as LUMINANCE_ALPHA_FLOAT32_ATI/ARB 286 RGBA_FLOAT16_APPLE 0x881A // Same as RGBA_FLOAT16_ATI/ARB 287 RGB_FLOAT16_APPLE 0x881B // Same as RGB_FLOAT16_ATI/ARB 288 ALPHA_FLOAT16_APPLE 0x881C // Same as ALPHA_FLOAT16_ATI/ARB 289 INTENSITY_FLOAT16_APPLE 0x881D // Same as NTENSITY_FLOAT16_ATI/ARB 290 LUMINANCE_FLOAT16_APPLE 0x881E // Same as LUMINANCE_FLOAT16_ATI/ARB 291 LUMINANCE_ALPHA_FLOAT16_APPLE 0x881F // Same as LUMINANCE_ALPHA_FLOAT16_ATI/ARB 292 293Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 294 295 Add a new Section 2.1.2, (p. 6): 296 297 2.1.2 16-Bit Floating-Point Numbers 298 299 A 16-bit floating-point number has a 1-bit sign (S), a 5-bit 300 exponent (E), and a 10-bit mantissa (M). The value of a 16-bit 301 floating-point number is determined by the following: 302 303 (-1)^S * 0.0, if E == 0 and M == 0, 304 (-1)^S * 2^-14 * (M / 2^10), if E == 0 and M != 0, 305 (-1)^S * 2^(E-15) * (1 + M/2^10), if 0 < E < 31, 306 (-1)^S * INF, if E == 31 and M == 0, or 307 NaN, if E == 31 and M != 0, 308 309 where 310 311 S = floor((N mod 65536) / 32768), 312 E = floor((N mod 32768) / 1024), and 313 M = N mod 1024. 314 315 Implementations are also allowed to use any of the following 316 alternative encodings: 317 318 (-1)^S * 0.0, if E == 0 and M != 0, 319 (-1)^S * 2^(E-15) * (1 + M/2^10), if E == 31 and M == 0, or 320 (-1)^S * 2^(E-15) * (1 + M/2^10), if E == 31 and M != 0, 321 322 Any representable 16-bit floating-point value is legal as input 323 to a GL command that accepts 16-bit floating-point data. The 324 result of providing a value that is not a floating-point number 325 (such as infinity or NaN) to such a command is unspecified, but 326 must not lead to GL interruption or termination. Providing a 327 denormalized number or negative zero to GL must yield predictable 328 results. 329 330 (modify Table 2.2, p. 9) -- add new row 331 332 Minimum 333 GL Type Bit Width Description 334 ------- --------- ----------------------------------- 335 half 16 half-precision floating-point value 336 encoded in an unsigned scalar 337 338 Modify Section 2.14, (Colors and Coloring), p. 59 339 340 (modify Table 2.9, p. 59) Add new row to the table: 341 342 GL Type Conversion 343 ------- ---------- 344 half c 345 346 347Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 348 349 Modify Section 3.6.4 (Rasterization of Pixel Rectangles), p. 126 350 351 (modify next-to-last paragraph, p.136, "Final Conversion") ... For 352 RGBA components, if fragment color clamping is enabled, each element 353 is clamped to [0,1], and may be converted to fixed-point according 354 to the rules given in section 2.14.9 (Final Color Processing). If 355 fragment color clamping is disabled, RGBA components are unmodified. 356 For the purposes of this specification, fragment color clamping is 357 enabled implicitly if all enabled color buffers have fixed-point 358 components. 359 360 Modify Section 3.8.1 (Texture Image Specification), p. 150 361 362 (modify second paragraph, p. 151) The selected groups are processed 363 exactly as for DrawPixels, stopping just before final conversion. 364 For R, G, B, and A, if the <internalformat> of the texture is 365 fixed-point, the components are clamped to [0, 1]. Otherwise, the 366 components are not modified. The depth value so generated is 367 clamped to [0, 1]. 368 369 (modify the second paragraph, p. 152) The internal component resolution 370 is the number of bits allocated to each value in a texture image. If 371 <internalformat> is specified as a base internal format, the GL stores 372 the resulting texture with internal component resolutions of its own 373 choosing. If a sized internal format is specified, the mapping of the 374 R, G, B, A, and depth values to texture components is equivalent to the 375 mapping of the corresponding base internal format's components, as 376 specified in table 3.15, the type (unsigned int, float, etc.) is 377 assigned the same type specified by <internalFormat>, and the memory 378 allocation per texture component is assigned by the GL to match the 379 allocations listed in table 3.16 as closely as possible. (The definition 380 of closely is left up to the implementation. Implementations are not 381 required to support more than one resolution of each type (unsigned int, 382 float, etc.) for each base internal format.) If a compressed internal 383 format is specified, the mapping of the R, G, B, A, and depth values to 384 texture components is equivalent to the mapping of the corresponding 385 base internal format's components, as specified in table 3.15. The 386 specified image is compressed using a (possibly lossy) compression 387 algorithm chosen by the GL. 388 389 (add the following to table 3.16, p. 154) 390 391 Sized Base R G B A L I 392 Internal Format Internal Format bits bits bits bits bits bits 393 --------------------------- --------------- ---- ---- ---- ---- ---- ---- 394 RGBA32F_ARB RGBA f32 f32 f32 f32 395 RGB32F_ARB RGB f32 f32 f32 396 ALPHA32F_ARB ALPHA f32 397 INTENSITY32F_ARB INTENSITY f32 398 LUMINANCE32F_ARB LUMINANCE f32 399 LUMINANCE_ALPHA32F_ARB LUMINANCE_ALPHA f32 f32 400 RGBA16F_ARB RGBA f16 f16 f16 f16 401 RGB16F_ARB RGB f16 f16 f16 402 ALPHA16F_ARB ALPHA f16 403 INTENSITY16F_ARB INTENSITY f16 404 LUMINANCE16F_ARB LUMINANCE f16 405 LUMINANCE_ALPHA16F_ARB LUMINANCE_ALPHA f16 f16 406 407 Table 3.16: Correspondence of sized internal formats to base 408 internal formats, and desired component resolutions for each 409 sized internal format. The notation <f16> and <f32> imply 410 16- and 32-bit floating-point, respectively. 411 412 Modify Section 3.8.4 (Texture Parameters), p. 166 413 414 (remove TEXTURE_BORDER_COLOR from end of first paragraph, p. 166) 415 416 ... If the value for TEXTURE_PRIORITY is specified as an integer, 417 the conversion for signed integers from table 2.9 is applied to 418 convert this value to floating-point, followed by clamping the 419 value to lie in [0, 1]. 420 421 (modify last paragraph, p. 174) ... If the texture contains color 422 components, the values of TEXTURE BORDER COLOR are interpreted as 423 an RGBA color to match the texture's internal format in a manner 424 consistent with table 3.15. The border values for texture 425 components stored as fixed-point values are clamped to [0, 1] 426 before they are used. If the texture contains depth ... 427 428 429 Add a new section, after 3.8.9 and prior to section 3.8.10, p. 177 430 431 3.8.9.5 Floating point formats and texture filters 432 433 Due to limitations in current render hardware, textures with 434 floating point formats may not support minification or magnification 435 filters that require LINEAR filtering in the manner described above. 436 437 Specifically, if the texture filter is neither GL_NEAREST nor 438 GL_NEAREST_MIPMAP_NEAREST, and *any* of following conditions are 439 true: 440 441 * the <internalformat> of the texture is a 32-bit/component 442 floating point format and ARB_texture_float is not supported 443 by the implementation, *or* 444 445 * the <internalformat> of the texture is a 16-bit/component 446 floating point format and APPLEX_texture_float_16_filter 447 extension is not supported by the implementation, 448 449 then the GL will interpret texture minification and magnification filters 450 according to the table (xxx.1) listed below: 451 452 specified filter will behave as: 453 ---------------- -------------- 454 LINEAR NEAREST 455 NEAREST_MIPMAP_LINEAR NEAREST_MIPMAP_NEAREST 456 LINEAR_MIPMAP_NEAREST NEAREST_MIPMAP_NEAREST 457 LINEAR_MIPMAP_LINEAR NEAREST_MIPMAP_NEAREST 458 ---------------------------------------------------- 459 Table xxx.1 - floating point texture filter behavior 460 461 Otherwise, the texture minification and magnfication filters behave 462 as specified earlier in section 3.8.8 and 3.8.9. 463 464 465 Modify Section 3.8.13 (Texture Environments and Functions), p.182 466 467 (modify third paragraph, p. 183, removing clamping language) 468 ...TEXTURE_ENV_COLOR is set to an RGBA color by providing four 469 single-precision floating-point values. If integers are provided 470 for TEXTURE ENV COLOR, then they are converted to floating-point 471 as specified in table 2.9 for signed integers. 472 473 (replace the sixth paragraph of p. 183) If fragment color clamping 474 is enabled, all of these color values, including the results, are 475 clamped to the range [0,1]. If fragment color clamping is 476 disabled, the values are not clamped. The texture functions are 477 specified in tables 3.22, 3.23, and 3.24. 478 479 (modify seventh paragraph of p. 183) ... ALPHA_SCALE, respectively. 480 If fragment color clamping is enabled, the arguments and results 481 used in table 3.24 are clamped to [0,1]. Otherwise, the results 482 are unmodified. 483 484 Modify Section 3.9 (Color Sum), p. 191 485 486 (modify second paragraph) ... the A component of c_sec is unused. 487 If color sum is disabled, then c_pri is assigned to c. The 488 components of c are then clamped to the range [0,1] if and only 489 if fragment color clamping is enabled. 490 491 Modify Section 3.10 (Fog), p. 191 492 493 (modify fourth paragraph, p. 192, removing clamping language) ...If 494 these are not floating-point values, then they are converted to 495 floating-point using the conversion given in table 2.9 for signed 496 integers. If fragment color clamping is enabled, the components of 497 C_r and C_f and the result C are clamped to the range [0,1] before 498 the fog blend is performed. 499 500 Modify Section 3.11.2 (Shader Execution), p. 194 501 502 (modify Shader Inputs, first paragraph, p. 196) The built-in 503 variables gl_Color and gl_SecondaryColor hold the R, G, B, and A 504 components, respectively, of the fragment color and secondary 505 color. If the primary color or the secondary color components are 506 represented by the GL as fixed-point values, they undergo an 507 implied conversion to floating-point. This conversion must leave 508 the values 0 and 1 invariant. Floating-point color components 509 (resulting from a disabled vertex color clamp) are unmodified. 510 511 (modify Shader Outputs, first paragraph, p. 196) ... These are 512 gl_FragColor, gl_FragData[n], and gl_FragDepth. If fragment 513 clamping is enabled, the final fragment color values or the final 514 fragment data values written by a fragment shader are clamped to 515 the range [0, 1] and then may be converted to fixed-point as 516 described in section 2.14.9. If fragment clamping is disabled, 517 the final fragment color values or the final fragment data values 518 are not modified. The final fragment depth... 519 520Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 521Operations and the Frame Buffer) 522 523 524 Modify Chapter 4 Introduction, (p. 198) 525 526 (modify third paragraph, p. 198) Color buffers consist of either 527 unsigned integer color indices, R, G, B and optionally A unsigned 528 integer values, or R, G, B, and optionally A floating-point values. 529 The number of bitplanes... 530 531 Modify Section 4.1.3 (Multisample Fragment Operations), p. 200 532 533 (modify last paragraph, p. 200) ...and all 0's corresponding to all 534 alpha values being 0. The alpha values used to generate a coverage 535 value are clamped to the range [0,1]. It is also intended ... 536 537 Modify Section 4.1.5 (Alpha Test), p. 201 538 539 (modify first paragraph of section, deleting clamping of 540 reference value) ... The test is controlled with 541 542 void AlphaFunc(enum func, float ref); 543 544 func is a symbolic constant indicating the alpha test function; 545 ref is a reference value. When performing the alpha test, the GL 546 will convert the reference value to the same representation as the 547 the fragment's alpha value (floating-point or fixed-point). 548 For fixed-point, the reference value is converted according to the 549 rules given for an A component in section 2.14.9 and the fragment's 550 alpha value is rounded to the nearest integer. The possible ... 551 552 Modify Section 4.1.8 (Blending), p. 205 553 554 (modify first paragraph, p. 206) Source and destination values are 555 combined according to the blend equation, quadruplets of source and 556 destination weighting factors determined by the blend functions, and 557 a constant blend color to obtain a new set of R, G, B, and A values, 558 as described below. 559 560 If the color buffer is fixed-point, the components of the source 561 and destination values and blend factors are clamped to [0, 1] 562 prior to evaluating the blend equation, the components of the 563 blending result are clamped to [0,1] and converted to fixed- 564 point values in the manner described in section 2.14.9. If the 565 color buffer is floating-point, no clamping occurs. The 566 resulting four values are sent to the next operation. 567 568 Blending is dependent on the incoming fragment's alpha value and 569 that of the corresponding currently stored pixel. Blending applies 570 only in RGBA mode and only one of the following conditions is true: 571 572 * the format of the current color buffer is fixed-point, *or* 573 574 * the format of current color buffer(s) is 16 bit floating point 575 and the APPLEX_color_buffer_float_16_blend extension is 576 supported by the implementation, *or* 577 578 * the format of the current color buffer is floating-point and 579 the ARB_color_buffer_float extension is supported by the 580 implementation. 581 582 Otherwise, the blending stage is bypassed. Blending is enabled or 583 disabled using Enable or Disable with the symbolic constant BLEND. 584 If it is disabled (or bypassed), or if logical operation on color 585 values is enabled (section 4.1.10), proceed to the next operation. 586 587 (modify fifth paragraph, p. 206) Fixed-point destination 588 (framebuffer) components are taken to be fixed-point values 589 represented according to the scheme given in section 2.14.9 590 (Final Color Processing). Constant color components, floating- 591 point destination components, and source (fragment) components are 592 taken to be floating point values. If source components are 593 represented internally by the GL as either fixed-point values they 594 are also interepreted according to section 2.14.9. 595 596 (modify Blend Color section removing the clamp, p. 209) The 597 constant color C_c to be used in blending is specified with the 598 command 599 600 void BlendColor(float red, float green, float blue, float alpha); 601 602 The constant color can be used in both the source and destination 603 blending functions. 604 605 Replace Section 4.1.9 (Dithering), p. 209 606 607 Dithering selects between two representable color values or indices. 608 A representable value is a value that has an exact representation in 609 the color buffer. In RGBA mode dithering selects, for each color 610 component, either the most positive representable color value (for 611 that particular color component) that is less than or equal to the 612 incoming color component value, c, or the most negative 613 representable color value that is greater than or equal to c. The 614 selection may depend on the x_w and y_w coordinates of the pixel, as 615 well as on the exact value of c. If one of the two values does not 616 exist, then the selection defaults to the other value. 617 618 In color index mode dithering selects either the largest 619 representable index that is less than or equal to the incoming 620 color value, c, or the smallest representable index that is greater 621 than or equal to c. If one of the two indices does not exist, then 622 the selection defaults to the other value. 623 624 Many dithering selection algorithms are possible, but an individual 625 selection must depend only on the incoming color index or component 626 value and the fragment's x and y window coordinates. If dithering 627 is disabled, then each incoming color component c is replaced with 628 the most positive representable color value (for that particular 629 component) that is less than or equal to c, or by the most negative 630 representable value, if no representable value is less than or equal 631 to c; a color index is rounded to the nearest representable index 632 value. 633 634 Dithering is enabled with Enable and disabled with Disable using the 635 symbolic constant DITHER. The state required is thus a single bit. 636 Initially dithering is enabled. 637 638 Section 4.1.10 (Logical Operation), p. 210 639 640 (insert after the first sentence, p. 210) Logical operation has no 641 effect on a floating-point destination color buffer. However, if 642 COLOR_LOGIC_OP is enabled, blending is still disabled. 643 644 Modify Section 4.2.3 (Clearing the Buffers), p. 215 645 646 (modify second paragraph, p. 216, removing clamp of clear color) 647 648 void ClearColor(float r, float g, float b, float a); 649 650 sets the clear value for the color buffers in RGBA mode. 651 652 (add to the end of first partial paragraph, p. 217) ... then a 653 Clear directed at that buffer has no effect. Fixed-point RGBA 654 color buffers are cleared to a color values derived by taking the 655 clear color, clamping to [0,1], and converting to fixed-point 656 according to the rules of section 2.14.9. 657 658 Modify Section 4.2.4 (The Accumulation Buffer), p. 217 659 660 (modify second paragraph in section, p. 217) ... Using ACCUM 661 obtains R, G, B, and A components from the color buffer currently 662 selected for reading (section 4.3.2). If the color buffer is 663 fixed-point, each component is considered as a fixed-point value 664 in [0,1] (see section 2.14.9) and is converted to floating-point. 665 Each result is then multiplied ... 666 667 (modify second paragraph on p. 218) The RETURN operation takes 668 each color value from the accumulation buffer and multiplies each 669 of the R, G, B, and A components by <value>. If fragment color 670 clamping is enabled, the results are then clamped to the range 671 [0,1]. ... 672 673 Modify Section 4.3.2 (Reading Pixels), p. 219 674 675 (modify paragraph at top of page, p. 222) ... For a fixed-point 676 color buffer, each element is taken to be a fixed-point value in 677 [0, 1] with m bits, where m is the number of bits in the 678 corresponding color component of the selected buffer (see 679 section 2.14.9). For floating-point color buffer, the elements 680 are unmodified. 681 682 (modify Final Conversion, p. 222) For an index, if the type is not 683 FLOAT or HALF_FLOAT_ARB, final conversion consists of masking the 684 index with the value given in Table 4.6; if the type is FLOAT or 685 HALF_FLOAT_ARB, then the integer index is converted to a GL float 686 or half data value. 687 688 For an RGBA color, if <type> is not FLOAT or HALF, or the selected 689 color buffer is a fixed-point buffer, each component is first 690 clamped to [0,1]. Then the appropriate conversion... 691 692 (modify Table 4.7, p. 224 -- add new row) 693 694 type Parameter GL Data Type Component Conversion Formula 695 -------------- ------------ ---------------------------- 696 HALF_APPLE half c = f 697 698 699 700Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 701 702 None. 703 704Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 705State Requests) 706 707 Modify Section 6.1.2, Data Conversions, p. 245 708 709 (add new paragraph at the end of the section, p. 245) If fragment 710 color clamping is enabled, querying of the texture border color, 711 texture environment color, fog color, alpha test reference value, 712 blend color, and RGBA clear color will clamp the corresponding 713 state values to [0,1] before returning them. This behavior 714 provides compatibility with previous versions of the GL that 715 clamped these values when specified. 716 717 718Modifications to the AGL Specification 719 720 Modify the values accepted by aglChoosePixelFormat and aglDescribePixelFormat. 721 722 AGL_COLOR_FLOAT 723 If true, this pixel format supports using floating point 724 color buffers as the destination for rendering. 725 726Modifications to the CGL Specification 727 728 Modify the values accepted by CGLChoosePixelFormat and CGLDescribePixelFormat. 729 730 kCGLPFAColorFloat 731 If true, this pixel format supports using floating point 732 color buffers as the destination for rendering. 733 734Dependencies on ARB_fragment_program 735 736 (modify 2nd paragraph of Section 3.11.4.4 language) If fragment 737 color clamping is enabled, the fragment's color components are first 738 clamped to the range [0,1] and are optionally converted to fixed 739 point as in section 2.14.9. If the fragment program does not write 740 result.color, the color will be undefined in subsequent stages. 741 742Dependencies on ARB_fragment_shader 743 744 (modify 1st paragraph of Section 3.11.6 language) ... are 745 gl_FragColor and gl_FragDepth. If fragment color clamping is 746 enabled, the final fragment color values written by a fragment 747 shader are clamped to the range [0,1] and are optionally converted 748 to fixed-point as described in section 2.14.9, Final Color 749 Processing. ... 750 751Dependencies on APPLEX_texture_float_16_filter 752 753 If APPLEX_texture_float_16_filter is not supported, then all 754 references to APPLEX_texture_float_16_filter should be removed from 755 this extension. In this case, 16 bit floating point textures will 756 behave as if the GL_MAG_FILTER is GL_NEAREST and as if GL_MIN_FILTER 757 is either GL_NEAREST_MIPMAP_NEAREST (if a mipmap min filter is 758 requested) or GL_NEAREST (if a non-mipmap min filter is requested). 759 760Dependencies on APPLEX_color_buffer_float_16_blend 761 762 If APPLEX_color_buffer_float_16_blend is not supported, then all 763 references to APPLEX_texture_float_16_filter should be removed from 764 this extension. In this case, rendering to a 16 bit floating point 765 color buffer will behave as if the enable state for GL_BLEND is set 766 to FALSE. 767 768Errors 769 770 None. 771 772New State 773 774(table 6.25, p. 215) 775 776 Get value Type Get Cmnd Minimum Value Description Sec. Attribute 777 ----------------- ---- ----------- ------------- --------------------------- ---- --------- 778 COLOR_FLOAT_APPLE B GetBooleanv - True if color buffers store 2.7 - 779 floating point components 780 781Revision History 782 783 784 0.1, 2003, gstahl@apple.com 785 * preliminary draft, documents shipping behavior as of 10.2.3 786 787 0.2, 08/16/2005, jsandmel@apple.com 788 * rewritten to account for the fact that APPLE_float_pixels doesn't support: 789 - float 16/32 texture filtering 790 - float 16/32 color buffer blending 791 - controllable color clamping 792 - texture per-component float-versus-int type queries 793 - half float types with imaging subset routines 794 * added interactions with the shader extensions 795 * added interactions with the APPLEX_*_float_16_* extensions 796 * added updates to AGL and CGL 797 798