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) Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) Status Complete. Version Last Modifed Date: Feb 8, 2013 Author Revision: 2 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 parameters of PixelStorei, GetIntegerv, and GetFloatv: GL_UNPACK_ROW_LENGTH_EXT 0x0CF2 GL_UNPACK_SKIP_ROWS_EXT 0x0CF3 GL_UNPACK_SKIP_PIXELS_EXT 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_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 ; 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 groups are obtained from contiguous elements in memory (without advancing the pointer), after which the pointer is advanced by k elements. sets of 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) Errors None New State 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 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_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. Revision History 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