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