1Name 2 3 ARB_depth_texture 4 5Name Strings 6 7 GL_ARB_depth_texture 8 9Contact 10 11 Brian Paul (brian_e_paul 'at' yahoo.com) 12 13Notice 14 15 Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Complete. 31 Approved by the ARB on February 14, 2002. 32 Updated version (June 1, 2004) approved by the ARB on June 8, 2004. 33 34Version 35 36 Last Modified Date: November 29, 2004 37 38Number 39 40 ARB Extension #22 41 42Dependencies 43 44 OpenGL 1.1 is required. 45 This extension is written against the OpenGL 1.3 Specification. 46 47Overview 48 49 This is a clarification of the GL_SGIX_depth_texture extension. The 50 original overview follows: 51 52 This extension defines a new depth texture format. An important 53 application of depth texture images is shadow casting, but separating 54 this from the shadow extension allows for the potential use of depth 55 textures in other applications such as image-based rendering or 56 displacement mapping. This extension does not define new depth-texture 57 environment functions, such as filtering or applying the depth values 58 computed from a texture but leaves this to other extensions, such as 59 the shadow extension. 60 61IP Status 62 63 None. 64 65Issues 66 67 (1) How is this extension different from GL_SGIX_depth_texture? 68 69 This extension defines support for texture border values, querying 70 depth texel resolution, and behavior when a depth texture is bound 71 to a texture unit that's expecting RGBA texels. 72 73 (2) What about texture borders and the border value? 74 75 Texture borders are supported. The texture border value used for 76 depth textures is the first component of TEXTURE_BORDER_COLOR. 77 78 (3) What happens when a depth texture is currently bound but RGBA 79 texels are expected by the texture unit? 80 81 The depth texture is treated as if it were a LUMINANCE texture. 82 It's sometimes useful to render a depth component texture as a 83 grayscale texture. 84 85 (4) What happens when an RGBA texture is currently bound but depth 86 texels are expected by the texture unit? 87 88 We do texturing in the normal way for an RGBA texture. 89 90 (5) What about 1D, 3D and cube maps textures? Should depth textures 91 be supported? 92 93 RESOLVED: For 1D textures, yes, for orthogonality. For 3D and cube map 94 textures, no. In both cases, the R coordinate that would be ordinarily 95 be used for a shadow comparison is needed for texture lookup and won't 96 contain a useful value. In theory, the shadow functionality could be 97 extended to provide useful behavior for such targets, but this 98 enhancement is left to a future extension. 99 100 (6) Why "depth" textures instead of a generic, extended-precision, 101 single-channel texture format? 102 103 RESOLVED: We need a depth format so that glCopyTex[Sub]Image() 104 can copy data from the depth buffer to the texture memory. 105 106 (7) Is there any particular reason that depth textures should only be 107 used as LUMINANCE textures? 108 109 RESOLVED: Add DEPTH_TEXTURE_MODE to allow depth textures to be used 110 as LUMINANCE, INTENSITY or ALPHA textures. 111 112 (8) It is very unlikely that depth textures when used as LUMINANCE, 113 INTENSITY or ALPHA textures are used at their full storage precision. 114 Should there be a query for the actual number of bits used for 115 depth textures? 116 117 RESOLVED: No. OpenGL does not have queries for internal precision. 118 Instead of adding it randomly for one feature, it should be looked 119 in the broader context of providing it for more features. 120 121 (9) How should GetTexImage work for depth textures? 122 123 RESOLVED: Since GetTexImage is modeled on ReadPixels, reading depth 124 components should require the DEPTH_COMPONENT format. Specifying a 125 color format when querying a texture image with a DEPTH_COMPONENT 126 base internal format should be an invalid operation. Likewise, 127 specifying a DEPTH_COMPONENT format when querying a texture image 128 with a color internal format should be an invalid operation. 129 This is not only consistent with ReadPixels but how the 130 EXT_paletted_texture and NV_texture_shader extensions amend 131 GetTexImage to return non-color texture image data. 132 133New Procedures and Functions 134 135 None 136 137New Tokens 138 139 Accepted by the <internalFormat> parameter of TexImage1D, TexImage2D, 140 CopyTexImage1D and CopyTexImage2D: 141 142 DEPTH_COMPONENT 143 DEPTH_COMPONENT16_ARB 0x81A5 (same as DEPTH_COMPONENT16_SGIX) 144 DEPTH_COMPONENT24_ARB 0x81A6 (same as DEPTH_COMPONENT24_SGIX) 145 DEPTH_COMPONENT32_ARB 0x81A7 (same as DEPTH_COMPONENT32_SGIX) 146 147 Accepted by the <format> parameter of GetTexImage, TexImage1D, 148 TexImage2D, TexSubImage1D, and TexSubImage2D: 149 150 DEPTH_COMPONENT 151 152 Accepted by the <pname> parameter of GetTexLevelParameterfv and 153 GetTexLevelParameteriv: 154 155 TEXTURE_DEPTH_SIZE_ARB 0x884A 156 157 Accepted by the <pname> parameter of TexParameterf, TexParameteri, 158 TexParameterfv, TexParameteriv, GetTexParameterfv, and GetTexParameteriv: 159 160 DEPTH_TEXTURE_MODE_ARB 0x884B 161 162Additions to Chapter 2 of the 1.3 Specification (OpenGL Operation) 163 164 None 165 166Additions to Chapter 3 of the 1.3 Specification (Rasterization) 167 168 Section 3.8.1, Texture Image Specification, p. 116, change last 169 sentence of first paragraph to: 170 171 "The format STENCIL_INDEX is not allowed." 172 173 Section 3.8.1, Texture Image Specification, p. 116, change final 174 paragraph to read: 175 176 "The selected groups are processed exactly as for DrawPixels, stopping 177 just before final conversion. Each R, G, B, A or depth component (D) 178 value so generated is clamped to [0,1]." 179 180 Section 3.8.1, Texture Image Specification, p. 117, modify beginning of 181 the first paragraph: 182 183 "Components are then selected from the resulting R, G, B, A, or D 184 values to obtain a texture with the base internal format specified 185 by..." 186 187 Section 3.8.1, Texture Image Specification, p. 117, add two new paragraphs 188 after the beginning of the first paragraph: 189 190 "Textures with a base internal format of DEPTH_COMPONENT are supported 191 by texture image specification commands only if <target> is TEXTURE_1D, 192 TEXTURE_2D, PROXY_TEXTURE_1D or PROXY_TEXTURE_2D. Using this format in 193 conjunction with any other <target> will result in an INVALID_OPERATION 194 error." 195 196 "Textures with a base internal format of DEPTH_COMPONENT require depth 197 component data; textures with other base internal formats require RGBA 198 component data. The error INVALID_OPERATION is generated if the base 199 internal format is DEPTH_COMPONENT and format is not DEPTH_COMPONENT, 200 or if the base internal format is not DEPTH_COMPONENT and format is 201 DEPTH_COMPONENT." 202 203 Section 3.8.1, Texture Image Specification, p. 117, modify the last 204 paragraph, which flows to p. 118: 205 206 "... If a sized internal format is specified, the mapping of the R, G, 207 B, A, and D values to texture components is equivalent to ..." 208 209 (on p. 118) "... If a compressed internal format is specified, the 210 mapping of the R, G, B, A, and D values to texture components is 211 equivalent to..." 212 213 Section 3.8.1, Texture Image Specification, p. 118, add a new row to Table 214 3.15. 215 216 Base Internal Format RGBA Values Internal Components 217 -------------------- ----------- ------------------- 218 DEPTH_COMPONENT D D 219 220 Section 3.8.1, Texture Image Specification, p. 118, add three new rows and 221 one new column to Table 3.16. 222 223 Sized Internal Format Base Int. Format ... D bits 224 --------------------- ---------------- ------ 225 DEPTH_COMPONENT16_ARB DEPTH_COMPONENT 16 226 DEPTH_COMPONENT24_ARB DEPTH_COMPONENT 24 227 DEPTH_COMPONENT32_ARB DEPTH_COMPONENT 32 228 229 Section 3.8.2, Alternate Texture Image Specification Commands, p. 125, 230 modify first paragraph to read: 231 232 ... "The image is taken from the framebuffer exactly as if these 233 arguments were passed to CopyPixels, with argument <type> set to 234 COLOR or DEPTH_COMPONENT, depending on <internalformat>, stopping 235 after pixel transfer processing is complete. RGBA data is taken 236 from the current color buffer while depth component data is taken 237 from the depth buffer. If no depth buffer is present, the error 238 INVALID_OPERATION is generated. Subsequent processing is identical 239 to that described for TexImage2D, beginning with clamping of the R, 240 G, B, A, or depth values from the resulting pixel groups." ... 241 242 Section 3.8.4, Texture Parameters, p. 133, append table 3.19 with the 243 following: 244 245 Name Type Legal Values 246 -------------------------- ---- ------------------------------- 247 DEPTH_TEXTURE_MODE_ARB enum LUMINANCE, INTENSITY, ALPHA 248 249 Before current section 3.8.5, Texture Wrap Modes, p. 134, insert the 250 following new section. Renumber subsections of 3.8 appropriately. 251 252 "3.8.5 Depth Component Textures 253 254 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA 255 textures during texture filtering and application. Initially, 256 depth textures are interpreted as LUMINANCE." 257 258 Modify section 3.8.7, Texture Minification, p. 139. Modify the last 259 paragraph before the "Mipmapping" section to read: 260 261 "If any of the selected tauijk, tauij, or taui in the above 262 equations refer to a border texel with i < -bs, j < bs, k < -bs, 263 i >= ws-bs, j >= hs-bs, or k >= ds-bs, then the border values 264 given by the current setting of TEXTURE_BORDER_COLOR is used 265 instead of the unspecified value or values. If the texture 266 contains color components, the components of the 267 TEXTURE_BORDER_COLOR vector are interpreted as an RGBA color 268 to match the texture's internal format in a manner consistent 269 with table 3.15. If the texture contains depth components, 270 the R component of the TEXTURE_BORDER_COLOR vector is 271 interpreted as the depth component value." 272 273Additions to Chapter 4 of the 1.3 Specification (Per-Fragment Operations 274and the Frame Buffer) 275 276 None 277 278Additions to Chapter 5 of the 1.3 Specification (Special Functions) 279 280 None 281 282Additions to Chapter 6 of the 1.3 Specification (State and State Requests) 283 284 Section 6.1.3, Enumerated Queries, p. 200, edit paragraph two as follows: 285 286 ..."Queries of TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, 287 TEXTURE_BLUE_SIZE, TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, 288 TEXTURE_INTENSITY_SIZE, and TEXTURE_DEPTH_SIZE_ARB return the 289 actual resolutions of the stored image array components, not 290 the resolutions specified when the image array was defined. 291 292 Section 6.1.4, Texture Queries, p. 201, replace the sentence two of 293 paragraph two as follows: 294 295 "Calling GetTexImage with a color format when the internal 296 format of the texture image is not a color format causes the error 297 INVALID_OPERATION. Likewise, calling GetTexImage with a format 298 of DEPTH_COMPONENT when the internal format of the texture 299 image is not a depth format cause the error INVALID_OPERATION. 300 If the internal format of the texture image level is a color 301 format (one of RED, GREEN, BLUE, ALPHA, RGB, BGR, RGBA, BGRA, 302 LUMINANCE, or LUMINANCE_ALPHA), then the components are assigned 303 among R, G, B, and A according to Table 6.1, starting with the 304 first group in the first row, and continuing by obtaining groups 305 in order from each row and proceeding from the first row to the 306 last, and from the first image to the last for three-dimensional 307 textures. If the internal format of the texture image level is a 308 depth format (DEPTH_COMPONENT), then each depth component is 309 assigned with the same ordering of rows and images." 310 311 Replace the last sentence of paragraph four with: 312 313 "Calling GetTexImage with format of COLOR_INDEX or STENCIL_INDEX 314 causes the error INVALID_ENUM." 315 316 Section 1.6.7, Color Table Query, p.203, replace sentence two of 317 paragraph one with: 318 319 "format and type accept the same values as do the corresponding 320 parameters of GetTexImage except that a format of DEPTH_COMPONENT 321 causes the error INVALID_ENUM." 322 323 Section 1.6.8, Convolution Query, p.204, replace sentence two of 324 paragraph one with: 325 326 "format and type accept the same values as do the corresponding 327 parameters of GetTexImage except that a format of DEPTH_COMPONENT 328 causes the error INVALID_ENUM." 329 330 Replace sentence two of paragraph two (specifying GetSeparableFilter) 331 with: 332 333 "format and type accept the same values as do the corresponding 334 parameters of GetTexImage except that a format of DEPTH_COMPONENT 335 causes the error INVALID_ENUM." 336 337 Section 1.6.9, Histogram Query, p.205, replace sentence two of 338 paragraph one with: 339 340 "format and type accept the same values as do the corresponding 341 parameters of GetTexImage except that a format of DEPTH_COMPONENT 342 causes the error INVALID_ENUM." 343 344 Section 1.6.10, Minmax Query, p.205, replace sentence two of 345 paragraph one with: 346 347 "format and type accept the same values as do the corresponding 348 parameters of GetTexImage except that a format of DEPTH_COMPONENT 349 causes the error INVALID_ENUM." 350 351Additions to the GLX Specification 352 353 None 354 355Errors 356 357 INVALID_OPERATION is generated by TexImage2D or CopyTexImage2D if 358 <target> is not TEXTURE_2D or PROXY_TEXTURE_2D and <internalFormat> 359 is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or 360 DEPTH_COMPONENT32_ARB. 361 362 INVALID_OPERATION is generated by TexImage1D or CopyTexImage1D if 363 <target> is not TEXTURE_1D or PROXY_TEXTURE_1D and <internalFormat> 364 is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or 365 DEPTH_COMPONENT32_ARB. 366 367 INVALID_OPERATION is generated by TexImage1D or TexImage2D if <format> 368 is DEPTH_COMPONENT and <internalFormat> is not DEPTH_COMPONENT, 369 DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. 370 371 INVALID_OPERATION is generated by TexImage1D or TexImage2D if 372 <internalFormat> is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, 373 DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB, and <format> is not 374 DEPTH_COMPONENT. 375 376 INVALID_OPERATION is generated by TexSubImage1D or TexSubImage2D if 377 <format> is DEPTH_COMPONENT and the base internal format of the 378 texture is not DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, 379 DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. 380 381 INVALID_OPERATION is generated by TexSubImage1D or TexSubImage2D if 382 <format> is not DEPTH_COMPONENT and the base internal format of 383 the texture is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, 384 DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. 385 386 INVALID_OPERATION is generated by TexImage3D if <internalFormat> 387 is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, 388 or DEPTH_COMPONENT32_ARB. 389 390 INVALID_OPERATION is generated by CopyTexImage1D or CopyTexImage2D if 391 <internalFormat> is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, 392 DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB, and there is no depth 393 buffer. 394 395 INVALID_OPERATION is generated by CopyTexSubImage1D or CopyTexSubImage2D 396 if the base internal format of the texture is DEPTH_COMPONENT and there 397 is no depth buffer. 398 399 INVALID_ENUM is generated if TexParameter[if] parameter <pname> 400 is DEPTH_TEXTURE_MODE_ARB and parameter <param> is not ALPHA, 401 LUMINANCE, or INTENSITY. 402 403 INVALID_OPERATION is generated if GetTexImage parameter <format> 404 is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA, BGR, BGRA, LUMINANCE, 405 or LUMINANCE_ALPHA but the internal format of the texture level 406 image is not a color format. 407 408 INVALID_OPERATION is generated if GetTexImage parameter <format> 409 is DEPTH_COMPONENT but the internal format of the texture level 410 image is not a depth format. 411 412 Eliminate the INVALID_ENUM generated if GetTexImage parameter 413 <format> is DEPTH_COMPONENT. (but this should still be an error for 414 GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram, 415 and GetMinmax). 416 417New State 418 419 In table 6.12, Texture Objects, p. 202, add the following: 420 421 Initial 422 Get Value Type Get Command Value Description Sec. Attribute 423 ------------------ ---- -------------------- ------- ------------------------------------- ---- --------- 424 TEXTURE_DEPTH_SIZE Z+ GetTexLevelParameter 0 xD texture image i's depth resolution 3.8 - 425 426 In table 6.16, Texture Objects, p. 224, add the following: 427 428 Get Value Type Get Command Initial Value Description Sec. Attribute 429 -------------------------- ---- -------------------- ------------- -------------- ----- --------- 430 DEPTH_TEXTURE_MODE_ARB Z_3 GetTexParameter[if]v LUMINANCE depth texture mode 3.8.13 texture 431 432 433 434New Implementation Dependent State 435 436 None 437 438Revision History 439 440 19 March 2001 441 - initial version 442 22 June 2001 443 - added 1D textures to issue 4 444 16 November 2001 445 - removed TEXTURE_BORDER_DEPTH. use the first component of 446 TEXTURE_BORDER_COLOR to specify the depth border value. 447 - Added new language in section 3.8.5 to describe how 448 TEXTURE_BORDER_COLOR is used with depth textures. 449 - Inserted new issue item #4. 450 17 November 2001 451 - Changed issue 4 resolution. 452 - Rewrote section 3.8.4 453 12 December 2001 (Pat Brown) 454 - Retargeted against the OpenGL 1.3 specification. 455 - Depth textures are allowed only on 1D and 2D targets. Shadowing is 456 problematic for 3D and cube map textures. 457 - Updated base and sized internal format tables. 458 - Documented a couple missing error conditions for TexImage and 459 TexSubImage calls where <format> and the texture internal format are 460 incompatible. 461 - Minor cleanups to provide for depth components in wording that 462 formerly assumed RGBA components only. 463 13 December 2001 464 - Removed a few lingering references to glTexImage3D. 465 - Rewrite the first and last error conditions to be clearer. 466 - replace "1.2" with "1.3" in a few places. 467 - fixed a few more error conditions (Pat Brown) 468 11 January 2002 469 - fixed "intented" typo 470 - added sentence saying that TEXTURE_LUMINANCE_SIZE may be used 471 to query the effective resolution of a depth textures when it's 472 interpreted as a luminance texture. 473 18 January 2002 474 - Allow depth textures to be used as LUMINANCE, INTENSITY or ALPHA 475 textures (Bimal Poddar) 476 21 January 2002 477 - Added issue #8 to deal with actual depth texture precision. 478 Fixed error to be INVALID_ENUM instead of INVALID_OPERATION. 479 13 May 2004 (mjk) 480 - Document GetTexImage behavior when depth texture formats are 481 supported. 482 - Document that GetColorTable, GetConvolutionFilter, GetHistogram, 483 and GetMinmax now differ from GetTexImage in that 484 DEPTH_COMPONENT is (still) not a legal format for these 485 queries. 486 - Document in "New Tokens" that DEPTH_COMPONENT is a newly accepted 487 token for the <internalFormat> parameter of TexImage1D, 488 TexImage2D, CopyTexImage1D and CopyTexImage2D; and the <format> 489 parameter of GetTexImage, TexImage1D, TexImage2D, TexSubImage1D, 490 and TexSubImage2D. 491 - Fix mangled sentence in 3.8.5 492 1 June 2004 (John Rosasco) 493 - Added BGR and BGRA to the list of color internal formats in 494 section 6.1.4. 495 29 November 2004 (mjk) 496 - Document that GetSeparableFilter now differ from GetTexImage 497 in that DEPTH_COMPONENT is (still) not a legal format for 498 these queries. 499