1Name
2
3    ANGLE_pack_reverse_row_order
4
5Name Strings
6
7    GL_ANGLE_pack_reverse_row_order
8
9Contact
10
11    Daniel Koch, TransGaming (daniel 'at' transgaming.com)
12
13Contributors
14
15    Brian Salomon
16    Daniel Koch
17
18Status
19
20    Implemented in ANGLE ES2
21
22Version
23
24    Last Modified Date: February 22, 2011
25    Author Revision: 22
26
27Number
28
29    OpenGL ES Extension #110
30
31Dependencies
32
33    OpenGL 1.5 or OpenGL ES 1.0 are required.
34
35    Some of the functionality of this extension is not supported
36    when implemented against OpenGL ES.
37
38    EXT_texture_rg interacts with this extension.
39
40    The extension is written against the OpenGL 3.2 Specification
41    (Core Profile).
42
43Overview
44
45    This extension introduces a mechanism to allow reversing the order
46    in which image rows are written into a pack destination. This
47    effectively allows an application to flip the results of a ReadPixels
48    in the y direction operation without having to render upside down.
49
50    The coordinate system of OpenGL is vertically reversed in comparison to a
51    number of other graphics systems such as native windowing APIs. Applications
52    that perform ReadPixels may have to either render to an intermediate color
53    buffer before calling ReadPixels or perform a flip in software after
54    ReadPixels. In some systems the GL can perform the row reversal during
55    ReadPixels without incurring additional cost.
56
57IP Status
58
59    No known IP claims.
60
61New Procedures and Functions
62
63    None
64
65New Types
66
67    None
68
69New Tokens
70
71    Accepted by the <pname> parameter of PixelStore{if}, GetIntegerv(),
72    GetBooleanv(), and GetFloatv():
73
74        PACK_REVERSE_ROW_ORDER_ANGLE    0x93A4
75
76Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)
77
78    In Section 4.3.1 (Reading Pixels) add a row to table 4.7:
79
80        +------------------------------+---------+---------------+-------------+
81        | Parameter Name               | Type    | Initial Value | Valid Range |
82        +------------------------------+---------+---------------+-------------+
83        | PACK_REVERSE_ROW_ORDER_ANGLE | boolean | FALSE         | TRUE/FALSE  |
84        +------------------------------+---------+---------------+-------------+
85
86    In Section 4.3.1 (Reading Pixels) modify the second paragraph of subsection 
87    "Placement in Pixel Pack Buffer or Client Memory" to read:
88
89        When PACK_REVERSE_ROW_ORDER_ANGLE is FALSE groups of elements are placed
90        in memory just as they are taken from memory when transferring pixel
91        rectangles to the GL. That is, the ith group of the jth row
92        (corresponding to the ith pixel in the jth row) is placed in memory just
93        where the ith group of the jth row would be taken from when transferring
94        pixels. See Unpacking under section 3.7.2. The only difference is that
95        the storage mode parameters whose names begin with PACK_ are used
96        instead of those whose names begin with UNPACK_. If the format is RED,
97        GREEN, BLUE, or ALPHA, only the corresponding single element is written.
98        Likewise if the format is RG, RGB, or BGR, only the corresponding two or
99        three elements are written. Otherwise all the elements of each group are
100        written. When PACK_REVERSE_ROW_ORDER_ANGLE is TRUE the order of the rows
101        of elements is reversed before the data is packed. That is, the element
102        corresponding to pixel (x, y + height - 1) becomes the first element
103        packed, followed by (x + 1, y + height - 1), etc. Otherwise, pixel data
104        is packed in the same manner as when PACK_REVERSE_ROW_ORDER_ANGLE is
105        FALSE.
106
107Additions to Chapter 6 of the OpenGL 3.2 Specification (State and State Requests)
108
109    In Section 6.1.4 add the following sentence to the fifth paragraph
110    (beginning with "For three-dimensional and two-dimensional array
111    textures..."):
112        When PACK_REVERSE_ROW_ORDER_ANGLE is TRUE the order of rows within
113        each image are reversed without reordering the images themselves.
114
115Dependencies on OpenGL ES
116
117    If implemented for OpenGL ES, this extension behaves as specified, except:
118
119    -Delete all references to formats RED, GREEN, BLUE, RG, and BGR.
120
121    -The language about image order in Section 6.1.4 does not apply as OpenGL ES
122     does not have GetTexImage.
123
124Dependencies on EXT_texture_rg
125
126    If EXT_texture_rg is present reinsert language about formats RED and RG
127    into the OpenGL ES 2.0 specification.
128
129Errors
130
131    None
132
133New State
134                                                           Initial
135    Get Value                       Type  Get Command      Value    Description                    Sec.
136    ---------                       ----  -----------      -------  -----------                    ----
137    PACK_REVERSE_ROW_ORDER_ANGLE    B     GetIntegerv      FALSE    Pixel pack row order reversal  4.3.1
138
139New Implementation Dependent State
140
141    None
142
143Issues
144
145    None
146
147Sample Code
148
149    /* Allocate space to hold the pixel data */
150    const GLvoid* pixels = malloc(width * height * 4);
151
152    /* Bind the framebuffer object to be read */
153    glBindFramebuffer(GL_READ_FRAMEBUFFER, framebuffer);
154
155    /* Enable row order reversal */
156    glPixelStore(GL_PACK_REVERSE_ROW_ORDER_ANGLE, TRUE);
157
158    /* The pixel data stored in pixels will be in top-down order, ready for
159     * use with a windowing system API that expects this order.
160     */
161    glReadPixels(x, y, width, height, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
162
163Revision History
164
165    Revision 1, 2011/11/22 (Brian Salomon)
166      - First version
167    Revision 2, 2012/02/22 (dgkoch)
168      - prepare for publishing
169