1GLREADPIXELS(3G) OpenGL Manual GLREADPIXELS(3G)
2
6 glReadPixels - read a block of pixels from the frame buffer
7
9 void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height,
10 GLenum format, GLenum type, GLvoid * data);
11
13 x, y
14 Specify the window coordinates of the first pixel that is read from
15 the frame buffer. This location is the lower left corner of a
16 rectangular block of pixels.
17 width, height
19 Specify the dimensions of the pixel rectangle. width and height of
20 one correspond to a single pixel.
21 format
23 Specifies the format of the pixel data. The following symbolic
24 values are accepted: GL_STENCIL_INDEX, GL_DEPTH_COMPONENT,
25 GL_DEPTH_STENCIL, GL_RED, GL_GREEN, GL_BLUE, GL_RGB, GL_BGR,
26 GL_RGBA, and GL_BGRA.
27 type
29 Specifies the data type of the pixel data. Must be one of
30 GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
31 GL_UNSIGNED_INT, GL_INT, GL_HALF_FLOAT, GL_FLOAT,
32 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
33 GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV,
34 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
35 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
36 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
37 GL_UNSIGNED_INT_10_10_10_2, GL_UNSIGNED_INT_2_10_10_10_REV,
38 GL_UNSIGNED_INT_24_8, GL_UNSIGNED_INT_10F_11F_11F_REV,
39 GL_UNSIGNED_INT_5_9_9_9_REV, or GL_FLOAT_32_UNSIGNED_INT_24_8_REV.
40 data
42 Returns the pixel data.
43
45 glReadPixels returns pixel data from the frame buffer, starting with
46 the pixel whose lower left corner is at location (x, y), into client
47 memory starting at location data. Several parameters control the
48 processing of the pixel data before it is placed into client memory.
49 These parameters are set with glPixelStore(). This reference page
50 describes the effects on glReadPixels of most, but not all of the
51 parameters specified by these three commands.
52 If a non-zero named buffer object is bound to the GL_PIXEL_PACK_BUFFER
54 target (see glBindBuffer()) while a block of pixels is requested, data
55 is treated as a byte offset into the buffer object's data store rather
56 than a pointer to client memory.
57 glReadPixels returns values from each pixel with lower left corner at x
59 + i y + j for 0 <= i < width and 0 <= j < height. This pixel is said to
60 be the ith pixel in the jth row. Pixels are returned in row order from
61 the lowest to the highest row, left to right in each row.
62 format specifies the format for the returned pixel values; accepted
64 values are:
65 GL_STENCIL_INDEX
67 Stencil values are read from the stencil buffer. Each index is
68 converted to fixed point, shifted left or right depending on the
69 value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If
70 GL_MAP_STENCIL is GL_TRUE, indices are replaced by their mappings
71 in the table GL_PIXEL_MAP_S_TO_S.
72 GL_DEPTH_COMPONENT
74 Depth values are read from the depth buffer. Each component is
75 converted to floating point such that the minimum depth value maps
76 to 0 and the maximum value maps to 1. Each component is then
77 multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and finally
78 clamped to the range 0 1.
79 GL_DEPTH_STENCIL
81 Values are taken from both the depth and stencil buffers. The type
82 parameter must be GL_UNSIGNED_INT_24_8 or
83 GL_FLOAT_32_UNSIGNED_INT_24_8_REV.
84 GL_RED
86 GL_GREEN
88 GL_BLUE
90 GL_RGB
92 GL_BGR
94 GL_RGBA
96 GL_BGRA
98 Finally, the indices or components are converted to the proper format,
100 as specified by type. If format is GL_STENCIL_INDEX and type is not
101 GL_FLOAT, each index is masked with the mask value given in the
102 following table. If type is GL_FLOAT, then each integer index is
103 converted to single-precision floating-point format.
104 If format is GL_RED, GL_GREEN, GL_BLUE, GL_RGB, GL_BGR, GL_RGBA, or
106 GL_BGRA and type is not GL_FLOAT, each component is multiplied by the
107 multiplier shown in the following table. If type is GL_FLOAT, then each
108 component is passed as is (or converted to the client's
109 single-precision floating-point format if it is different from the one
110 used by the GL).
111 ┌──────────────────────────────────┬────────────────────────────────────┬────────────────────────────────────────────────────┐
113 │type │ │ │
114 │ │ Index │ Component │
115 │ │ Mask │ Conversion │
116 │ │ │ │
117 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
118 │GL_UNSIGNED_BYTE │ 2 │ 2 │
119 │ │ 8 │ 8 │
120 │ │ │ │
121 │ │ - │ - │
122 │ │ 1 │ 1 │
123 │ │ │ │
124 │ │ │ │
125 │ │ │ │
126 │ │ │ c │
127 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
128 │GL_BYTE │ 2 │ 2 │
129 │ │ 7 │ 8 │
130 │ │ │ │
131 │ │ - │ - │
132 │ │ 1 │ 1 │
133 │ │ │ │
134 │ │ │ │
135 │ │ │ │
136 │ │ │ c │
137 │ │ │ - │
138 │ │ │ 1 │
139 │ │ │ │
140 │ │ │ │
141 │ │ │ 2 │
142 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
143 │GL_UNSIGNED_SHORT │ 2 │ 2 │
144 │ │ 16 │ 16 │
145 │ │ │ │
146 │ │ - │ - │
147 │ │ 1 │ 1 │
148 │ │ │ │
149 │ │ │ │
150 │ │ │ │
151 │ │ │ c │
152 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
153 │GL_SHORT │ 2 │ 2 │
154 │ │ 15 │ 16 │
155 │ │ │ │
156 │ │ - │ - │
157 │ │ 1 │ 1 │
158 │ │ │ │
159 │ │ │ │
160 │ │ │ │
161 │ │ │ c │
162 │ │ │ - │
163 │ │ │ 1 │
164 │ │ │ │
165 │ │ │ │
166 │ │ │ 2 │
167 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
168 │GL_UNSIGNED_INT │ 2 │ 2 │
169 │ │ 32 │ 32 │
170 │ │ │ │
171 │ │ - │ - │
172 │ │ 1 │ 1 │
173 │ │ │ │
174 │ │ │ │
175 │ │ │ │
176 │ │ │ c │
177 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
178 │GL_INT │ 2 │ 2 │
179 │ │ 31 │ 32 │
180 │ │ │ │
181 │ │ - │ - │
182 │ │ 1 │ 1 │
183 │ │ │ │
184 │ │ │ │
185 │ │ │ │
186 │ │ │ c │
187 │ │ │ - │
188 │ │ │ 1 │
189 │ │ │ │
190 │ │ │ │
191 │ │ │ 2 │
192 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
193 │GL_HALF_FLOAT │ none │ c │
194 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
195 │GL_FLOAT │ none │ c │
196 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
197 │GL_UNSIGNED_BYTE_3_3_2 │ 2 │ 2 │
198 │ │ N │ N │
199 │ │ │ │
200 │ │ - │ - │
201 │ │ 1 │ 1 │
202 │ │ │ │
203 │ │ │ │
204 │ │ │ │
205 │ │ │ c │
206 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
207 │GL_UNSIGNED_BYTE_2_3_3_REV │ 2 │ 2 │
208 │ │ N │ N │
209 │ │ │ │
210 │ │ - │ - │
211 │ │ 1 │ 1 │
212 │ │ │ │
213 │ │ │ │
214 │ │ │ │
215 │ │ │ c │
216 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
217 │GL_UNSIGNED_SHORT_5_6_5 │ 2 │ 2 │
218 │ │ N │ N │
219 │ │ │ │
220 │ │ - │ - │
221 │ │ 1 │ 1 │
222 │ │ │ │
223 │ │ │ │
224 │ │ │ │
225 │ │ │ c │
226 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
227 │GL_UNSIGNED_SHORT_5_6_5_REV │ 2 │ 2 │
228 │ │ N │ N │
229 │ │ │ │
230 │ │ - │ - │
231 │ │ 1 │ 1 │
232 │ │ │ │
233 │ │ │ │
234 │ │ │ │
235 │ │ │ c │
236 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
237 │GL_UNSIGNED_SHORT_4_4_4_4 │ 2 │ 2 │
238 │ │ N │ N │
239 │ │ │ │
240 │ │ - │ - │
241 │ │ 1 │ 1 │
242 │ │ │ │
243 │ │ │ │
244 │ │ │ │
245 │ │ │ c │
246 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
247 │GL_UNSIGNED_SHORT_4_4_4_4_REV │ 2 │ 2 │
248 │ │ N │ N │
249 │ │ │ │
250 │ │ - │ - │
251 │ │ 1 │ 1 │
252 │ │ │ │
253 │ │ │ │
254 │ │ │ │
255 │ │ │ c │
256 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
257 │GL_UNSIGNED_SHORT_5_5_5_1 │ 2 │ 2 │
258 │ │ N │ N │
259 │ │ │ │
260 │ │ - │ - │
261 │ │ 1 │ 1 │
262 │ │ │ │
263 │ │ │ │
264 │ │ │ │
265 │ │ │ c │
266 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
267 │GL_UNSIGNED_SHORT_1_5_5_5_REV │ 2 │ 2 │
268 │ │ N │ N │
269 │ │ │ │
270 │ │ - │ - │
271 │ │ 1 │ 1 │
272 │ │ │ │
273 │ │ │ │
274 │ │ │ │
275 │ │ │ c │
276 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
277 │GL_UNSIGNED_INT_8_8_8_8 │ 2 │ 2 │
278 │ │ N │ N │
279 │ │ │ │
280 │ │ - │ - │
281 │ │ 1 │ 1 │
282 │ │ │ │
283 │ │ │ │
284 │ │ │ │
285 │ │ │ c │
286 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
287 │GL_UNSIGNED_INT_8_8_8_8_REV │ 2 │ 2 │
288 │ │ N │ N │
289 │ │ │ │
290 │ │ - │ - │
291 │ │ 1 │ 1 │
292 │ │ │ │
293 │ │ │ │
294 │ │ │ │
295 │ │ │ c │
296 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
297 │GL_UNSIGNED_INT_10_10_10_2 │ 2 │ 2 │
298 │ │ N │ N │
299 │ │ │ │
300 │ │ - │ - │
301 │ │ 1 │ 1 │
302 │ │ │ │
303 │ │ │ │
304 │ │ │ │
305 │ │ │ c │
306 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
307 │GL_UNSIGNED_INT_2_10_10_10_REV │ 2 │ 2 │
308 │ │ N │ N │
309 │ │ │ │
310 │ │ - │ - │
311 │ │ 1 │ 1 │
312 │ │ │ │
313 │ │ │ │
314 │ │ │ │
315 │ │ │ c │
316 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
317 │GL_UNSIGNED_INT_24_8 │ 2 │ 2 │
318 │ │ N │ N │
319 │ │ │ │
320 │ │ - │ - │
321 │ │ 1 │ 1 │
322 │ │ │ │
323 │ │ │ │
324 │ │ │ │
325 │ │ │ c │
326 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
327 │GL_UNSIGNED_INT_10F_11F_11F_REV │ -- │ Special │
328 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
329 │GL_UNSIGNED_INT_5_9_9_9_REV │ -- │ Special │
330 ├──────────────────────────────────┼────────────────────────────────────┼────────────────────────────────────────────────────┤
331 │GL_FLOAT_32_UNSIGNED_INT_24_8_REV │ none │ c (Depth Only) │
332 └──────────────────────────────────┴────────────────────────────────────┴────────────────────────────────────────────────────┘
333 Return values are placed in memory as follows. If format is
335 GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, or GL_BLUE, a
336 single value is returned and the data for the ith pixel in the jth row
337 is placed in location j width + i. GL_RGB and GL_BGR return three
338 values, GL_RGBA and GL_BGRA return four values for each pixel, with all
339 values corresponding to a single pixel occupying contiguous space in
340 data. Storage parameters set by glPixelStore(), such as
341 GL_PACK_LSB_FIRST and GL_PACK_SWAP_BYTES, affect the way that data is
342 written into memory. See glPixelStore() for a description.
343
345 Values for pixels that lie outside the window connected to the current
346 GL context are undefined.
347 If an error is generated, no change is made to the contents of data.
349
351 GL_INVALID_ENUM is generated if format or type is not an accepted
352 value.
353 GL_INVALID_VALUE is generated if either width or height is negative.
355 GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and
357 there is no stencil buffer.
358 GL_INVALID_OPERATION is generated if format is GL_DEPTH_COMPONENT and
360 there is no depth buffer.
361 GL_INVALID_OPERATION is generated if format is GL_DEPTH_STENCIL and
363 there is no depth buffer or if there is no stencil buffer.
364 GL_INVALID_ENUM is generated if format is GL_DEPTH_STENCIL and type is
366 not GL_UNSIGNED_INT_24_8 or GL_FLOAT_32_UNSIGNED_INT_24_8_REV.
367 GL_INVALID_OPERATION is generated if type is one of
369 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
370 GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format is
371 not GL_RGB.
372 GL_INVALID_OPERATION is generated if type is one of
374 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
375 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
376 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
377 GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and
378 format is neither GL_RGBA nor GL_BGRA.
379 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
381 bound to the GL_PIXEL_PACK_BUFFER target and the buffer object's data
382 store is currently mapped.
383 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
385 bound to the GL_PIXEL_PACK_BUFFER target and the data would be packed
386 to the buffer object such that the memory writes required would exceed
387 the data store size.
388 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
390 bound to the GL_PIXEL_PACK_BUFFER target and data is not evenly
391 divisible into the number of bytes needed to store in memory a datum
392 indicated by type.
393 GL_INVALID_OPERATION is generated if GL_READ_FRAMEBUFFER_BINDING is
395 non-zero, the read framebuffer is complete, and the value of
396 GL_SAMPLE_BUFFERS for the read framebuffer is greater than zero.
397
399 glGet() with argument GL_INDEX_MODE
400 glGet() with argument GL_PIXEL_PACK_BUFFER_BINDING
402
404 glPixelStore(), glReadBuffer()
405
407 Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
408 under the SGI Free Software B License. For details, see
409 http://oss.sgi.com/projects/FreeB/.
410
412 opengl.org
413opengl.org 06/10/2014 GLREADPIXELS(3G)