xref: /third_party/openGLES/extensions/NV/NV_texture_compression_s3tc.txt

Name

    NV_texture_compression_s3tc

Name Strings

    GL_NV_texture_compression_s3tc

Contributors

    Contributors to the OpenGL EXT_texture_compression_s3tc extension
    Greg Roth, NVIDIA

Contact

    Ian Stewart, NVIDIA Corporation (istewart 'at' nvidia.com)

Status

    Complete.

Version

    Last Modifed Date: Sep 27, 2012
    NVIDIA Revision: 1

Number

    OpenGL ES Extension #128

Dependencies

    This extension is written against the OpenGL ES 2.0.25
    Specification.

    This extension interacts with NV_texture_array

Overview

    This extension adds support for S3's S3TC texture compression
    formats, including DXT1, DXT3, and DXT5.  For the DXT1 format,
    this specification supports an RGB-only mode and a special RGBA
    mode with single-bit alpha.

IP Status

    Contact S3 Incorporated (http://www.s3.com) regarding any
    intellectual property issues associated with implementing this
    extension.

    WARNING: Vendors able to support S3TC texture compression in
    Direct3D drivers do not necessarily have the right to use the same
    functionality in OpenGL ES.

New Tokens

    Accepted by the <internalformat> parameter of CompressedTexImage2D
    and CompressedTexSubImage2D:

        COMPRESSED_RGB_S3TC_DXT1_NV                     0x83F0
        COMPRESSED_RGBA_S3TC_DXT1_NV                    0x83F1
        COMPRESSED_RGBA_S3TC_DXT3_NV                    0x83F2
        COMPRESSED_RGBA_S3TC_DXT5_NV                    0x83F3

Additions to Chapter 3 of the OpenGL ES 2.0.25 Specification

    Modify Section 3.7.3, "Compressed Texture Images"

    (Replace first two sentences with)

    Texture images may also be specified or modified using image data
    already stored in a known compressed image format.  The GL defines
    some specific compressed formats, and others may be defined by GL
    extensions.

    (Insert after section describing CompressedTexImage2D)

    The specific compressed texture formats supported by
    CompressedTexImage2D, and the corresponding base internal format
    for each specific format, are defined in table 3.X.

        Table 3.X: "Specific compressed texture formats"

        Compressed Internal Formats           Base Internal Format
        ===========================           ====================
        COMPRESSED_RGB_S3TC_DXT1_NV           RGB
        COMPRESSED_RGBA_S3TC_DXT1_NV          RGBA
        COMPRESSED_RGBA_S3TC_DXT3_NV          RGBA
        COMPRESSED_RGBA_S3TC_DXT5_NV          RGBA

    (Replace last paragraph with)

    If the internal format is one of COMPRESSED_RGB_S3TC_DXT1_NV,
    COMPRESSED_RGBA_S3TC_DXT1_NV, COMPRESSED_RGBA_S3TC_DXT3_NV, or
    COMPRESSED_RGBA_S3TC_DXT5_NV, the compressed texture is stored
    using one of several S3TC compressed texture image formats and is
    easily edited along 4x4 texel boundaries. In this case,
    CompressedTexImage2D will result in an INVALID_OPERATION error
    if one of the following conditions occurs:

        * <width> is not a multiple of four, and <width> plus
          <xoffset> is not equal to TEXTURE_WIDTH;

        * <height> is not a multiple of four, and <height> plus
          <yoffset> is not equal to TEXTURE_HEIGHT; or

        * <xoffset> or <yoffset> is not a multiple of four.

    For any other formats, calling CompressedTexSubImage2D will result
    in an INVALID_OPERATION error if <xoffset> or <yoffset> is not
    equal to zero, or if <width> and <height> do not match the width
    and height of the texture, respectively. The contents of any texel
    outside the region modified by the call are undefined. These
    restrictions may be relaxed for other specific compressed internal
    formats whose images are easily modified.

Interactions with NV_texture_array

    If NV_texture_array is supported, the S3TC compressed formats may
    also be used as the internal formats given to
    CompressedTexImage3DNV and CompressedTexSubImage3DNV. The
    restrictions for the <width>, <height>, <xoffset>, and <yoffset>
    parameters of the CompressedTexSubImage2D function when used with
    S3TC compressed texture formats, described in this extension, also
    apply to the identically named parameters of
    CompressedTexSubImage3DNV.

Errors

    INVALID_OPERATION is generated by CopyTexSubImage2D if the texture
    image <level> bound to <target> has internal format
    COMPRESSED_RGB_S3TC_DXT1_NV, COMPRESSED_RGBA_S3TC_DXT1_NV,
    COMPRESSED_RGBA_S3TC_DXT3_NV, or COMPRESSED_RGBA_S3TC_DXT5_NV.

    INVALID_OPERATION is generated by CompressedTexSubImage2D if
    <internalformat> is COMPRESSED_RGB_S3TC_DXT1_NV,
    COMPRESSED_RGBA_S3TC_DXT1_NV, COMPRESSED_RGBA_S3TC_DXT3_NV, or
    COMPRESSED_RGBA_S3TC_DXT5_NV and any of the following apply:

        * <width> is not a multiple of four, and <width> plus
          <xoffset> is not equal to the texture width;

        * <height> is not a multiple of four, and <height> plus
          <yoffset> is not equal to the texture height; or

        * <xoffset> or <yoffset> is not a multiple of four.

New State

    The queries for NUM_COMPRESSED_TEXTURE_FORMATS and
    COMPRESSED_TEXTURE_FORMATS include COMPRESSED_RGB_S3TC_DXT1_NV,
    COMPRESSED_RGBA_S3TC_DXT1_NV, COMPRESSED_RGBA_S3TC_DXT3_NV, and
    COMPRESSED_RGBA_S3TC_DXT5_NV.

Appendix

    S3TC Compressed Texture Image Formats

    Compressed texture images stored using the S3TC compressed image
    formats are represented as a collection of 4x4 texel blocks, where
    each block contains 64 or 128 bits of texel data.  The image is
    encoded as a normal 2D raster image in which each 4x4 block is
    treated as a single pixel.  If an S3TC image has a width or height
    that is not a multiple of four, the data corresponding to texels
    outside the image are irrelevant and undefined.

    When an S3TC image with a width of <w>, height of <h>, and block
    size of <blocksize> (8 or 16 bytes) is decoded, the corresponding
    image size (in bytes) is:

        ceil(<w>/4) * ceil(<h>/4) * blocksize.

    When decoding an S3TC image, the block containing the texel at
    offset (<x>, <y>) begins at an offset (in bytes) relative to the
    base of the image of:

        blocksize * (ceil(<w>/4) * floor(<y>/4) + floor(<x>/4)).

    The data corresponding to a specific texel (<x>, <y>) are
    extracted from a 4x4 texel block using a relative (x,y) value of

        (<x> modulo 4, <y> modulo 4).

    There are four distinct S3TC image formats:

    COMPRESSED_RGB_S3TC_DXT1_NV:  Each 4x4 block of texels consists of
    64 bits of RGB image data.

        Each RGB image data block is encoded as a sequence of 8 bytes,
        called (in order of increasing address):

            c0_lo, c0_hi, c1_lo, c1_hi, bits_0, bits_1, bits_2, bits_3

        The 8 bytes of the block are decoded into three quantities:

            color0 = c0_lo + c0_hi * 256
            color1 = c1_lo + c1_hi * 256
            bits   = bits_0 + 256 * (bits_1 + 256 * (bits_2 + 256 * bits_3))

        color0 and color1 are 16-bit unsigned integers that are
        unpacked to RGB colors RGB0 and RGB1 as though they were
        16-bit packed pixels with a <format> of RGB and a type of
        UNSIGNED_SHORT_5_6_5.

        bits is a 32-bit unsigned integer, from which a two-bit
        control code is extracted for a texel at location (x,y) in the
        block using:

            code(x,y) = bits[2*(4*y+x)+1 .. 2*(4*y+x)+0]

        where bit 31 is the most significant and bit 0 is the least
        significant bit.

        The RGB color for a texel at location (x,y) in the block is
        given by:

            RGB0,              if color0 > color1 and code(x,y) == 0
            RGB1,              if color0 > color1 and code(x,y) == 1
            (2*RGB0+RGB1)/3,   if color0 > color1 and code(x,y) == 2
            (RGB0+2*RGB1)/3,   if color0 > color1 and code(x,y) == 3

            RGB0,              if color0 <= color1 and code(x,y) == 0
            RGB1,              if color0 <= color1 and code(x,y) == 1
            (RGB0+RGB1)/2,     if color0 <= color1 and code(x,y) == 2
            BLACK,             if color0 <= color1 and code(x,y) == 3

        Arithmetic operations are done per component, and BLACK refers
        to an RGB color where red, green, and blue are all zero.

        Since this image has an RGB format, there is no alpha
        component and the image is considered fully opaque.


    COMPRESSED_RGBA_S3TC_DXT1_NV:  Each 4x4 block of texels consists
    of 64 bits of RGB image data and minimal alpha information.  The
    RGB components of a texel are extracted in the same way as
    COMPRESSED_RGB_S3TC_DXT1_NV.

        The alpha component for a texel at location (x,y) in the block
        is given by:

            0.0,               if color0 <= color1 and code(x,y) == 3
            1.0,               otherwise


    COMPRESSED_RGBA_S3TC_DXT3_NV:  Each 4x4 block of texels consists
    of 64 bits of uncompressed alpha image data followed by 64 bits of
    RGB image data.

        Each RGB image data block is encoded according to the
        COMPRESSED_RGB_S3TC_DXT1_NV format, with the exception that
        the two code bits always use the non-transparent encodings.
        In other words, they are treated as though color0 > color1,
        regardless of the actual values of color0 and color1.

        Each alpha image data block is encoded as a sequence of 8
        bytes, called (in order of increasing address):

            a0, a1, a2, a3, a4, a5, a6, a7

        The 8 bytes of the block are decoded into one 64-bit integer:

            alpha = a0 + 256 * (a1 + 256 * (a2 + 256 * (a3 + 256 * (a4 +
                         256 * (a5 + 256 * (a6 + 256 * a7))))))

        alpha is a 64-bit unsigned integer, from which a four-bit
        alpha value is extracted for a texel at location (x,y) in the
        block using:

            alpha(x,y) = bits[4*(4*y+x)+3 .. 4*(4*y+x)+0]

        where bit 63 is the most significant and bit 0 is the least
        significant bit.

        The alpha component for a texel at location (x,y) in the block
        is given by alpha(x,y) / 15.


    COMPRESSED_RGBA_S3TC_DXT5_NV:  Each 4x4 block of texels consists
    of 64 bits of compressed alpha image data followed by 64 bits of
    RGB image data.

        Each RGB image data block is encoded according to the
        COMPRESSED_RGB_S3TC_DXT1_NV format, with the exception that
        the two code bits always use the non-transparent encodings.
        In other words, they are treated as though color0 > color1,
        regardless of the actual values of color0 and color1.

        Each alpha image data block is encoded as a sequence of 8
        bytes, called (in order of increasing address):

        alpha0, alpha1, bits_0, bits_1, bits_2, bits_3, bits_4, bits_5

        The alpha0 and alpha1 are 8-bit unsigned bytes converted to
        alpha components by multiplying by 1/255.

        The 6 "bits" bytes of the block are decoded into one 48-bit
        integer:

          bits = bits_0 + 256 * (bits_1 + 256 * (bits_2 + 256 * (bits_3 +
                          256 * (bits_4 + 256 * bits_5))))

        bits is a 48-bit unsigned integer, from which a three-bit
        control code is extracted for a texel at location (x,y) in the
        block using:

            code(x,y) = bits[3*(4*y+x)+2 .. 3*(4*y+x)+0]

        where bit 47 is the most significant and bit 0 is the least
        significant bit.

        The alpha component for a texel at location (x,y) in the block
        is given by:

              alpha0,                   code(x,y) == 0
              alpha1,                   code(x,y) == 1

              (6*alpha0 + 1*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 2
              (5*alpha0 + 2*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 3
              (4*alpha0 + 3*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 4
              (3*alpha0 + 4*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 5
              (2*alpha0 + 5*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 6
              (1*alpha0 + 6*alpha1)/7,  alpha0 > alpha1 and code(x,y) == 7

              (4*alpha0 + 1*alpha1)/5,  alpha0 <= alpha1 and code(x,y) == 2
              (3*alpha0 + 2*alpha1)/5,  alpha0 <= alpha1 and code(x,y) == 3
              (2*alpha0 + 3*alpha1)/5,  alpha0 <= alpha1 and code(x,y) == 4
              (1*alpha0 + 4*alpha1)/5,  alpha0 <= alpha1 and code(x,y) == 5
              0.0,                      alpha0 <= alpha1 and code(x,y) == 6
              1.0,                      alpha0 <= alpha1 and code(x,y) == 7


Issues

    None

Revision History

    Rev.    Date        Author       Changes
    ----   --------     ---------    -------------------------------------
     1     09/27/2012   istewart     First revision, based of the
                                     EXT_texture_compression_s3tc
                                     specification.

# vim:ai:ts=4:sts=4:expandtab:textwidth=70