xref: /third_party/openGLES/extensions/EXT/EXT_packed_pixels.txt

Name

    EXT_packed_pixels

Name Strings

    GL_EXT_packed_pixels

Version

    $Date: 1997/09/22 23:23:58 $ $Revision: 1.21 $

Number

    23

Dependencies

    EXT_abgr affects the definition of this extension
    EXT_texture3D affects the definition of this extension
    EXT_subtexture affects the definition of this extension
    EXT_histogram affects the definition of this extension
    EXT_convolution affects the definition of this extension
    SGI_color_table affects the definition of this extension
    SGIS_texture4D affects the definition of this extension
    EXT_cmyka affects the definition of this extension

Overview

    This extension provides support for packed pixels in host memory.  A
    packed pixel is represented entirely by one unsigned byte, one
    unsigned short, or one unsigned integer.  The fields with the packed
    pixel are not proper machine types, but the pixel as a whole is.  Thus
    the pixel storage modes, including PACK_SKIP_PIXELS, PACK_ROW_LENGTH,
    PACK_SKIP_ROWS, PACK_IMAGE_HEIGHT_EXT, PACK_SKIP_IMAGES_EXT,
    PACK_SWAP_BYTES, PACK_ALIGNMENT, and their unpacking counterparts all
    work correctly with packed pixels.

New Procedures and Functions

    None

New Tokens

    Accepted by the <type> parameter of DrawPixels, ReadPixels, TexImage1D,
    TexImage2D, GetTexImage, TexImage3DEXT, TexSubImage1DEXT,
    TexSubImage2DEXT, TexSubImage3DEXT, GetHistogramEXT, GetMinmaxEXT,
    ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT,
    GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT,
    GetSeparableFilterEXT, ColorTableSGI, GetColorTableSGI, TexImage4DSGIS,
    and TexSubImage4DSGIS:

        UNSIGNED_BYTE_3_3_2_EXT         0x8032
        UNSIGNED_SHORT_4_4_4_4_EXT      0x8033
        UNSIGNED_SHORT_5_5_5_1_EXT      0x8034
        UNSIGNED_INT_8_8_8_8_EXT        0x8035
        UNSIGNED_INT_10_10_10_2_EXT     0x8036

Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the 1.0 Specification (Rasterization)

    The five tokens defined by this extension are added to Table 3.4:

        <type> Parameter                Corresponding   Special
        Token Value                     GL Data Type    Interpretation
        ----------------                -------------   --------------
        UNSIGNED_BYTE                   ubyte           No
        BYTE                            byte            No
        UNSIGNED_SHORT                  ushort          No
        SHORT                           short           No
        UNSIGNED_INT                    uint            No
        INT                             int             No
        FLOAT                           float           No
        BITMAP                          ubyte           Yes
        UNSIGNED_BYTE_3_3_2_EXT         ubyte           Yes
        UNSIGNED_SHORT_4_4_4_4_EXT      ushort          Yes
        UNSIGNED_SHORT_5_5_5_1_EXT      ushort          Yes
        UNSIGNED_INT_8_8_8_8_EXT        uint            Yes
        UNSIGNED_INT_10_10_10_2_EXT     uint            Yes

        Table 3.4: DrawPixels and ReadPixels <type> parameter values and the
        corresponding GL data types.  Refer to table 2.2 for definitions of
        GL data types.  Special interpretations are described near the end
        of section 3.6.3.

    [Section 3.6.3 of the GL Specification (Rasterization of Pixel
    Rectangles) is rewritten as follows:]

    3.6.3 Rasterization of Pixel Rectangles

    The process of drawing pixels encoded in host memory is diagrammed in
    Figure 3.7.  We describe the stages of this process in the order in which
    they occur.

    Pixels are drawn using

        void DrawPixels(sizei width,
                        sizei height,
                        enum format,
                        enum type,
                        void* data);

    <format> is a symbolic constant indicating what the values in memory
    represent.  <width> and <height> are the width and height, respectively,
    of the pixel rectangle to be drawn.  <data> is a pointer to the data to
    be drawn.  These data are represented with one of seven GL data types,
    specified by <type>.  The correspondence between the thirteen <type>
    token values and the GL data types they indicate is given in Table 3.4.
    If the GL is in color index mode and <format> is not one of COLOR_INDEX,
    STENCIL_INDEX, or DEPTH_COMPONENT, then the error INVALID_OPERATION
    occurs.  Some additional constraints on the combinations of <format>
    and <type> values that are accepted are discussed below.

    Unpacking

    Data are taken from host memory as a sequence of signed or unsigned bytes
    (GL data types byte and ubyte), signed or unsigned short integers (GL data
    types short and ushort), signed or unsigned integers (GL data types int
    and uint), or floating-point values (GL data type float).  These elements
    are grouped into sets of one, two, three, four, or five values, depending
    on the <format>, to form a group.  Table 3.5 summarizes the format of
    groups obtained from memory.  It also indicates those formats that yield
    indices and those that yield components.

                        Target
        Format Name     Buffer  Element Meaning and Order
        -----------     ------  -------------------------
        COLOR_INDEX     Color   Color index
        STENCIL_INDEX   Stencil Stencil index
        DEPTH_COMPONENT Depth   Depth component
        RED             Color   R component
        GREEN           Color   G component
        BLUE            Color   B component
        ALPHA           Color   A component
        RGB             Color   R, G, B components
        RGBA            Color   R, G, B, A components
        ABGR_EXT        Color   A, B, G, R components
        CMYK_EXT        Color   Cyan, Magenta, Yellow, Black components
        CMYKA_EXT       Color   Cyan, Magenta, Yellow, Black, A components
        LUMINANCE       Color   Luminance component
        LUMINANCE_ALPHA Color   Luminance, A components

        Table 3.5: DrawPixels and ReadPixels formats.  The third column
        gives a description of and the number and order of elements in a
        group.

    By default the values of each GL data type are interpreted as they would
    be specified in the language of the client's GL binding.  If
    UNPACK_SWAP_BYTES is set to TRUE, however, then the values are
    interpreted with the bit orderings modified as per the table below.  The
    modified bit orderings are defined only if the GL data type ubyte has
    eight bits, and then for each specific GL data type only if that type
    is represented with 8, 16, or 32 bits.

        Element         Default 
        Size            Bit Ordering    Modified Bit Ordering
        -------         ------------    ---------------------
        8-bit           [7..0]          [7..0]
        16-bit          [15..0]         [7..0] [15..8]
        32-bit          [31..0]         [7..0] [15..8] [23..16] [31..24]

        Table: Bit ordering modification of elements when UNPACK_SWAP_BYTES
        is TRUE.  These reorderings are defined only when GL data type ubyte
        has 8 bits, and then only for GL data types with 8, 16, or 32 bits.

    The groups in memory are treated as being arranged in a rectangle.  This
    rectangle consists of a series of rows, with the first element of the
    first group of the first row pointed to by the pointer passed to
    DrawPixels.  If the value of UNPACK_ROW_LENGTH is not positive, then the
    number of groups in a row is <width>; otherwise the number of groups is
    UNPACK_ROW_LENGTH.  If the first element of the first row is at location
    p in memory, then the location of the first element of the Nth row is

        p + Nk

    where N is the row number (counting from zero) and k is defined as

             / nl                       s >= a
        k = <
             \ a/s * ceiling(snl/a)     s < a

    where n is the number of elements in a group, l is the number of groups
    in a row, a is the value of UNPACK_ALIGNMENT, and s is the size,
    in units of GL ubytes, of an element.  If the number of bits per
    element is not 1, 2, 4, or 8 times the number of bits in a GL ubyte,
    then k = nl for all values of a.

    There is a mechanism for selecting a sub-rectangle of groups from a
    larger containing rectangle.  This mechanism relies on three integer
    parameters: UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, and UNPACK_SKIP_PIXELS.
    Before obtaining the first group from memory, the pointer supplied to
    DrawPixels is effectively advanced by

        UNPACK_SKIP_PIXELS * n + UNPACK_SKIP_ROWS * k

    elements.  Then <width> groups are obtained from contiguous elements
    in memory (without advancing the pointer), after which the pointer is
    advanced by k elements.  <height> sets of <width> groups of values are
    obtained this way.  See Figure 3.8.

    Calling DrawPixels with a <type> of UNSIGNED_BYTE_3_3_2,
    UNSIGNED_SHORT_4_4_4_4, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_INT_8_8_8_8,
    or UNSIGNED_INT_10_10_10_2 is a special case in which all the elements
    of each group are packed into a single unsigned byte, unsigned short,
    or unsigned int, depending on the type.  The number of elements per
    packed pixel is fixed by the type, and must match the number of
    elements per group indicated by the <format> parameter.  (See the table
    below.)  The error INVALID_OPERATION is generated if a mismatch occurs.

                                        GL      Number
        <type> Parameter                Data    of        Matching
        Token Name                      Type    Elements  Pixel Formats
        ----------------                ----    --------  -------------

        UNSIGNED_BYTE_3_3_2_EXT         ubyte   3         RGB
        UNSIGNED_SHORT_4_4_4_4_EXT      ushort  4         RGBA,ABGR_EXT,CMYK_EXT
        UNSIGNED_SHORT_5_5_5_1_EXT      ushort  4         RGBA,ABGR_EXT,CMYK_EXT
        UNSIGNED_INT_8_8_8_8_EXT        uint    4         RGBA,ABGR_EXT,CMYK_EXT
        UNSIGNED_INT_10_10_10_2_EXT     uint    4         RGBA,ABGR_EXT,CMYK_EXT

    Bitfield locations of the first, second, third, and fourth elements
    of each packed pixel type are illustrated in the diagrams below.  Each
    bitfield is interpreted as an unsigned integer value.  If the base GL
    type is supported with more than the minimum precision (e.g. a 9-bit
    byte) the packed elements are right-justified in the pixel.


        UNSIGNED_BYTE_3_3_2_EXT:

              7   6   5   4   3   2   1   0
            +-----------+-----------+-------+
            |           |           |       |
            +-----------+-----------+-------+

               first       second     third
               element     element    element


        UNSIGNED_SHORT_4_4_4_4_EXT:

              15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
            +---------------+---------------+---------------+---------------+
            |               |               |               |               |
            +---------------+---------------+---------------+---------------+

                first           second          third           fourth
                element         element         element         element


        UNSIGNED_SHORT_5_5_5_1_EXT:

              15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
            +-------------------+-------------------+-------------------+---+
            |                   |                   |                   |   |
            +-------------------+-------------------+-------------------+---+

                first                second             third           fourth
                element              element            element         element


        UNSIGNED_INT_8_8_8_8_EXT:

             31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
            +-----------------------+-----------------------+-----------------------+-----------------------+
            |                       |                       |                       |                       |
            +-----------------------+-----------------------+-----------------------+-----------------------+

                     first                   second                  third                   fourth
                     element                 element                 element                 element


        UNSIGNED_INT_10_10_10_2_EXT:

             31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
            +-----------------------------+-----------------------------+-----------------------------+-----+
            |                             |                             |                             |     |
            +-----------------------------+-----------------------------+-----------------------------+-----+

                       first                         second                        third               fourth
                       element                       element                       element             element


    The assignment of elements to fields in the packed pixel is as
    described in the table below:

                        First       Second      Third       Fourth
        Format          Element     Element     Element     Element
        ------          -------     -------     -------     -------
        RGB             red         green       blue
        RGBA            red         green       blue        alpha
        ABGR_EXT        alpha       blue        green       red
        CMYK_EXT        cyan        magenta     yellow      black
    
    Byte swapping, if enabled, is performed before the elements are
    extracted from each pixel.  The above discussions of row length and
    image extraction are valid for packed pixels, if "group" is substituted
    for "element" and the number of elements per group is understood to
    be one.

    Calling DrawPixels with a <type> of BITMAP is a special case in which
    the data are a series of GL ubyte values.  Each ubyte value specifies
    8 1-bit elements with its 8 least-significant bits.  The 8 single-bit
    elements are ordered from most significant to least significant if the
    value of UNPACK_LSB_FIRST is FALSE; otherwise, the ordering is from
    least significant to most significant.  The values of bits other than
    the 8 least significant in each ubyte are not significant.

    The first element of the first row is the first bit (as defined above)
    of the ubyte pointed to by the pointer passed to DrawPixels.  The first
    element of the second row is the first bit (again as defined above) of
    the ubyte at location p+k, where k is computed as

        k = a * ceiling(nl/8a)

    There is a mechanism for selecting a sub-rectangle of elements from
    a BITMAP image as well.  Before obtaining the first element from memory,
    the pointer supplied to DrawPixels is effectively advanced by

        UNPACK_SKIP_ROWS * k

    ubytes.  Then UNPACK_SKIP_PIXELS 1-bit elements are ignored, and the
    subsequent <width> 1-bit elements are obtained, without advancing the
    ubyte pointer, after which the pointer is advanced by k ubytes.  <height>
    sets of <width> elements are obtained this way.

    Conversion to floating-point

    This step applies only to groups of components.  It is not performed on
    indices.  Each element in a group is converted to a floating-point value
    according to the appropriate formula in Table 2.4 (section 2.12).
    Unsigned integer bitfields extracted from packed pixels are interpreted
    using the formula

        f = c / ((2**N)-1)

    where c is the value of the bitfield (interpreted as an unsigned
    integer), N is the number of bits in the bitfield, and the division is
    performed in floating point.

    [End of changes to Section 3.6.3]

    If this extension is supported, all commands that accept pixel data
    also accept packed pixel data.  These commands are DrawPixels,
    TexImage1D, TexImage2D, TexImage3DEXT, TexSubImage1DEXT,
    TexSubImage2DEXT, TexSubImage3DEXT, ConvolutionFilter1DEXT,
    ConvolutionFilter2DEXT, ConvolutionFilter3DEXT, SeparableFilter2DEXT,
    SeparableFilter3DEXT, ColorTableSGI, TexImage4DSGIS, and
    TexSubImage4DSGIS.

Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
and the Framebuffer)

    [Make the following changes to Section 4.3.2 (Reading Pixels):]

    Final Conversion

    For an index, if the <type> is not FLOAT, final conversion consists of
    masking the index with the value given in Table 4.6; if the <type> is
    FLOAT, then the integer index is converted to a GL float data value.
    For a component, each component is first clamped to [0,1].  Then,
    the appropriate conversion formula from Table 4.7 is applied to the
    component.

        <type> Parameter        Index Mask
        ----------------        ----------
        UNSIGNED_BYTE           2**8 - 1
        BITMAP                  1
        BYTE                    2**7 - 1
        UNSIGNED_SHORT          2**16 - 1
        SHORT                   2**15 - 1
        UNSIGNED_INT            2**32 - 1
        INT                     2**31 - 1

        Table 4.6: Index masks used by ReadPixels.  Floating point data
        are not masked.

        <type>                          GL Data         Component
        Parameter                       Type            Conversion Formula
        ---------                       -------         ------------------
        UNSIGNED_BYTE                   ubyte           c = ((2**8)-1)*f
        BYTE                            byte            c = (((2**8)-1)*f-1)/2
        UNSIGNED_SHORT                  ushort          c = ((2**16)-1)*f
        SHORT                           short           c = (((2**16)-1)*f-1)/2
        UNSIGNED_INT                    uint            c = ((2**32)-1)*f
        INT                             int             c = (((2**32)-1)*f-1)/2
        FLOAT                           float           c = f
        UNSIGNED_BYTE_3_3_2_EXT         ubyte           c = ((2**N)-1)*f
        UNSIGNED_SHORT_4_4_4_4_EXT      ushort          c = ((2**N)-1)*f
        UNSIGNED_SHORT_5_5_5_1_EXT      ushort          c = ((2**N)-1)*f
        UNSIGNED_INT_8_8_8_8_EXT        uint            c = ((2**N)-1)*f
        UNSIGNED_INT_10_10_10_2_EXT     uint            c = ((2**N)-1)*f

        Table 4.7: Reversed component conversions - used when component data
        are being returned to client memory.  Color, normal, and depth
        components are converted from the internal floating-point
        representation (f) to a datum of the specified GL data type (c) using
        the equations in this table.  All arithmetic is done in the internal
        floating point format.  These conversions apply to component data
        returned by GL query commands and to components of pixel data returned
        to client memory.  The equations remain the same even if the
        implemented ranges of the GL data types are greater than the minimum
        required ranges.  (Refer to table 2.2.)  Equations with N as the
        exponent are performed for each bitfield of the packed data type,
        with N set to the number of bits in the bitfield.

    Placement in Client Memory

    Groups of elements are placed in memory just as they are taken from memory
    for DrawPixels.  That is, the ith group of the jth row (corresponding to
    the ith pixel in the jth row) is placed in memory must where the ith group
    of the jth row would be taken from for DrawPixels.  See Unpacking under
    section 3.6.3.  The only difference is that the storage mode parameters
    whose names begin with PACK_ are used instead of those whose names begin
    with UNPACK_.

    [End of changes to Section 4.3.2]

    If this extension is supported, all commands that return pixel data
    also return packed pixel data.  These commands are ReadPixels,
    GetTexImage, GetHistogramEXT, GetMinmaxEXT, GetConvolutionFilterEXT,
    GetSeparableFilterEXT, and GetColorTableSGI.

Additions to Chapter 5 of the 1.0 Specification (Special Functions)

    None

Additions to Chapter 6 of the 1.0 Specification (State and State Requests)

    None

Additions to the GLX Specification

    None

GLX Protocol

        None

Dependencies on EXT_abgr

    If EXT_abgr is not implemented, then the references to ABGR_EXT in this
    file are invalid, and should be ignored.

Dependencies on EXT_texture3D

    If EXT_texture3D is not implemented, then the references to
    TexImage3DEXT in this file are invalid, and should be ignored.

Dependencies on EXT_subtexture

    If EXT_subtexture is not implemented, then the references to
    TexSubImage1DEXT, TexSubImage2DEXT, and TexSubImage3DEXT in this file
    are invalid, and should be ignored.

Dependencies on EXT_histogram

    If EXT_histogram is not implemented, then the references to
    GetHistogramEXT and GetMinmaxEXT in this file are invalid, and should be
    ignored.

Dependencies on EXT_convolution

    If EXT_convolution is not implemented, then the references to
    ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT,
    GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT, and
    GetSeparableFilterEXT in this file are invalid, and should be ignored.

Dependencies on SGI_color_table

    If SGI_color_table is not implemented, then the references to
    ColorTableSGI and GetColorTableSGI in this file are invalid, and should
    be ignored.

Dependencies on SGIS_texture4D

    If SGIS_texture4D is not implemented, then the references to
    TexImage4DSGIS and TexSubImage4DSGIS in this file are invalid, and should
    be ignored.

Dependencies on EXT_cmyka

    If EXT_cmyka is not implemented, then the references to CMYK_EXT and
    CMYKA_EXT in this file are invalid, and should be ignored.

Errors

    [For the purpose of this enumeration of errors, GenericPixelFunction
    represents any OpenGL function that accepts or returns pixel data, using
    parameters <type> and <format> to define the type and format of that
    data.  Currently these functions are DrawPixels, ReadPixels, TexImage1D,
    TexImage2D, GetTexImage, TexImage3DEXT, TexSubImage1DEXT,
    TexSubImage2DEXT, TexSubImage3DEXT, GetHistogramEXT, GetMinmaxEXT,
    ConvolutionFilter1DEXT, ConvolutionFilter2DEXT, ConvolutionFilter3DEXT,
    GetConvolutionFilterEXT, SeparableFilter2DEXT, SeparableFilter3DEXT,
    GetSeparableFilterEXT, ColorTableSGI, GetColorTableSGI, TexImage4DSGIS,
    and TexSubImage4DSGIS.]

    INVALID_OPERATION is generated by GenericPixelFunction if its <type>
    parameter is UNSIGNED_BYTE_3_3_2_EXT and its <format> parameter does not
    specify three components.  Currently the only 3-component format is RGB.

    INVALID_OPERATION is generated by GenericPixelFunction if its <type>
    parameter is UNSIGNED_SHORT_4_4_4_4_EXT, UNSIGNED_SHORT_5_5_5_1_EXT,
    UNSIGNED_INT_8_8_8_8_EXT, or UNSIGNED_INT_10_10_10_2_EXT and its
    <format> parameter does not specify four components.  Currently the only
    4-component formats are RGBA, ABGR_EXT, and CMYK_EXT.

New State

    None

New Implementation Dependent State

    None