glReadPixels(3gl)

1GLREADPIXELS(3G)                                              GLREADPIXELS(3G)
2
3
4

NAME

6       glReadPixels - read a block of pixels from the frame buffer
7
8

C SPECIFICATION

10       void glReadPixels( GLint x,
11                          GLint y,
12                          GLsizei width,
13                          GLsizei height,
14                          GLenum format,
15                          GLenum type,
16                          GLvoid *pixels )
17
18       delim $$
19

PARAMETERS

21       x, y Specify  the  window  coordinates  of the first pixel that is read
22            from the frame buffer.  This location is the lower left corner  of
23            a rectangular block of pixels.
24
25       width, height
26            Specify  the  dimensions of the pixel rectangle.  width and height
27            of one correspond to a single pixel.
28
29       format
30            Specifies the  of the pixel data.  The following  symbolic  values
31            are        accepted:       GL_COLOR_INDEX,       GL_STENCIL_INDEX,
32            GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE,  GL_ALPHA,  GL_RGB,
33            GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
34
35       type Specifies  the  data  type  of  the  pixel  data.   Must be one of
36            GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT,
37            GL_UNSIGNED_INT,    GL_INT,    GL_FLOAT,   GL_UNSIGNED_BYTE_3_3_2,
38            GL_UNSIGNED_BYTE_2_3_3_REV,               GL_UNSIGNED_SHORT_5_6_5,
39            GL_UNSIGNED_SHORT_5_6_5_REV,            GL_UNSIGNED_SHORT_4_4_4_4,
40            GL_UNSIGNED_SHORT_4_4_4_4_REV,          GL_UNSIGNED_SHORT_5_5_5_1,
41            GL_UNSIGNED_SHORT_1_5_5_5_REV,            GL_UNSIGNED_INT_8_8_8_8,
42            GL_UNSIGNED_INT_8_8_8_8_REV,    GL_UNSIGNED_INT_10_10_10_2,     or
43            GL_UNSIGNED_INT_2_10_10_10_REV.
44
45       pixels
46            Returns the pixel data.
47

DESCRIPTION

49       glReadPixels  returns  pixel  data from the frame buffer, starting with
50       the pixel whose lower left corner is at location (x,  y),  into  client
51       memory  starting  at  location  pixels.  Several parameters control the
52       processing of the pixel data before it is placed  into  client  memory.
53       These   parameters   are   set   with   three  commands:  glPixelStore,
54       glPixelTransfer, and glPixelMap.  This  reference  page  describes  the
55       effects  on  glReadPixels of most, but not all of the parameters speci‐
56       fied by these three commands.
57
58       When the GL_ARB_imaging extension is supported, the pixel data  may  be
59       processed  by additional operations including color table lookup, color
60       matrix transformations, convolutions, histograms and minimum  and  max‐
61       imun pixel value computations.
62
63       glReadPixels  returns  values from each pixel with lower left corner at
64       (x + $i$, y + $j$) for 0 ≤ $i$ < width and 0  ≤  $j$  <  height.   This
65       pixel  is  said  to  be  the  $i$th pixel in the $j$th row.  Pixels are
66       returned in row order from the lowest to the highest row, left to right
67       in each row.
68
69       format  specifies  the   for the returned pixel values; accepted values
70       are:
71
72       GL_COLOR_INDEX
73                 Color indices are read from  the  color  buffer  selected  by
74                 glReadBuffer.   Each  index  is  converted  to  fixed  point,
75                 shifted left or right depending on  the  value  and  sign  of
76                 GL_INDEX_SHIFT,    and    added   to   GL_INDEX_OFFSET.    If
77                 GL_MAP_COLOR is GL_TRUE, indices are replaced by  their  map‐
78                 pings in the table GL_PIXEL_MAP_I_TO_I.
79
80       GL_STENCIL_INDEX
81                 Stencil  values are read from the stencil buffer.  Each index
82                 is converted to fixed point, shifted left or right  depending
83                 on  the  value  and  sign  of  GL_INDEX_SHIFT,  and  added to
84                 GL_INDEX_OFFSET.  If GL_MAP_STENCIL is GL_TRUE,  indices  are
85                 replaced by their mappings in the table GL_PIXEL_MAP_S_TO_S.
86
87       GL_DEPTH_COMPONENT
88                 Depth  values are read from the depth buffer.  Each component
89                 is converted to floating point such that  the  minimum  depth
90                 value maps to 0 and the maximum value maps to 1.  Each compo‐
91                 nent  is  then  multiplied  by   GL_DEPTH_SCALE,   added   to
92                 GL_DEPTH_BIAS, and finally clamped to the range [0,1].
93
94       GL_RED
95
96       GL_GREEN
97
98       GL_BLUE
99
100       GL_ALPHA
101
102       GL_RGB
103
104       GL_BGR
105
106       GL_RGBA
107
108       GL_BGRA
109
110       GL_LUMINANCE
111
112       GL_LUMINANCE_ALPHA
113                 Processing  differs  depending on whether color buffers store
114                 color indices or RGBA color components.  If color indices are
115                 stored,  they  are  read  from  the  color buffer selected by
116                 glReadBuffer.   Each  index  is  converted  to  fixed  point,
117                 shifted  left  or  right  depending  on the value and sign of
118                 GL_INDEX_SHIFT, and added to  GL_INDEX_OFFSET.   Indices  are
119                 then  replaced  by  the  red,  green,  blue, and alpha values
120                 obtained  by   indexing   the   tables   GL_PIXEL_MAP_I_TO_R,
121                 GL_PIXEL_MAP_I_TO_G,         GL_PIXEL_MAP_I_TO_B,         and
122                 GL_PIXEL_MAP_I_TO_A.  Each table must be of size $2  sup  n$,
123                 but  $n$  may  be  different for different tables.  Before an
124                 index is used to look up a value in a table of  size  $2  sup
125                 n$, it must be masked against $2 sup n - 1$.
126
127                 If  RGBA  color  components  are stored in the color buffers,
128                 they are read from the color buffer selected by glReadBuffer.
129                 Each color component is converted to floating point such that
130                 zero intensity maps to 0.0 and full intensity  maps  to  1.0.
131                 Each  component is then multiplied by GL_c_SCALE and added to
132                 GL_c_BIAS, where c is RED, GREEN, BLUE, or  ALPHA.   Finally,
133                 if  GL_MAP_COLOR is GL_TRUE, each component is clamped to the
134                 range [0, 1], scaled to the size of its corresponding  table,
135                 and   is   then   replaced   by  its  mapping  in  the  table
136                 GL_PIXEL_MAP_c_TO_c, where c is R, G, B, or A.
137
138                 Unneeded data is then discarded.  For  example,  GL_RED  dis‐
139                 cards  the  green,  blue,  and alpha components, while GL_RGB
140                 discards only the alpha component.  GL_LUMINANCE  computes  a
141                 single-component value as the sum of the red, green, and blue
142                 components, and GL_LUMINANCE_ALPHA does the same, while keep‐
143                 ing alpha as a second value.  The final values are clamped to
144                 the range [0, 1].
145
146       The shift, scale, bias, and lookup factors just described are all spec‐
147       ified by
148       glPixelTransfer.  The lookup table contents themselves are specified by
149       glPixelMap.
150
151       Finally, the indices or components are converted to  the  proper  ,  as
152       specified by type.  If format is GL_COLOR_INDEX or GL_STENCIL_INDEX and
153       type is not GL_FLOAT, each index is masked with the mask value given in
154       the  following  table.  If type is GL_FLOAT, then each integer index is
155       converted to single-precision floating-point .
156
157       If format is  GL_RED,  GL_GREEN,  GL_BLUE,  GL_ALPHA,  GL_RGB,  GL_BGR,
158       GL_RGBA,  GL_BGRA,  GL_LUMINANCE, or GL_LUMINANCE_ALPHA and type is not
159       GL_FLOAT, each component is multiplied by the multiplier shown  in  the
160       following table.  If type is GL_FLOAT, then each component is passed as
161       is (or converted to the client's single-precision floating-point  if it
162       is different from the one used by the GL).
163
164            ──────────────────────────────────────────────────────────────
165            type                 index mask       component conversion
166            ──────────────────────────────────────────────────────────────
167            GL_UNSIGNED_BYTE    $2"^"8 - 1$         $(2"^"8 - 1)  c$
168            GL_BYTE             $2"^"7 - 1$    $[(2"^"8 - 1) c - 1] / 2$
169            GL_BITMAP               $1$                   $1$
170            GL_UNSIGNED_SHORT   $2"^"16 - 1$        $(2"^"16 - 1) c$
171            GL_SHORT            $2"^"15 - 1$   $[(2"^"16 - 1) c - 1] / 2$
172            GL_UNSIGNED_INT     $2"^"32 - 1$        $(2"^"32 - 1) c$
173            GL_INT              $2"^"31 - 1$   $[(2"^"32 - 1) c - 1] / 2$
174            GL_FLOAT                none                  $c$
175            ──────────────────────────────────────────────────────────────
176
177       Return   values  are  placed  in  memory  as  follows.   If  format  is
178       GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN,
179       GL_BLUE,  GL_ALPHA, or GL_LUMINANCE, a single value is returned and the
180       data for the $i$th pixel  in  the  $j$th  row  is  placed  in  location
181       $(j)~"width"~+~i$.   GL_RGB and GL_BGR return three values, GL_RGBA and
182       GL_BGRA return four values, and GL_LUMINANCE_ALPHA returns  two  values
183       for each pixel, with all values corresponding to a single pixel occupy‐
184       ing  contiguous  space  in   pixels.    Storage   parameters   set   by
185       glPixelStore,  such as GL_PACK_LSB_FIRST and GL_PACK_SWAP_BYTES, affect
186       the way that data is written  into  memory.   See  glPixelStore  for  a
187       description.
188

NOTES

190       Values  for pixels that lie outside the window connected to the current
191       GL context are undefined.
192
193       If an error is generated, no change is made to the contents of pixels.
194

ERRORS

196       GL_INVALID_ENUM is generated if format  or  type  is  not  an  accepted
197       value.
198
199       GL_INVALID_ENUM  is  generated  if  type is GL_BITMAP and format is not
200       GL_COLOR_INDEX or GL_STENCIL_INDEX.
201
202       GL_INVALID_VALUE is generated if either width or height is negative.
203
204       GL_INVALID_OPERATION is generated if format is GL_COLOR_INDEX  and  the
205       color buffers store RGBA color components.
206
207       GL_INVALID_OPERATION  is  generated  if  format is GL_STENCIL_INDEX and
208       there is no stencil buffer.
209
210       GL_INVALID_OPERATION is generated if format is  GL_DEPTH_COMPONENT  and
211       there is no depth buffer.
212
213       GL_INVALID_OPERATION  is  generated if glReadPixels is executed between
214       the execution of glBegin and the corresponding execution of glEnd.
215
216       GL_INVALID_OPERATION   is    generated    if    type    is    one    of
217       GL_UNSIGNED_BYTE_3_3_2,                     GL_UNSIGNED_BYTE_2_3_3_REV,
218       GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and  format  is
219       not GL_RGB.
220
221       GL_INVALID_OPERATION    is    generated    if    type    is    one   of
222       GL_UNSIGNED_SHORT_4_4_4_4,               GL_UNSIGNED_SHORT_4_4_4_4_REV,
223       GL_UNSIGNED_SHORT_5_5_5_1,               GL_UNSIGNED_SHORT_1_5_5_5_REV,
224       GL_UNSIGNED_INT_8_8_8_8,                   GL_UNSIGNED_INT_8_8_8_8_REV,
225       GL_UNSIGNED_INT_10_10_10_2,  or GL_UNSIGNED_INT_2_10_10_10_REV and for‐
226       mat is neither GL_RGBA nor GL_BGRA.
227
228       The formats  GL_BGR,  and  GL_BGRA  and  types  GL_UNSIGNED_BYTE_3_3_2,
229       GL_UNSIGNED_BYTE_2_3_3_REV,                    GL_UNSIGNED_SHORT_5_6_5,
230       GL_UNSIGNED_SHORT_5_6_5_REV,                 GL_UNSIGNED_SHORT_4_4_4_4,
231       GL_UNSIGNED_SHORT_4_4_4_4_REV,               GL_UNSIGNED_SHORT_5_5_5_1,
232       GL_UNSIGNED_SHORT_1_5_5_5_REV,                 GL_UNSIGNED_INT_8_8_8_8,
233       GL_UNSIGNED_INT_8_8_8_8_REV,       GL_UNSIGNED_INT_10_10_10_2,      and
234       GL_UNSIGNED_INT_2_10_10_10_REV are available only if the GL version  is
235       1.2 or greater.
236

ASSOCIATED GETS

238       glGet with argument GL_INDEX_MODE
239