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

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 <format> parameter of TexImage2D and TexSubImage2D and by the 
    <internalformat> parameter of TexImage2D:

        DEPTH_STENCIL_OES                              0x84F9

    Accepted by the <type> parameter of TexImage2D and TexSubImage2D:

        UNSIGNED_INT_24_8_OES                          0x84FA

    Accepted by the <internalformat> parameter of RenderbufferStorage, and 
    returned in the <params> parameter of GetRenderbufferParameteriv when 
    <pname> 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 <internalformat>.  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.  <internalformat> 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 <target> is
    TEXTURE_2D.  Using this format in conjunction with any other <target> 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 <format> is not DEPTH_COMPONENT or
    DEPTH_STENCIL_OES, or if the base internal format is not DEPTH_COMPONENT or
    DEPTH_STENCIL_OES and <format> 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
    <internalformat> 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);
            <render to color, depth, and stencil textures>
            glBindFramebuffer(GL_FRAMEBUFFER, 0);

            glBindTexture(GL_TEXTURE_2D, tex_color);
            glGenerateMipmap(GL_TEXTURE_2D);
            <draw to the window, reading from the color texture>

            glBindTexture(GL_TEXTURE_2D, tex_depthstencil);
            <draw to the window, reading depth from the depthstencil texture>
        }

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.