Name ARB_depth_texture Name Strings GL_ARB_depth_texture Contact Brian Paul (brian_e_paul 'at' yahoo.com) Notice Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by the ARB on February 14, 2002. Updated version (June 1, 2004) approved by the ARB on June 8, 2004. Version Last Modified Date: November 29, 2004 Number ARB Extension #22 Dependencies OpenGL 1.1 is required. This extension is written against the OpenGL 1.3 Specification. Overview This is a clarification of the GL_SGIX_depth_texture extension. The original overview follows: This extension defines a new depth texture format. An important application of depth texture images is shadow casting, but separating this from the shadow extension allows for the potential use of depth textures in other applications such as image-based rendering or displacement mapping. This extension does not define new depth-texture environment functions, such as filtering or applying the depth values computed from a texture but leaves this to other extensions, such as the shadow extension. IP Status None. Issues (1) How is this extension different from GL_SGIX_depth_texture? This extension defines support for texture border values, querying depth texel resolution, and behavior when a depth texture is bound to a texture unit that's expecting RGBA texels. (2) What about texture borders and the border value? Texture borders are supported. The texture border value used for depth textures is the first component of TEXTURE_BORDER_COLOR. (3) What happens when a depth texture is currently bound but RGBA texels are expected by the texture unit? The depth texture is treated as if it were a LUMINANCE texture. It's sometimes useful to render a depth component texture as a grayscale texture. (4) What happens when an RGBA texture is currently bound but depth texels are expected by the texture unit? We do texturing in the normal way for an RGBA texture. (5) What about 1D, 3D and cube maps textures? Should depth textures be supported? RESOLVED: For 1D textures, yes, for orthogonality. For 3D and cube map textures, no. In both cases, the R coordinate that would be ordinarily be used for a shadow comparison is needed for texture lookup and won't contain a useful value. In theory, the shadow functionality could be extended to provide useful behavior for such targets, but this enhancement is left to a future extension. (6) Why "depth" textures instead of a generic, extended-precision, single-channel texture format? RESOLVED: We need a depth format so that glCopyTex[Sub]Image() can copy data from the depth buffer to the texture memory. (7) Is there any particular reason that depth textures should only be used as LUMINANCE textures? RESOLVED: Add DEPTH_TEXTURE_MODE to allow depth textures to be used as LUMINANCE, INTENSITY or ALPHA textures. (8) It is very unlikely that depth textures when used as LUMINANCE, INTENSITY or ALPHA textures are used at their full storage precision. Should there be a query for the actual number of bits used for depth textures? RESOLVED: No. OpenGL does not have queries for internal precision. Instead of adding it randomly for one feature, it should be looked in the broader context of providing it for more features. (9) How should GetTexImage work for depth textures? RESOLVED: Since GetTexImage is modeled on ReadPixels, reading depth components should require the DEPTH_COMPONENT format. Specifying a color format when querying a texture image with a DEPTH_COMPONENT base internal format should be an invalid operation. Likewise, specifying a DEPTH_COMPONENT format when querying a texture image with a color internal format should be an invalid operation. This is not only consistent with ReadPixels but how the EXT_paletted_texture and NV_texture_shader extensions amend GetTexImage to return non-color texture image data. New Procedures and Functions None New Tokens Accepted by the parameter of TexImage1D, TexImage2D, CopyTexImage1D and CopyTexImage2D: DEPTH_COMPONENT DEPTH_COMPONENT16_ARB 0x81A5 (same as DEPTH_COMPONENT16_SGIX) DEPTH_COMPONENT24_ARB 0x81A6 (same as DEPTH_COMPONENT24_SGIX) DEPTH_COMPONENT32_ARB 0x81A7 (same as DEPTH_COMPONENT32_SGIX) Accepted by the parameter of GetTexImage, TexImage1D, TexImage2D, TexSubImage1D, and TexSubImage2D: DEPTH_COMPONENT Accepted by the parameter of GetTexLevelParameterfv and GetTexLevelParameteriv: TEXTURE_DEPTH_SIZE_ARB 0x884A Accepted by the parameter of TexParameterf, TexParameteri, TexParameterfv, TexParameteriv, GetTexParameterfv, and GetTexParameteriv: DEPTH_TEXTURE_MODE_ARB 0x884B Additions to Chapter 2 of the 1.3 Specification (OpenGL Operation) None Additions to Chapter 3 of the 1.3 Specification (Rasterization) Section 3.8.1, Texture Image Specification, p. 116, change last sentence of first paragraph to: "The format STENCIL_INDEX is not allowed." Section 3.8.1, Texture Image Specification, p. 116, change final paragraph to read: "The selected groups are processed exactly as for DrawPixels, stopping just before final conversion. Each R, G, B, A or depth component (D) value so generated is clamped to [0,1]." Section 3.8.1, Texture Image Specification, p. 117, modify beginning of the first paragraph: "Components are then selected from the resulting R, G, B, A, or D values to obtain a texture with the base internal format specified by..." Section 3.8.1, Texture Image Specification, p. 117, add two new paragraphs after the beginning of the first paragraph: "Textures with a base internal format of DEPTH_COMPONENT are supported by texture image specification commands only if is TEXTURE_1D, TEXTURE_2D, PROXY_TEXTURE_1D or PROXY_TEXTURE_2D. Using this format in conjunction with any other will result in an INVALID_OPERATION error." "Textures with a base internal format of DEPTH_COMPONENT require depth component data; textures with other base internal formats require RGBA component data. The error INVALID_OPERATION is generated if the base internal format is DEPTH_COMPONENT and format is not DEPTH_COMPONENT, or if the base internal format is not DEPTH_COMPONENT and format is DEPTH_COMPONENT." Section 3.8.1, Texture Image Specification, p. 117, modify the last paragraph, which flows to p. 118: "... If a sized internal format is specified, the mapping of the R, G, B, A, and D values to texture components is equivalent to ..." (on p. 118) "... If a compressed internal format is specified, the mapping of the R, G, B, A, and D values to texture components is equivalent to..." Section 3.8.1, Texture Image Specification, p. 118, add a new row to Table 3.15. Base Internal Format RGBA Values Internal Components -------------------- ----------- ------------------- DEPTH_COMPONENT D D Section 3.8.1, Texture Image Specification, p. 118, add three new rows and one new column to Table 3.16. Sized Internal Format Base Int. Format ... D bits --------------------- ---------------- ------ DEPTH_COMPONENT16_ARB DEPTH_COMPONENT 16 DEPTH_COMPONENT24_ARB DEPTH_COMPONENT 24 DEPTH_COMPONENT32_ARB DEPTH_COMPONENT 32 Section 3.8.2, Alternate Texture Image Specification Commands, p. 125, modify first paragraph to read: ... "The image is taken from the framebuffer exactly as if these arguments were passed to CopyPixels, with argument set to COLOR or DEPTH_COMPONENT, depending on , stopping after pixel transfer processing is complete. RGBA data is taken from the current color buffer while depth component data is taken from the depth buffer. If no depth buffer is present, the error INVALID_OPERATION is generated. Subsequent processing is identical to that described for TexImage2D, beginning with clamping of the R, G, B, A, or depth values from the resulting pixel groups." ... Section 3.8.4, Texture Parameters, p. 133, append table 3.19 with the following: Name Type Legal Values -------------------------- ---- ------------------------------- DEPTH_TEXTURE_MODE_ARB enum LUMINANCE, INTENSITY, ALPHA Before current section 3.8.5, Texture Wrap Modes, p. 134, insert the following new section. Renumber subsections of 3.8 appropriately. "3.8.5 Depth Component Textures Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures during texture filtering and application. Initially, depth textures are interpreted as LUMINANCE." Modify section 3.8.7, Texture Minification, p. 139. Modify the last paragraph before the "Mipmapping" section to read: "If any of the selected tauijk, tauij, or taui in the above equations refer to a border texel with i < -bs, j < bs, k < -bs, i >= ws-bs, j >= hs-bs, or k >= ds-bs, then the border values given by the current setting of TEXTURE_BORDER_COLOR is used instead of the unspecified value or values. If the texture contains color components, the components of the TEXTURE_BORDER_COLOR vector are interpreted as an RGBA color to match the texture's internal format in a manner consistent with table 3.15. If the texture contains depth components, the R component of the TEXTURE_BORDER_COLOR vector is interpreted as the depth component value." Additions to Chapter 4 of the 1.3 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the 1.3 Specification (Special Functions) None Additions to Chapter 6 of the 1.3 Specification (State and State Requests) Section 6.1.3, Enumerated Queries, p. 200, edit paragraph two as follows: ..."Queries of TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, TEXTURE_BLUE_SIZE, TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, TEXTURE_INTENSITY_SIZE, and TEXTURE_DEPTH_SIZE_ARB return the actual resolutions of the stored image array components, not the resolutions specified when the image array was defined. Section 6.1.4, Texture Queries, p. 201, replace the sentence two of paragraph two as follows: "Calling GetTexImage with a color format when the internal format of the texture image is not a color format causes the error INVALID_OPERATION. Likewise, calling GetTexImage with a format of DEPTH_COMPONENT when the internal format of the texture image is not a depth format cause the error INVALID_OPERATION. If the internal format of the texture image level is a color format (one of RED, GREEN, BLUE, ALPHA, RGB, BGR, RGBA, BGRA, LUMINANCE, or LUMINANCE_ALPHA), then the components are assigned among R, G, B, and A according to Table 6.1, starting with the first group in the first row, and continuing by obtaining groups in order from each row and proceeding from the first row to the last, and from the first image to the last for three-dimensional textures. If the internal format of the texture image level is a depth format (DEPTH_COMPONENT), then each depth component is assigned with the same ordering of rows and images." Replace the last sentence of paragraph four with: "Calling GetTexImage with format of COLOR_INDEX or STENCIL_INDEX causes the error INVALID_ENUM." Section 1.6.7, Color Table Query, p.203, replace sentence two of paragraph one with: "format and type accept the same values as do the corresponding parameters of GetTexImage except that a format of DEPTH_COMPONENT causes the error INVALID_ENUM." Section 1.6.8, Convolution Query, p.204, replace sentence two of paragraph one with: "format and type accept the same values as do the corresponding parameters of GetTexImage except that a format of DEPTH_COMPONENT causes the error INVALID_ENUM." Replace sentence two of paragraph two (specifying GetSeparableFilter) with: "format and type accept the same values as do the corresponding parameters of GetTexImage except that a format of DEPTH_COMPONENT causes the error INVALID_ENUM." Section 1.6.9, Histogram Query, p.205, replace sentence two of paragraph one with: "format and type accept the same values as do the corresponding parameters of GetTexImage except that a format of DEPTH_COMPONENT causes the error INVALID_ENUM." Section 1.6.10, Minmax Query, p.205, replace sentence two of paragraph one with: "format and type accept the same values as do the corresponding parameters of GetTexImage except that a format of DEPTH_COMPONENT causes the error INVALID_ENUM." Additions to the GLX Specification None Errors INVALID_OPERATION is generated by TexImage2D or CopyTexImage2D if is not TEXTURE_2D or PROXY_TEXTURE_2D and is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by TexImage1D or CopyTexImage1D if is not TEXTURE_1D or PROXY_TEXTURE_1D and is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by TexImage1D or TexImage2D if is DEPTH_COMPONENT and is not DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by TexImage1D or TexImage2D if is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB, and is not DEPTH_COMPONENT. INVALID_OPERATION is generated by TexSubImage1D or TexSubImage2D if is DEPTH_COMPONENT and the base internal format of the texture is not DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by TexSubImage1D or TexSubImage2D if is not DEPTH_COMPONENT and the base internal format of the texture is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by TexImage3D if is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB. INVALID_OPERATION is generated by CopyTexImage1D or CopyTexImage2D if is DEPTH_COMPONENT, DEPTH_COMPONENT16_ARB, DEPTH_COMPONENT24_ARB, or DEPTH_COMPONENT32_ARB, and there is no depth buffer. INVALID_OPERATION is generated by CopyTexSubImage1D or CopyTexSubImage2D if the base internal format of the texture is DEPTH_COMPONENT and there is no depth buffer. INVALID_ENUM is generated if TexParameter[if] parameter is DEPTH_TEXTURE_MODE_ARB and parameter is not ALPHA, LUMINANCE, or INTENSITY. INVALID_OPERATION is generated if GetTexImage parameter is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA, BGR, BGRA, LUMINANCE, or LUMINANCE_ALPHA but the internal format of the texture level image is not a color format. INVALID_OPERATION is generated if GetTexImage parameter is DEPTH_COMPONENT but the internal format of the texture level image is not a depth format. Eliminate the INVALID_ENUM generated if GetTexImage parameter is DEPTH_COMPONENT. (but this should still be an error for GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram, and GetMinmax). New State In table 6.12, Texture Objects, p. 202, add the following: Initial Get Value Type Get Command Value Description Sec. Attribute ------------------ ---- -------------------- ------- ------------------------------------- ---- --------- TEXTURE_DEPTH_SIZE Z+ GetTexLevelParameter 0 xD texture image i's depth resolution 3.8 - In table 6.16, Texture Objects, p. 224, add the following: Get Value Type Get Command Initial Value Description Sec. Attribute -------------------------- ---- -------------------- ------------- -------------- ----- --------- DEPTH_TEXTURE_MODE_ARB Z_3 GetTexParameter[if]v LUMINANCE depth texture mode 3.8.13 texture New Implementation Dependent State None Revision History 19 March 2001 - initial version 22 June 2001 - added 1D textures to issue 4 16 November 2001 - removed TEXTURE_BORDER_DEPTH. use the first component of TEXTURE_BORDER_COLOR to specify the depth border value. - Added new language in section 3.8.5 to describe how TEXTURE_BORDER_COLOR is used with depth textures. - Inserted new issue item #4. 17 November 2001 - Changed issue 4 resolution. - Rewrote section 3.8.4 12 December 2001 (Pat Brown) - Retargeted against the OpenGL 1.3 specification. - Depth textures are allowed only on 1D and 2D targets. Shadowing is problematic for 3D and cube map textures. - Updated base and sized internal format tables. - Documented a couple missing error conditions for TexImage and TexSubImage calls where and the texture internal format are incompatible. - Minor cleanups to provide for depth components in wording that formerly assumed RGBA components only. 13 December 2001 - Removed a few lingering references to glTexImage3D. - Rewrite the first and last error conditions to be clearer. - replace "1.2" with "1.3" in a few places. - fixed a few more error conditions (Pat Brown) 11 January 2002 - fixed "intented" typo - added sentence saying that TEXTURE_LUMINANCE_SIZE may be used to query the effective resolution of a depth textures when it's interpreted as a luminance texture. 18 January 2002 - Allow depth textures to be used as LUMINANCE, INTENSITY or ALPHA textures (Bimal Poddar) 21 January 2002 - Added issue #8 to deal with actual depth texture precision. Fixed error to be INVALID_ENUM instead of INVALID_OPERATION. 13 May 2004 (mjk) - Document GetTexImage behavior when depth texture formats are supported. - Document that GetColorTable, GetConvolutionFilter, GetHistogram, and GetMinmax now differ from GetTexImage in that DEPTH_COMPONENT is (still) not a legal format for these queries. - Document in "New Tokens" that DEPTH_COMPONENT is a newly accepted token for the parameter of TexImage1D, TexImage2D, CopyTexImage1D and CopyTexImage2D; and the parameter of GetTexImage, TexImage1D, TexImage2D, TexSubImage1D, and TexSubImage2D. - Fix mangled sentence in 3.8.5 1 June 2004 (John Rosasco) - Added BGR and BGRA to the list of color internal formats in section 6.1.4. 29 November 2004 (mjk) - Document that GetSeparableFilter now differ from GetTexImage in that DEPTH_COMPONENT is (still) not a legal format for these queries.