Name

    EXT_unpack_subimage

Name Strings

    GL_EXT_unpack_subimage

Contact

    Peter Pipkorn, NVIDIA Corporation (ppipkorn 'at' nvidia.com)

Contributors

    Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com)
    Nicolai de Haan, NVIDIA Corporation (nicolaid 'at' nvidia.com)

Status

    Draft

Version

    Last Modifed Date:  Mar 25, 2011
    Author Revision:    1.0

Number

    OpenGL ES Extension #90

Dependencies

    The extension is written against the OpenGL ES 2.0 specification.
    The extension references the OpenGL 2.0 specification.

Overview

    This OpenGL ES 2.0 extension adds support for GL_UNPACK_ROW_LENGTH,
    GL_UNPACK_SKIP_ROWS and GL_UNPACK_SKIP_PIXELS as valid enums to
    PixelStore.  The functionality is the same as in OpenGL. These are
    useful for updating textures with a sub-rectangle of pixel data
    coming from a larger image in host memory.

IP Status

    None

New Procedures and Functions

    None

New Tokens

    Accepted by the <pname> parameters of PixelStorei, GetIntegerv, and
    GetFloatv:

        GL_UNPACK_ROW_LENGTH                0x0CF2
        GL_UNPACK_SKIP_ROWS                 0x0CF3
        GL_UNPACK_SKIP_PIXELS               0x0CF4

Additions to the OpenGL ES 2.0 Specification

    Modifications to Table 3.1 (PixelStore parameters)

        Add the following entries:

        Parameter Name          Type      Initial Value  Valid Range
        ==============          ====      =============  ===========
        UNPACK_ROW_LENGTH       integer   0              [0,Infinity)
        UNPACK_SKIP_ROWS        integer   0              [0,Infinity)
        UNPACK_SKIP_PIXELS      integer   0              [0,Infinity)

    Modifications to 3.6.2 Transfer of Pixel Rectangles, in the Unpacking
    section:

        Change

          "The number of groups in a row is width;"

        to

          "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."

        After the sentence

          "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."

        insert:

          "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 TexImage2D 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.6."

        Before Table 3.5 Packed pixel formats, insert

           Figure 3.8 from the OpenGL 2.0 specification (a visual
           description of UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, and
           UNPACK_SKIP_PIXELS)

Errors

    None

New State

    Modifications to Table 6.12 Pixels in section 6.2 State Tables:

        Get Value              Type  Get Cmnd     Initial  Description                     Sec.    Attribute
                                                  Value
        ====================   ====  ===========  =======  ============================    =====   ===========
        UNPACK_ROW_LENGTH      Z+    GetIntegerv  0        Value of UNPACK_ROW_LENGTH      3.6.1   pixel-store
        UNPACK_SKIP_ROWS       Z+    GetIntegerv  0        Value of UNPACK_SKIP_ROWS       3.6.1   pixel-store
        UNPACK_SKIP_PIXELS     Z+    GetIntegerv  0        Value of UNPACK_SKIP_PIXELS     3.6.1   pixel-store

Issues

    1. Can't this be done with repeated calls to
       TexSubImage2D/TexSubImage3D?

        Yes, it is possible to unpack pixels from a sub-rectangle in
        host memory by by calling these functions for one line at a
        time, but this could add unnecessary burden on the CPU system.
        Specifying GL_UNPACK_ROW_LENGTH makes it possible to unpack
        sub-rectangles of pixels with lower overhead.

    2. Should the corresponding PACK enums be added?

        No, it should be done in a separate extension. There is no
        dependency between the PACK enums and the UNPACK enums.

    3. Are these UNPACK_SKIP_* tokens strictly necessary?

        No. The same functionality can be achieved by advancing the
        pixel pointer to host memory appropriately before issuing an
        unpacking function call. They are included here for both
        completeness and for convenience.

Revision History

    Rev.   Date       Author       Changes
    ----   --------   ---------    ------------------------------------
     1     03/25/11   ppipkorn     First revision.