1Name 2 3 ARB_depth_buffer_float 4 5Name Strings 6 7 GL_ARB_depth_buffer_float 8 9Contributors 10 11 Pierre Boudier 12 13Contact 14 15 Pierre Boudier, AMD pierre.boudier 'at' amd.com) 16 17Notice 18 19 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Specification Update Policy 23 24 Khronos-approved extension specifications are updated in response to 25 issues and bugs prioritized by the Khronos OpenGL Working Group. For 26 extensions which have been promoted to a core Specification, fixes will 27 first appear in the latest version of that core Specification, and will 28 eventually be backported to the extension document. This policy is 29 described in more detail at 30 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 31 32Status 33 34 Approved by the ARB on July 11, 2008 35 36Version 37 38 Last Modified Date: October 18, 2012 39 Revision: 7 40 41Number 42 43 ARB Extension #43 44 45Dependencies 46 47 OpenGL 2.0 is required. 48 49 ARB_color_buffer_float is required. 50 51 EXT_packed_depth_stencil is required. 52 53 ARB_framebuffer_object is required. 54 55 This extension modifies EXT_depth_bounds_test. 56 57 This extension modifies NV_copy_depth_to_color. 58 59 This extension is written against the OpenGL 2.0 specification. 60 61Overview 62 63 This extension provides new texture internal formats whose depth 64 components are stored as 32-bit floating-point values, rather than the 65 normalized unsigned integers used in existing depth formats. 66 Floating-point depth textures support all the functionality supported for 67 fixed-point depth textures, including shadow mapping and rendering support 68 via EXT_framebuffer_object. Floating-point depth textures can store 69 values outside the range [0,1]. 70 71 Additionally, this extension provides new packed depth/stencil pixel 72 formats (see EXT_packed_depth_stencil) that have 64-bit pixels consisting 73 of a 32-bit floating-point depth value, 8 bits of stencil, and 24 unused 74 bites. A packed depth/stencil texture internal format is also provided. 75 76 This extension does not provide support for WGL or GLX pixel formats with 77 floating-point depth buffers. The existing (but not commonly used) 78 WGL_EXT_depth_float extension could be used for this purpose. 79 80 81New Procedures and Functions 82 83 None 84 85New Tokens 86 87 Accepted by the <internalformat> parameter of TexImage1D, TexImage2D, 88 TexImage3D, CopyTexImage1D, CopyTexImage2D, and RenderbufferStorageEXT, 89 and returned in the <data> parameter of GetTexLevelParameter and 90 GetRenderbufferParameterivEXT: 91 92 DEPTH_COMPONENT32F 0x8CAC 93 DEPTH32F_STENCIL8 0x8CAD 94 95 Accepted by the <type> parameter of DrawPixels, ReadPixels, TexImage1D, 96 TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D, and 97 GetTexImage: 98 99 FLOAT_32_UNSIGNED_INT_24_8_REV 0x8DAD 100 101Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 102 103 Modify Section 2.11.1 (Controling the Viewport), p. 41 104 105 (modify second paragraph) The factor and offset applied to z_d 106 encoded by n and f are set using 107 108 void DepthRange(clampd n, clampd f); 109 110 z_w is represented as either fixed-point or floating-point 111 depending on whether the framebuffer's depth buffer uses 112 fixed-point or floating-point representation. If the depth buffer 113 uses fixed-point representation, we assume that the representation 114 used represents each value k/(2^m - 1), where k is in 115 {0,1,...,2^m-1}, as k (e.g. 1.0 is represented in binary as a 116 string of all ones). The parameters n and f are clamped to [0, 1] 117 when using DepthRange. When n and f are applied to z_d, they are 118 clamped to the range appropriate given the depth buffer's representation. 119 120Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 121 122 Modify Section 3.5.5 (Depth Offset), p. 112 123 124 (modify third paragraph) The minimum resolvable difference r is 125 an implementation dependent parameter that depends on the depth 126 buffer representation. It is the smallest difference in window 127 coordinate z values that is guaranteed to remain distinct 128 throughout polygon rasterization and in the depth buffer. All 129 pairs of fragments generated by the rasterization of two polygons 130 with otherwise identical vertices, but z_w values that differ by r, 131 will have distinct depth values. 132 133 For fixed-point depth buffer representations, r is constant 134 throughout the range of the entire depth buffer. For 135 floating-point depth buffers, there is no single minimum resolvable 136 difference. In this case, the minimum resolvable difference for a 137 given polygon is dependent on the maximum exponent, e, in the range 138 of z values spanned by the primitive. If n is the number of bits 139 in the floating-point mantissa, the minimum resolvable difference, 140 r, for the given primitive is defined as 141 142 r = 2^(e - n). (3.11) 143 144 (modify fourth paragraph) The offset value o for a polygon is 145 146 o = m * factor + r * units. (3.12) 147 148 m is computed as described above. If the depth buffer uses a 149 fixed-point representation, m is a function of depth values in the 150 range [0, 1], and o is applied to depth values in the same range. 151 152 (modify last paragraph) For fixed-point depth buffers, fragment 153 depth values are always limited to the range [0, 1], either by 154 clamping after offset addition is performed (preferred), or by 155 clamping the vertex values used in the rasterization of the 156 polygons. Fragment depth values are clamped when the depth 157 buffer uses a floating-point representation. 158 159 160 Add a row to table 3.5, p. 128 161 162 type Parameter GL Type Special 163 ------------------------------ ------- ------- 164 ... ... ... 165 FLOAT_32_UNSIGNED_INT_24_8_REV N/A Yes 166 ... ... ... 167 168 169 Modify Section 3.6.4 (Rasterization of Pixel Rectangles), p. 128 170 171 (modify second paragraph as updated by EXT_packed_depth_stencil) 172 ... If the GL is in color index mode and <format> is not one of 173 COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL_EXT, 174 then the error INVALID_OPERATION occurs. If <type> is BITMAP and 175 <format> is not COLOR_INDEX or STENCIL_INDEX then the error 176 INVALID_ENUM occurs. If <format> is DEPTH_STENCIL_EXT and <type> 177 is not UNSIGNED_INT_24_8_EXT or FLOAT_32_UNSIGNED_INT_24_8_REV, 178 then the error INVALID_ENUM occurs. Some additional constraints 179 on the combinations of <format> and <type> values that are accepted 180 are discussed below. 181 182 (modify fifth paragraph of "Unpacking," p 130. as updated by 183 EXT_packed_depth_stencil) Calling DrawPixels with a <type> of 184 UNSIGNED_BYTE_3_3_2, ..., UNSIGNED_INT_2_10_10_10_REV, or 185 UNSIGNED_INT_24_8_EXT is a special case in which all the components 186 of each group are packed into a single unsigned byte, unsigned 187 short, or unsigned int, depending on the type. If <type> is 188 FLOAT_32_UNSIGNED_INT_24_8_REV, the components of each group 189 are two 32-bit words. The first word contains the float component. 190 The second word contains packed 24-bit and 8-bit components. 191 192 193 Add two rows to table 3.8, p. 132 194 195 type Parameter GL Type Components Pixel Formats 196 ------------------------------ ------- ---------- ------------- 197 ... ... ... ... 198 FLOAT_32_UNSIGNED_INT_24_8_REV N/A 2 DEPTH_STENCIL_EXT 199 ... ... ... ... 200 201 202 Add a row to table 3.11, p. 134 203 204 FLOAT_32_UNSIGNED_INT_24_8_REV: 205 206 31 30 29 28 ... 4 3 2 1 0 31 30 29 ... 9 8 7 6 5 ... 2 1 0 207 +-------------------------+ +--------------------------------+ 208 | Float Component | | 2nd Component | 1st Component | 209 +-------------------------+ +--------------------------------+ 210 211 212 (modify last paragraph of "Final Conversion," p. 136) For a depth 213 component, an element is processed according to the depth buffer's 214 representation. For fixed-point depth buffers, the element is first 215 clamped to [0, 1] and then converted to fixed-point as if it were a 216 window z value (see section 2.11.1, Controling the Viewport). 217 Conversion is not necessary when the depth buffer uses 218 a floating-point representation, but clamping is. 219 220 221 Modify Section 3.8.1 (Texture Image Specification), p. 150 222 223 (modify the second paragraph, p. 151, as modified by 224 ARB_color_buffer_float) The selected groups are processed exactly 225 as for DrawPixels, stopping just before final conversion. Each R, 226 G, B, A, or depth value so generated is clamped based on the 227 component type in the <internalFormat>. Fixed-point and Floating-point 228 components are clamped to [0, 1]. 229 32-bit floating-point components are in the standard IEEE float format. 230 16-bit floating-point components have 1 sign bit, 5 exponent bits, 231 and 10 mantissa bits. Stencil index values are masked by 2^n-1 232 where n is the number of stencil bits in the internal format 233 resolution (see below). If the base internal format is 234 DEPTH_STENCIL_EXT and <format> is not DEPTH_STENCIL_EXT, then the 235 values of the stencil index texture components are undefined. 236 237 238 Add two rows to table 3.16, p. 154 239 240 Sized Base R G B A L I D S 241 Internal Format InternalFormat bits bits bits bits bits bits bits bits 242 ------------------ ----------------- ---- ---- ---- ---- ---- ---- ---- ---- 243 ... ... ... ... ... ... ... ... ... ... 244 DEPTH_COMPONENT32F DEPTH_COMPONENT f32 245 DEPTH32F_STENCIL8 DEPTH_STENCIL_EXT f32 8 246 ... ... ... ... ... ... ... ... ... ... 247 248 249 Modify Section 3.8.14 (Texture Comparison Modes), p. 185 250 251 (modify second paragraph of "Depth Texture Comparison Mode," p. 252 188) 253 254 Let D_t be the depth texture value, and R be the interpolated 255 texture coordinate. If the texture's internal format indicates a 256 fixed-point depth texture, then D_t and R are clamped to [0, 1]; 257 otherwise no clamping is performed. The effective texture value L_t, 258 I_t, or A_t is computed as follows: 259 260 261 Modify Section 3.11.2 (Shader Execution), p. 194 262 263 (modify first paragraph of "Shader Outputs," p, 196, as modified by 264 ARB_color_buffer_float) The OpenGL Shading Language specification 265 describes the values that may be output by a fragment shader. 266 These are gl_FragColor, gl_FragData[n], and gl_FragDepth. If 267 fragment clamping is enabled, the final fragment color values or 268 the final fragment data values written by a fragment shader are 269 clamped to the range [0, 1] and then may be converted to 270 fixed-point as described in section 2.14.9. If fragment clamping 271 is disabled, the final fragment color values or the final fragment 272 data values are not modified. For fixed-point depth buffers the 273 final fragment depth written by a fragment shader is first clamped 274 to [0, 1] and then converted to fixed-point as if it were a window 275 z value (see section 2.11.1). Conversion is not applied for floating-point 276 depth buffers. Note that the depth range computation is not applied here. 277 278 279Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 280Operations and the Frame Buffer) 281 282 283 (modify third paragraph in the introduction, p. 198, as modified by 284 ARB_color_buffer_float) Color buffers consist of either unsigned 285 integer color indices, R, G, B and optionally A unsigned integer 286 values, or R, G, B, and optionally A floating-point values. Depth 287 buffers consist of either unsigned integer values of the format 288 described in section 2.11.1, or floating-point values. The number 289 of bitplanes... 290 291 292 Modify Section 4.2.3 (Clearing the Buffers), p. 215 293 294 (modify fourth paragraph) 295 296 The functions 297 298 void ClearDepth(clampd d); 299 300 are used to set the depth value used when clearing the depth buffer. 301 ClearDepth takes a floating-point value that is clamped to the range 302 [0, 1]. When clearing a fixed-point depth buffer, the depth clear 303 value is clamped to the range [0, 1], and converted to fixed-point 304 according to the rules for a window z value given in section 2.11.1. 305 No conversion are applied when clearing a floating-point 306 depth buffer. 307 308 Modify Section 4.3.1 (Writing to the Stencil Buffer), p. 218 309 310 (modify paragraph added by EXT_packed_depth_stencil, p. 219) 311 If the <format> is DEPTH_STENCIL_EXT, then values are taken from 312 both the depth buffer and the stencil buffer. If there is no depth 313 buffer or if there is no stencil buffer, then the error 314 INVALID_OPERATION occurs. If the <type> parameter is not 315 UNSIGNED_INT_24_8_EXT, or FLOAT_32_UNSIGNED_INT_24_8_REV then 316 the error INVALID_ENUM occurs. 317 318 319 Modify Section 4.3.2 (Reading Pixels), p. 219 320 321 (modify "Conversion of Depth values," p. 222, as modified by 322 EXT_packed_depth_stencil) This step only applies if <format> is 323 DEPTH_COMPONENT or DEPTH_STENCIL_EXT and the depth buffer uses a 324 fixed-point representation. An element taken from the depth buffer 325 is taken to be a fixed-point value in [0, 1] with m bits, where 326 m is the number of bits in the depth buffer (see section 2.11.1). 327 No conversion is necessary if <format> is DEPTH_COMPONENT or 328 DEPTH_STENCIL_EXT and the depth buffer uses a floating-point 329 representation. 330 331 332 Add a row to table 4.6, p. 223 333 334 type Parameter Index Mask 335 ------------------------------ ---------- 336 ... ... 337 FLOAT_32_UNSIGNED_INT_24_8_REV 2^8-1 338 339 340 Add a row to table 4.7, p. 224 341 342 type Parameter GL Type Component Conversion 343 ------------------------------ ------- -------------------- 344 ... ... ... 345 FLOAT_32_UNSIGNED_INT_24_8_REV float c = f (depth only) 346 347 348Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 349 350 None. 351 352 353Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 354State Requests) 355 356 Modify DEPTH_RANGE entry in table 6.9 (Transformation State) p. 270 357 358 Init 359 Get Value Type Get Command Value Description Sec. Attribute 360 ----------- ---- ----------- ----- ---------------------- ------ --------- 361 DEPTH_RANGE 2xR GetFloatv 0,1 Depth range near & far 2.11.1 viewport 362 363 364 Modify DEPTH_BOUNDS_EXT entry in table 6.19 (Pixel Operation) p. 280 365 366 Init 367 Get Value Type Get Command Value Description Sec Attribute 368 --------------------- ----------- ----- ------------------------ ----- ------------ 369 DEPTH_BOUNDS_EXT 2xR GetFloatv 0,1 Depth bounds zmin & zmax 4.1.X depth-buffer 370 371 372 Modify DEPTH_CLEAR_VALUE entry in table 6.21 (Framebuffer Control) p. 280 373 374 Init 375 Get Value Type Get Command Value Description Sec Attribute 376 ----------------- ---- ----------- ---- ------------------------ ----- ------------ 377 DEPTH_CLEAR_VALUE R GetFloatv 1 Depth buffer clear value 4.2.3 depth-buffer 378 379 380Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 381 382 None. 383 384Additions to the AGL/GLX/WGL Specifications 385 386 None. 387 388GLX Protocol 389 390 None. 391 392Dependencies on EXT_depth_bounds_test: 393 394 Modify the definition of DepthBoundsEXT in section 4.1.x Depth 395 Bounds Test. 396 397 Modify section 4.1.x (Depth Bounds Test) 398 399 (modify first paragraph) ...These values are set with 400 401 void DepthBoundsEXT(clampd zmin, clampd zmax); 402 403 The paramerters to DepthBoundsEXT are clamped to the range [0, 1]. 404 Each of zmin and zmax are subject to clamping to the range of the depth 405 buffer at the time the depth bounds test is applied. For 406 fixed-point depth buffers, the applied zmin and zmax are clamped to 407 [0, 1]. For floating-point depth buffers, the applied zmin and 408 zmax are clamped to [0, 1]. If zmin <= Zpixel <= zmax, then the depth 409 bounds test passes. Otherwise, the test fails and the fragment is 410 discarded. The test is enabled or disabled using Enable or Disable 411 using the constant DEPTH_BOUNDS_TEST_EXT. When disabled, it is as 412 if the depth bounds test always passes. If zmin is greater than 413 zmax, then the error INVALID_VALUE is generated. The state 414 required consists of two floating-point values and a bit indicating 415 whether the test is enabled or disabled. In the initial state, 416 zmin and zmax are set to 0.0 and 1.0 respectively; and the depth 417 bounds test is disabled. 418 419Errors 420 421 Modify the following error in the EXT_packed_depth_stencil 422 specification by adding mention of 423 FLOAT_32_UNSIGNED_INT_24_8_REV: 424 425 The error INVALID_ENUM is generated if DrawPixels or ReadPixels is 426 called where format is DEPTH_STENCIL_EXT and type is not 427 UNSIGNED_INT_24_8_EXT, or FLOAT_32_UNSIGNED_INT_24_8_REV. 428 429 430 Modify the following error in the EXT_packed_depth_stencil 431 specification by adding mention of 432 FLOAT_32_UNSIGNED_INT_24_8_REV: 433 434 The error INVALID_OPERATION is generated if DrawPixels or 435 ReadPixels is called where type is UNSIGNED_INT_24_8_EXT, 436 or FLOAT_32_UNSIGNED_INT_24_8_REV and format is not 437 DEPTH_STENCIL_EXT. 438 439 440 Add the following error to the NV_copy_depth_to_color 441 specification: 442 443 The error INVALID_OPERATION is generated if CopyPixels is called 444 where type is DEPTH_STENCIL_TO_RGBA_EXT or DEPTH_STENCL_TO_BGRA_EXT 445 and the depth buffer uses a floating point representation. 446 447New State 448 449 None. 450 451Issues 452 453 1. Should this extension expose floating-point depth buffers through 454 WGL/GLX "pixel formats?" 455 456 RESOLVED: No. The WGL_EXT_depth_float extension already provides a 457 mechanism for requesting a floating-point depth buffer. 458 459 2. How does an application access the full range of a floating-point 460 depth buffer? 461 462 RESOLVED: This will be a different extension 463 464 3. Should we add a new state query to determine if the depth buffer is 465 using a floating-point representation? 466 467 RESOLVED: No. The old EXT version of this extension had 468 DEPTH_BUFFER_FLOAT_MODE_EXT boolean state to see if the depth 469 buffer is using a floating-point representation, but in this ARB 470 extension we rely on the GetFramebufferAttachmentiv query 471 FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE query introduced with 472 ARB_framebuffer_object and OpenGL 3.0. 473 474 475 4. How does polygon offset work with floating-point depth buffers? 476 477 RESOLVED: The third paragraph of section 3.5.5 (Depth Offset) 478 describes the minimum resolvable difference r as "the smallest 479 difference in window coordinate z values that is guaranteed to remain 480 distinct throughout polygon rasterization and in the depth buffer." 481 The polygon offset value o is computed as a function of r. The 482 minimum resolvable difference r makes sense for fixed-point depth 483 values, and even floating-point depth values in the range [-1, 1]. 484 For unclamped floating-point depth values, there is no constant 485 minimum resolvable difference -- the minimum difference necessary to 486 change the mantissa of a floating-point value by one bit depends on 487 the exponent of the value being offset. To remedy this problem, the 488 minimum resolvable difference is defined to be relative to the range 489 of depth values for the given primitive when the depth buffer is 490 floating-point. 491 492 5. How does NV_copy_depth_to_color work with floating-point depth values? 493 494 RESOLVED: It isn't clear that there is any usefulness to copying the 495 data for 32-bit floating-point depth values to a fixed-point color 496 buffer. It is even less clear how copying packed data from a 497 FLOAT_32_UNSIGNED_24_8_REV depth/stencil buffer to a fixed-point color 498 buffer would be useful or even how it should be implemented. An error 499 should be generated if CopyPixels is called where <type> is 500 DEPTH_STENCIL_TO_RGBA_EXT or DEPTH_STENCIL_TO_BGRA and the depth buffer 501 uses a floating-point representation. 502 503 6. Other OpenGL hardware implementations may be capable of supporting 504 floating-point depth buffers. Why is this an NV extension? 505 506 RESOLVED: When rendering to floating-point depth buffers, we expect 507 that other implementations may only be capable of supporting Z values 508 in the range [0,1]. For such implementations, floating-point Z 509 buffers do not improve the range of Z values supported, but do offer 510 increased precision than conventional 24-bit fixed-point Z buffers, 511 particularly around zero. 512 513 This extension was initially proposed as an EXT, but we have changed 514 it to an NV extension in the expectation that an EXT may be offered at 515 some point in the not-too-distant future. We expect that the EXT 516 could be supported by a larger range of vendors. NVIDIA would 517 continue to support both extensions, where the NV extension could be 518 thought of as taking the capability of the EXT version and extending 519 it to support Z values outside the range [0,1]. 520 521 7. Why don't the new tokens and entry points in this extension have 522 "ARB" suffixes like other ARB extensions? 523 524 RESOLVED: Unlike most ARB extensions, this is a strict subset of 525 functionality already approved in OpenGL 3.0. This extension 526 exists only to support that functionality on older hardware that 527 cannot implement a full OpenGL 3.0 driver. Since there are no 528 possible behavior changes between the ARB extension and core 529 features, source code compatibility is improved by not using 530 suffixes on the extension. 531 532Revision History 533 534 Rev. Date Author Changes 535 ---- -------- -------- ----------------------------------------- 536 7 10/18/12 Jon Leech Restrict [0,1] clamp of D_t and R to 537 only occur for fixed-point depth textures, 538 matching actual driver behavior and the 539 original intent of NV_depth_buffer_float 540 (Bug 7975). 541 542 6 08/08/08 Jon Leech Remove DEPTH_BUFFER_FLOAT_MODE query, 543 update issue 3 accordingly, and 544 change dependency from EXT to 545 ARB_framebuffer_object / GL 3.0. 546 547 5 08/07/08 Jon Leech Remove ARB suffixes. 548 549 4 08/06/08 Jon Leech Fix missing _REV in some token names. 550 551 3 07/11/08 Jon Leech Change NV enum values due to incompatible 552 clamping behavior. 553 554 2 06/30/08 jsandmel Trivial conversion to ARB_depth_buffer_float 555 556 1 06/05/08 pboudier Forked from NV_depth_buffer_float. Restore 557 clamping to [0,1] and remove 'd' entry 558 points. Change suffix from NV to EXT. 559