EXT_unpack_subimage

GL_EXT_unpack_subimage

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

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

Complete.

Last Modifed Date:  Feb 8, 2013
Author Revision:    2

OpenGL ES Extension #90

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

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.

None

None

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

    GL_UNPACK_ROW_LENGTH_EXT            0x0CF2
    GL_UNPACK_SKIP_ROWS_EXT             0x0CF3
    GL_UNPACK_SKIP_PIXELS_EXT           0x0CF4

Modifications to Table 3.1 (PixelStore parameters)

    Add the following entries:

    Parameter Name          Type      Initial Value  Valid Range
    ==============          ====      =============  ===========
    UNPACK_ROW_LENGTH_EXT   integer   0              [0,Infinity)
    UNPACK_SKIP_ROWS_EXT    integer   0              [0,Infinity)
    UNPACK_SKIP_PIXELS_EXT  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_EXT is not positive, then the
      number of groups in a row is <width>; otherwise the number of
      groups is UNPACK_ROW_LENGTH_EXT."

    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_EXT, UNPACK_SKIP_ROWS_EXT,
      and UNPACK_SKIP_PIXELS_EXT. Before obtaining the first group from
      memory, the pointer supplied to TexImage2D is effectively
      advanced by (UNPACK_SKIP_PIXELS_EXT)n + (UNPACK_SKIP_ROWS_EXT)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_EXT, UNPACK_SKIP_ROWS_EXT, and
       UNPACK_SKIP_PIXELS_EXT)

None

Modifications to Table 6.12 Pixels in section 6.2 State Tables:

    Get Value              Type  Get Cmnd     Initial  Description                     Sec.
                                              Value
    ====================   ====  ===========  =======  =============================== =====
    UNPACK_ROW_LENGTH_EXT  Z+    GetIntegerv  0        Value of UNPACK_ROW_LENGTH_EXT  3.6.1
    UNPACK_SKIP_ROWS_EXT   Z+    GetIntegerv  0        Value of UNPACK_SKIP_ROWS_EXT   3.6.1
    UNPACK_SKIP_PIXELS_EXT Z+    GetIntegerv  0        Value of UNPACK_SKIP_PIXELS_EXT 3.6.1

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

4. Should the new tokens be suffixed?
 
    Yes. This extension was originally drafted with unsuffixed tokens
    since they provide the same functionality as in core Desktop GL.
    However, the policy of the ES working group is that suffixes 
    must be used in extensions even for functionality that is core
    in Desktop GL.

Rev.   Date       Author       Changes
----   --------   ---------    ------------------------------------
 1     03/25/11   ppipkorn     First revision.
 2     02/08/13   dgkoch       add suffixes to tokens
                               remove unnecessary column from table 6.12 edits