Name OES_packed_depth_stencil Name Strings GL_OES_packed_depth_stencil Contributors Maurice Ribble Contributors to EXT_packed_depth_stencil Contact Benj Lipchak, Apple (lipchak 'at' apple.com) Notice Copyright (c) 2007-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL ES Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Ratified by the Khronos BOP, March 20, 2008. Version Last Modified Date: September 17, 2009 Revision: #3 Number OpenGL ES Extension #43 Dependencies OpenGL ES 1.0 is required. OES_framebuffer_object or OpenGL ES 2.0 is required. Written based on the wording of the OpenGL 2.0 specification. OES_depth_texture affects the definition of this extension. Overview Many OpenGL implementations have chosen to interleave the depth and stencil buffers into one buffer, often with 24 bits of depth precision and 8 bits of stencil data. 32 bits is more than is needed for the depth buffer much of the time; a 24-bit depth buffer, on the other hand, requires that reads and writes of depth data be unaligned with respect to power-of-two boundaries. On the other hand, 8 bits of stencil data is more than sufficient for most applications, so it is only natural to pack the two buffers into a single buffer with both depth and stencil data. OpenGL never provides direct access to the buffers, so the OpenGL implementation can provide an interface to applications where it appears the one merged buffer is composed of two logical buffers. One disadvantage of this scheme is that OpenGL lacks any means by which this packed data can be handled efficiently. For example, when an application reads from the 24-bit depth buffer, using the type GL_UNSIGNED_SHORT will lose 8 bits of data, while GL_UNSIGNED_INT has 8 too many. Both require expensive format conversion operations. A 24-bit format would be no more suitable, because it would also suffer from the unaligned memory accesses that made the standalone 24-bit depth buffer an unattractive proposition in the first place. If OES_depth_texture is supported, a new data format, GL_DEPTH_STENCIL_OES, as well as a packed data type, UNSIGNED_INT_24_8_OES, together can be used with glTex[Sub]Image2D. This provides an efficient way to supply data for a 24-bit depth texture. When a texture with DEPTH_STENCIL_OES data is bound for texturing, only the depth component is accessible through the texture fetcher. This extension also provides a new sized internal format, DEPTH24_STENCIL8_OES, which can be used for renderbuffer storage. When a renderbuffer or texture image with a DEPTH_STENCIL_OES base internal format is attached to both the depth and stencil attachment points of a framebuffer object, then it becomes both the depth and stencil buffers of the framebuffer. This fits nicely with hardware that interleaves both depth and stencil data into a single buffer. New Procedures and Functions None. New Tokens Accepted by the parameter of TexImage2D and TexSubImage2D and by the parameter of TexImage2D: DEPTH_STENCIL_OES 0x84F9 Accepted by the parameter of TexImage2D and TexSubImage2D: UNSIGNED_INT_24_8_OES 0x84FA Accepted by the parameter of RenderbufferStorage, and returned in the parameter of GetRenderbufferParameteriv when is RENDERBUFFER_INTERNAL_FORMAT: DEPTH24_STENCIL8_OES 0x88F0 Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) Update section 2.15.4, after the bullet list on page 86, to add this line: "The stencil index texture internal component is ignored if the base internal format is DEPTH_STENCIL_OES. If a vertex shader uses..." Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) Add a row to Table 3.5 (page 128): type Parameter GL Type Special ------------------------------------------------ ... ... ... UNSIGNED_INT_24_8_OES uint Yes Add a row to Table 3.6 (page 129): Format Name Element Meaning and Order Target Buffer ------------------------------------------------------------------ ... ... ... DEPTH_COMPONENT Depth Depth DEPTH_STENCIL_OES Depth and Stencil Index Depth and Stencil ... ... ... Add a row to Table 3.8 (page 132): type Parameter GL Type Components Pixel Formats ------------------------------------------------------------------ ... ... ... ... UNSIGNED_INT_24_8_OES uint 2 DEPTH_STENCIL_OES Add the following diagram to Table 3.11 (page 134): UNSIGNED_INT_24_8_OES 31 30 29 28 27 26 ... 12 11 10 9 8 7 6 5 4 3 2 1 0 +----------------------------------+---------------+ | 1st Component | 2nd Component | +----------------------------------+---------------+ Add a row to Table 3.12 (page 135): Format | 1st 2nd 3rd 4th ------------------+------------------------------- ... | ... ... ... ... DEPTH_STENCIL_OES | depth stencil N/A N/A Add the following paragraph to the end of the section "Conversion to floating-point" (page 135-136): "For groups of components that contain both standard components and index elements, such as DEPTH_STENCIL_OES, the index elements are not converted." In section 3.8.1 "Texture Image Specification", update page 151 to say: "The selected groups are processed exactly as for DrawPixels, stopping just before final conversion. Each R, G, B, A, or depth value so generated is clamped to [0, 1], while the stencil index values are masked by 2^n-1, where n is the number of stencil bits in the internal format resolution (see below). Components are then selected from the resulting R, G, B, A, depth, or stencil index values to obtain a texture with the base internal format specified by . Table 3.15 summarizes the mapping of R, G, B, A, depth, or stencil values to texture components, as a function of the base internal format of the texture image. may be specified as one of the eight internal format symbolic constants listed in table 3.15, as one of ... Textures with a base internal format of DEPTH_COMPONENT or DEPTH_STENCIL_OES are supported by texture image specification commands only if is 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 or DEPTH_STENCIL_OES require either depth component data or depth/stencil 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 or DEPTH_STENCIL_OES and is not DEPTH_COMPONENT or DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or DEPTH_STENCIL_OES and is DEPTH_COMPONENT or DEPTH_STENCIL_OES." Add a row to table 3.15 (page 153), and update the title of the second column: Base Internal Format RGBA, Depth and Stencil Values Internal Components ------------------------------------------------------------------------- ... ... ... DEPTH_STENCIL_OES Depth,Stencil D,S ... ... ... Update the caption for table 3.15 (page 153) "Table 3.15: Conversion from RGBA, depth, and stencil pixel components to internal texture components. See section 3.8.13 for a description of the texture components R, G, B, A, L, I, D, and S." Add a new section between sections 3.8.9 and 3.8.10, after the first paragraph on page 177: "3.8.9-1/2 Depth/Stencil Textures If the texture image has a base internal format of DEPTH_STENCIL_OES, then the stencil index texture component is ignored. The texture value Tau does not include a stencil index component, but includes only the depth component." Update the first paragraph of section 3.8.15 "Texture Application", on page 189, to say: "...Otherwise, a texture value is found according to the parameter values of the currently bound texture image of the appropriate dimensionality using the rules given in sections 3.8.6 through 3.8.9. Note that the texture value may contain R, G, B, A, L, I, or D components, but it does not contain an S component. If the texture's base internal format is DEPTH_STENCIL_OES, for the purposes of texture application, it is as if the base internal format was DEPTH..." Update section 3.11.2, after the bullet list on page 195, to add this line: "The stencil index texture internal component is ignored if the base internal format is DEPTH_STENCIL_OES. If a fragment shader uses..." Additions to Chapter 4 of the OpenGL ES 2.0 Specification In section 4.4.5 "Framebuffer Completeness", modify the definition of "depth-renderable" and "stencil-renderable" to say: "* An internal format is depth-renderable if it is one of the sized internal formats that has a depth-renderable internal format value of DEPTH_COMPONENT16 or DEPTH24_STENCIL8_OES. No other formats are depth- renderable. * An internal format is stencil-renderable if it is one of the sized internal formats that has a stencil-renderable internal format value of STENCIL_INDEX8 or DEPTH24_STENCIL8_OES. No other formats are stencil-renderable." Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) None. Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests) None. GLX Protocol None. Interactions with OES_depth_texture If OES_depth_texture is not available, mentions of DEPTH_STENCIL_OES and UNSIGNED_INT_24_8_OES as format/type combinations accepted by TexImage2D and TexSubImage2D are omitted. Errors The error INVALID_ENUM is generated if RenderbufferStorage is called with an that is not RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, DEPTH_STENCIL_OES, or one of the internal formats from table 3.16 or table 2.nnn that has a base internal format of RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL_OES." New State None. Usage Example (1) Attach a DEPTH_STENCIL_OES texture image to an FBO as both the depth and stencil buffers. glGenFramebuffers(1, &fb); glGenTextures(1, &tex_color); glGenTextures(1, &tex_depthstencil); glBindFramebuffer(GL_FRAMEBUFFER, fb); // Setup color texture (mipmap) glBindTexture(GL_TEXTURE_2D, tex_color); glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 512, 512, 0, GL_RGBA, GL_UNSIGNED_BYTE, NULL); glGenerateMipmap(GL_TEXTURE_2D); glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, tex_color, 0); // Setup depth_stencil texture (not mipmap) glBindTexture(GL_TEXTURE_2D, tex_depthstencil); glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH_STENCIL_OES, 512, 512, 0, GL_DEPTH_STENCIL_OES, GL_UNSIGNED_INT_24_8_OES, NULL); glFramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, GL_TEXTURE_2D, tex_depthstencil, 0); glFramebufferTexture2D(GL_FRAMEBUFFER, GL_STENCIL_ATTACHMENT, GL_TEXTURE_2D, tex_depthstencil, 0); // Check framebuffer completeness at the end of initialization. loop { glBindTexture(GL_TEXTURE_2D, 0); glBindFramebuffer(GL_FRAMEBUFFER, fb); glBindFramebuffer(GL_FRAMEBUFFER, 0); glBindTexture(GL_TEXTURE_2D, tex_color); glGenerateMipmap(GL_TEXTURE_2D); glBindTexture(GL_TEXTURE_2D, tex_depthstencil); } Issues 1) What are the differences between this extension and EXT_packed_depth_stencil? RESOLVED: The following are the only differences: * No support for 1D or 3D textures * No support for proxy targets * Sized internal format only used for RenderbufferStorage * Format and internal format must match for TexImage2D * No support for DrawPixels, ReadPixels, CopyPixels, CopyTexImage2D, or CopyTexSubImage2D * No support for GetTexLevelParameter, so no TEXTURE_STENCIL_SIZE_EXT * No support for GetTexImage Revision History #03 09/17/2009 Jon Leech Add glCopyTexSubImage2D to exclusions from OpenGL in issue 1 (bug 5335). #02 01/20/2009 Benj Lipchak Make the OES_depth_texture interactions more explicit. #01 10/02/2007 Benj Lipchak Start with EXT_packed_depth_stencil, rename OES and remove non-ES stuff.