1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
2 <!-- saved from url=(0013)about:internet -->
3 <?xml-stylesheet type=
"text/xsl" href=
"mathml.xsl"?><html xmlns=
"http://www.w3.org/1999/xhtml" xmlns:
pref=
"http://www.w3.org/2002/Math/preference" pref:
renderer=
"mathplayer-dl"><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" /><title>glReadPixels
</title><meta name=
"generator" content=
"DocBook XSL Stylesheets V1.73.2" /></head><body><div class=
"refentry" lang=
"en" xml:
lang=
"en"><a id=
"glReadPixels"></a><div class=
"titlepage"></div><div class=
"refnamediv"><h2>Name
</h2><p>glReadPixels — read a block of pixels from the frame buffer
</p></div><div class=
"refsynopsisdiv"><h2>C Specification
</h2><div class=
"funcsynopsis"><table border=
"0" summary=
"Function synopsis" cellspacing=
"0" cellpadding=
"0"><tr><td><code class=
"funcdef">void
<b class=
"fsfunc">glReadPixels
</b>(
</code></td><td>GLint
</td><td><var class=
"pdparam">x
</var>,
</td></tr><tr><td> </td><td>GLint
</td><td><var class=
"pdparam">y
</var>,
</td></tr><tr><td> </td><td>GLsizei
</td><td><var class=
"pdparam">width
</var>,
</td></tr><tr><td> </td><td>GLsizei
</td><td><var class=
"pdparam">height
</var>,
</td></tr><tr><td> </td><td>GLenum
</td><td><var class=
"pdparam">format
</var>,
</td></tr><tr><td> </td><td>GLenum
</td><td><var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>GLvoid *
</td><td><var class=
"pdparam">data
</var><code>)
</code>;
</td></tr></table></div></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"parameters"></a><h2>Parameters
</h2><div class=
"variablelist"><dl><dt><span class=
"term"><em class=
"parameter"><code>x
</code></em>,
</span><span class=
"term"><em class=
"parameter"><code>y
</code></em></span></dt><dd><p>
4 Specify the window coordinates of the first pixel
5 that is read from the frame buffer.
6 This location is the lower left corner of a rectangular block of pixels.
7 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>width
</code></em>,
</span><span class=
"term"><em class=
"parameter"><code>height
</code></em></span></dt><dd><p>
8 Specify the dimensions of the pixel rectangle.
9 <em class=
"parameter"><code>width
</code></em> and
<em class=
"parameter"><code>height
</code></em> of one correspond to a single pixel.
10 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>format
</code></em></span></dt><dd><p>
11 Specifies the format of the pixel data.
12 The following symbolic values are accepted:
13 <code class=
"constant">GL_COLOR_INDEX
</code>,
14 <code class=
"constant">GL_STENCIL_INDEX
</code>,
15 <code class=
"constant">GL_DEPTH_COMPONENT
</code>,
16 <code class=
"constant">GL_RED
</code>,
17 <code class=
"constant">GL_GREEN
</code>,
18 <code class=
"constant">GL_BLUE
</code>,
19 <code class=
"constant">GL_ALPHA
</code>,
20 <code class=
"constant">GL_RGB
</code>,
21 <code class=
"constant">GL_BGR
</code>,
22 <code class=
"constant">GL_RGBA
</code>,
23 <code class=
"constant">GL_BGRA
</code>,
24 <code class=
"constant">GL_LUMINANCE
</code>, and
25 <code class=
"constant">GL_LUMINANCE_ALPHA
</code>.
26 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>type
</code></em></span></dt><dd><p>
27 Specifies the data type of the pixel data.
29 <code class=
"constant">GL_UNSIGNED_BYTE
</code>,
30 <code class=
"constant">GL_BYTE
</code>,
31 <code class=
"constant">GL_BITMAP
</code>,
32 <code class=
"constant">GL_UNSIGNED_SHORT
</code>,
33 <code class=
"constant">GL_SHORT
</code>,
34 <code class=
"constant">GL_UNSIGNED_INT
</code>,
35 <code class=
"constant">GL_INT
</code>,
36 <code class=
"constant">GL_FLOAT
</code>,
37 <code class=
"constant">GL_UNSIGNED_BYTE_3_3_2
</code>,
38 <code class=
"constant">GL_UNSIGNED_BYTE_2_3_3_REV
</code>,
39 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5
</code>,
40 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5_REV
</code>,
41 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4
</code>,
42 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4_REV
</code>,
43 <code class=
"constant">GL_UNSIGNED_SHORT_5_5_5_1
</code>,
44 <code class=
"constant">GL_UNSIGNED_SHORT_1_5_5_5_REV
</code>,
45 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8
</code>,
46 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8_REV
</code>,
47 <code class=
"constant">GL_UNSIGNED_INT_10_10_10_2
</code>, or
48 <code class=
"constant">GL_UNSIGNED_INT_2_10_10_10_REV
</code>.
49 </p></dd><dt><span class=
"term"><em class=
"parameter"><code>data
</code></em></span></dt><dd><p>
50 Returns the pixel data.
51 </p></dd></dl></div></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"description"></a><h2>Description
</h2><p>
52 <code class=
"function">glReadPixels
</code> returns pixel data from the frame buffer,
53 starting with the pixel whose lower left corner
54 is at location (
<em class=
"parameter"><code>x
</code></em>,
<em class=
"parameter"><code>y
</code></em>),
55 into client memory starting at location
<em class=
"parameter"><code>data
</code></em>.
56 Several parameters control the processing of the pixel data before
57 it is placed into client memory.
58 These parameters are set with three commands:
59 <a class=
"citerefentry" href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a>,
60 <a class=
"citerefentry" href=
"glPixelTransfer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelTransfer
</span></span></a>, and
61 <a class=
"citerefentry" href=
"glPixelMap.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelMap
</span></span></a>.
62 This reference page describes the effects on
<code class=
"function">glReadPixels
</code> of most,
63 but not all of the parameters specified by these three commands.
65 If a non-zero named buffer object is bound to the
<code class=
"constant">GL_PIXEL_PACK_BUFFER
</code> target
66 (see
<a class=
"citerefentry" href=
"glBindBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glBindBuffer
</span></span></a>) while a block of pixels is
67 requested,
<em class=
"parameter"><code>data
</code></em> is treated as a byte offset into the buffer object's data store
68 rather than a pointer to client memory.
70 When the
<code class=
"code">ARB_imaging
</code> extension is supported, the pixel data may
71 be processed by additional operations including color table lookup,
72 color matrix transformations, convolutions, histograms, and minimum and
73 maximum pixel value computations.
75 <code class=
"function">glReadPixels
</code> returns values from each pixel with lower left corner at
76 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
78 <mml:mfenced open=
"(" close=
")">
80 <mml:mi mathvariant=
"italic">x
</mml:mi>
82 <mml:mi mathvariant=
"italic">i
</mml:mi>
85 <mml:mi mathvariant=
"italic">y
</mml:mi>
87 <mml:mi mathvariant=
"italic">j
</mml:mi>
92 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
96 <mml:mo><=
</mml:mo>
97 <mml:mi mathvariant=
"italic">i
</mml:mi>
99 <mml:mi mathvariant=
"italic">width
</mml:mi>
103 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
107 <mml:mo><=
</mml:mo>
108 <mml:mi mathvariant=
"italic">j
</mml:mi>
109 <mml:mo><</mml:mo>
110 <mml:mi mathvariant=
"italic">height
</mml:mi>
113 This pixel is said to be the
114 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math>th
116 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math>th
118 Pixels are returned in row order from the lowest to the highest row,
119 left to right in each row.
121 <em class=
"parameter"><code>format
</code></em> specifies the format for the returned pixel values;
123 </p><div class=
"variablelist"><dl><dt><span class=
"term"><code class=
"constant">GL_COLOR_INDEX
</code></span></dt><dd><p>
124 Color indices are read from the color buffer
125 selected by
<a class=
"citerefentry" href=
"glReadBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glReadBuffer
</span></span></a>.
126 Each index is converted to fixed point,
127 shifted left or right depending on the value and sign of
<code class=
"constant">GL_INDEX_SHIFT
</code>,
128 and added to
<code class=
"constant">GL_INDEX_OFFSET
</code>.
129 If
<code class=
"constant">GL_MAP_COLOR
</code> is
<code class=
"constant">GL_TRUE
</code>,
130 indices are replaced by their mappings in the table
<code class=
"constant">GL_PIXEL_MAP_I_TO_I
</code>.
131 </p></dd><dt><span class=
"term"><code class=
"constant">GL_STENCIL_INDEX
</code></span></dt><dd><p>
132 Stencil values are read from the stencil buffer.
133 Each index is converted to fixed point,
134 shifted left or right depending on the value and sign of
<code class=
"constant">GL_INDEX_SHIFT
</code>,
135 and added to
<code class=
"constant">GL_INDEX_OFFSET
</code>.
136 If
<code class=
"constant">GL_MAP_STENCIL
</code> is
<code class=
"constant">GL_TRUE
</code>,
137 indices are replaced by their mappings in the table
<code class=
"constant">GL_PIXEL_MAP_S_TO_S
</code>.
138 </p></dd><dt><span class=
"term"><code class=
"constant">GL_DEPTH_COMPONENT
</code></span></dt><dd><p>
139 Depth values are read from the depth buffer.
140 Each component is converted to floating point such that the minimum depth
141 value maps to
0 and the maximum value maps to
1.
142 Each component is then multiplied by
<code class=
"constant">GL_DEPTH_SCALE
</code>,
143 added to
<code class=
"constant">GL_DEPTH_BIAS
</code>,
144 and finally clamped to the range
145 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
147 <mml:mfenced open=
"[" close=
"]">
152 </p></dd><dt><span class=
"term"><code class=
"constant">GL_RED
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_GREEN
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_BLUE
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_ALPHA
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_RGB
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_BGR
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_RGBA
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_BGRA
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_LUMINANCE
</code></span></dt><dd></dd><dt><span class=
"term"><code class=
"constant">GL_LUMINANCE_ALPHA
</code></span></dt><dd><p>
153 Processing differs depending on whether color buffers store color indices
154 or RGBA color components.
155 If color indices are stored,
156 they are read from the color buffer selected by
<a class=
"citerefentry" href=
"glReadBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glReadBuffer
</span></span></a>.
157 Each index is converted to fixed point,
158 shifted left or right depending on the value and sign of
<code class=
"constant">GL_INDEX_SHIFT
</code>,
159 and added to
<code class=
"constant">GL_INDEX_OFFSET
</code>.
160 Indices are then replaced by the red,
163 and alpha values obtained by indexing the tables
164 <code class=
"constant">GL_PIXEL_MAP_I_TO_R
</code>,
165 <code class=
"constant">GL_PIXEL_MAP_I_TO_G
</code>,
166 <code class=
"constant">GL_PIXEL_MAP_I_TO_B
</code>, and
167 <code class=
"constant">GL_PIXEL_MAP_I_TO_A
</code>.
168 Each table must be of size
169 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
171 <mml:msup><mml:mn>2</mml:mn>
172 <mml:mi mathvariant=
"italic">n
</mml:mi>
176 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math>
179 Before an index is used to look up a value in a table of
181 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
183 <mml:msup><mml:mn>2</mml:mn>
184 <mml:mi mathvariant=
"italic">n
</mml:mi>
187 it must be masked against
188 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
191 <mml:msup><mml:mn>2</mml:mn>
192 <mml:mi mathvariant=
"italic">n
</mml:mi>
199 If RGBA color components are stored in the color buffers,
200 they are read from the color buffer selected by
<a class=
"citerefentry" href=
"glReadBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glReadBuffer
</span></span></a>.
201 Each color component is converted to floating point such that zero intensity
202 maps to
0.0 and full intensity maps to
1.0.
203 Each component is then multiplied by
<code class=
"constant">GL_c_SCALE
</code> and
204 added to
<code class=
"constant">GL_c_BIAS
</code>,
205 where
<span class=
"emphasis"><em>c
</em></span> is RED, GREEN, BLUE, or ALPHA.
207 if
<code class=
"constant">GL_MAP_COLOR
</code> is
<code class=
"constant">GL_TRUE
</code>,
208 each component is clamped to the range
209 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
211 <mml:mfenced open=
"[" close=
"]">
216 scaled to the size of its corresponding table, and is then
217 replaced by its mapping in the table
218 <code class=
"constant">GL_PIXEL_MAP_c_TO_c
</code>,
219 where
<span class=
"emphasis"><em>c
</em></span> is R, G, B, or A.
221 Unneeded data is then discarded.
223 <code class=
"constant">GL_RED
</code> discards the green, blue, and alpha components,
224 while
<code class=
"constant">GL_RGB
</code> discards only the alpha component.
225 <code class=
"constant">GL_LUMINANCE
</code> computes a single-component value as the sum of
229 and
<code class=
"constant">GL_LUMINANCE_ALPHA
</code> does the same,
230 while keeping alpha as a second value.
231 The final values are clamped to the range
232 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
234 <mml:mfenced open=
"[" close=
"]">
239 </p></dd></dl></div><p>
243 and lookup factors just described are all specified by
244 <a class=
"citerefentry" href=
"glPixelTransfer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelTransfer
</span></span></a>.
245 The lookup table contents themselves are specified by
<a class=
"citerefentry" href=
"glPixelMap.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelMap
</span></span></a>.
247 Finally, the indices or components
248 are converted to the proper format,
249 as specified by
<em class=
"parameter"><code>type
</code></em>.
250 If
<em class=
"parameter"><code>format
</code></em> is
<code class=
"constant">GL_COLOR_INDEX
</code> or
<code class=
"constant">GL_STENCIL_INDEX
</code>
251 and
<em class=
"parameter"><code>type
</code></em> is not
<code class=
"constant">GL_FLOAT
</code>,
252 each index is masked with the mask value given in the following table.
253 If
<em class=
"parameter"><code>type
</code></em> is
<code class=
"constant">GL_FLOAT
</code>, then each integer index is converted to
254 single-precision floating-point format.
256 If
<em class=
"parameter"><code>format
</code></em> is
257 <code class=
"constant">GL_RED
</code>,
258 <code class=
"constant">GL_GREEN
</code>,
259 <code class=
"constant">GL_BLUE
</code>,
260 <code class=
"constant">GL_ALPHA
</code>,
261 <code class=
"constant">GL_RGB
</code>,
262 <code class=
"constant">GL_BGR
</code>,
263 <code class=
"constant">GL_RGBA
</code>,
264 <code class=
"constant">GL_BGRA
</code>,
265 <code class=
"constant">GL_LUMINANCE
</code>, or
266 <code class=
"constant">GL_LUMINANCE_ALPHA
</code> and
<em class=
"parameter"><code>type
</code></em> is not
<code class=
"constant">GL_FLOAT
</code>,
267 each component is multiplied by the multiplier shown in the following table.
268 If type is
<code class=
"constant">GL_FLOAT
</code>, then each component is passed as is
269 (or converted to the client's single-precision floating-point format if
270 it is different from the one used by the GL).
272 </p><div class=
"informaltable"><table border=
"1"><colgroup><col align=
"left" /><col align=
"center" /><col align=
"center" /></colgroup><thead><tr><th align=
"left">
273 <em class=
"parameter"><code>type
</code></em>
274 </th><th align=
"center"><span class=
"bold"><strong>
276 </strong></span></th><th align=
"center"><span class=
"bold"><strong>
278 </strong></span></th></tr></thead><tbody><tr><td align=
"left">
279 <code class=
"constant">GL_UNSIGNED_BYTE
</code>
280 </td><td align=
"center">
281 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
284 <mml:msup><mml:mn>2</mml:mn>
291 </td><td align=
"center">
292 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
295 <mml:mfenced open=
"(" close=
")">
297 <mml:msup><mml:mn>2</mml:mn>
305 <mml:mi mathvariant=
"italic">c
</mml:mi>
308 </td></tr><tr><td align=
"left">
309 <code class=
"constant">GL_BYTE
</code>
310 </td><td align=
"center">
311 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
314 <mml:msup><mml:mn>2</mml:mn>
321 </td><td align=
"center">
322 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
325 <mml:mfenced open=
"" close=
"">
327 <mml:mfenced open=
"(" close=
")">
329 <mml:msup><mml:mn>2</mml:mn>
337 <mml:mi mathvariant=
"italic">c
</mml:mi>
345 </td></tr><tr><td align=
"left">
346 <code class=
"constant">GL_BITMAP
</code>
347 </td><td align=
"center">
348 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
352 </td><td align=
"center">
353 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
357 </td></tr><tr><td align=
"left">
358 <code class=
"constant">GL_UNSIGNED_SHORT
</code>
359 </td><td align=
"center">
360 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
363 <mml:msup><mml:mn>2</mml:mn>
370 </td><td align=
"center">
371 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
374 <mml:mfenced open=
"(" close=
")">
376 <mml:msup><mml:mn>2</mml:mn>
384 <mml:mi mathvariant=
"italic">c
</mml:mi>
387 </td></tr><tr><td align=
"left">
388 <code class=
"constant">GL_SHORT
</code>
389 </td><td align=
"center">
390 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
393 <mml:msup><mml:mn>2</mml:mn>
400 </td><td align=
"center">
401 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
404 <mml:mfenced open=
"" close=
"">
406 <mml:mfenced open=
"(" close=
")">
408 <mml:msup><mml:mn>2</mml:mn>
416 <mml:mi mathvariant=
"italic">c
</mml:mi>
424 </td></tr><tr><td align=
"left">
425 <code class=
"constant">GL_UNSIGNED_INT
</code>
426 </td><td align=
"center">
427 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
430 <mml:msup><mml:mn>2</mml:mn>
437 </td><td align=
"center">
438 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
441 <mml:mfenced open=
"(" close=
")">
443 <mml:msup><mml:mn>2</mml:mn>
451 <mml:mi mathvariant=
"italic">c
</mml:mi>
454 </td></tr><tr><td align=
"left">
455 <code class=
"constant">GL_INT
</code>
456 </td><td align=
"center">
457 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
460 <mml:msup><mml:mn>2</mml:mn>
467 </td><td align=
"center">
468 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
471 <mml:mfenced open=
"" close=
"">
473 <mml:mfenced open=
"(" close=
")">
475 <mml:msup><mml:mn>2</mml:mn>
483 <mml:mi mathvariant=
"italic">c
</mml:mi>
491 </td></tr><tr><td align=
"left">
492 <code class=
"constant">GL_FLOAT
</code>
493 </td><td align=
"center">
495 </td><td align=
"center">
496 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">c
</mml:mi></mml:math>
497 </td></tr></tbody></table></div><p>
498 Return values are placed in memory as follows.
499 If
<em class=
"parameter"><code>format
</code></em> is
500 <code class=
"constant">GL_COLOR_INDEX
</code>,
501 <code class=
"constant">GL_STENCIL_INDEX
</code>,
502 <code class=
"constant">GL_DEPTH_COMPONENT
</code>,
503 <code class=
"constant">GL_RED
</code>,
504 <code class=
"constant">GL_GREEN
</code>,
505 <code class=
"constant">GL_BLUE
</code>,
506 <code class=
"constant">GL_ALPHA
</code>, or
507 <code class=
"constant">GL_LUMINANCE
</code>,
508 a single value is returned and the data for the
509 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math>th
511 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll"><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math>th
513 is placed in location
514 <mml:math xmlns:
mml=
"http://www.w3.org/1998/Math/MathML" overflow=
"scroll">
517 <mml:mfenced open=
"(" close=
")">
518 <mml:mi mathvariant=
"italic">j
</mml:mi>
521 <mml:mi mathvariant=
"italic">width
</mml:mi>
523 <mml:mi mathvariant=
"italic">i
</mml:mi>
526 <code class=
"constant">GL_RGB
</code> and
<code class=
"constant">GL_BGR
</code> return three values,
527 <code class=
"constant">GL_RGBA
</code> and
<code class=
"constant">GL_BGRA
</code> return four values,
528 and
<code class=
"constant">GL_LUMINANCE_ALPHA
</code> returns two values for each pixel,
529 with all values corresponding to a single pixel occupying contiguous space
530 in
<em class=
"parameter"><code>data
</code></em>.
531 Storage parameters set by
<a class=
"citerefentry" href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a>,
532 such as
<code class=
"constant">GL_PACK_LSB_FIRST
</code> and
<code class=
"constant">GL_PACK_SWAP_BYTES
</code>,
533 affect the way that data is written into memory.
534 See
<a class=
"citerefentry" href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a> for a description.
535 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"notes"></a><h2>Notes
</h2><p>
536 Values for pixels that lie outside the window
537 connected to the current GL context are undefined.
539 If an error is generated,
540 no change is made to the contents of
<em class=
"parameter"><code>data
</code></em>.
541 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"errors"></a><h2>Errors
</h2><p>
542 <code class=
"constant">GL_INVALID_ENUM
</code> is generated if
<em class=
"parameter"><code>format
</code></em> or
<em class=
"parameter"><code>type
</code></em> is not an
545 <code class=
"constant">GL_INVALID_ENUM
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is
<code class=
"constant">GL_BITMAP
</code> and
<em class=
"parameter"><code>format
</code></em> is
546 not
<code class=
"constant">GL_COLOR_INDEX
</code> or
<code class=
"constant">GL_STENCIL_INDEX
</code>.
548 <code class=
"constant">GL_INVALID_VALUE
</code> is generated if either
<em class=
"parameter"><code>width
</code></em> or
<em class=
"parameter"><code>height
</code></em> is negative.
550 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>format
</code></em> is
<code class=
"constant">GL_COLOR_INDEX
</code>
551 and the color buffers store RGBA color components.
553 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>format
</code></em> is
<code class=
"constant">GL_STENCIL_INDEX
</code>
554 and there is no stencil buffer.
556 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>format
</code></em> is
<code class=
"constant">GL_DEPTH_COMPONENT
</code>
557 and there is no depth buffer.
559 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is one of
560 <code class=
"constant">GL_UNSIGNED_BYTE_3_3_2
</code>,
561 <code class=
"constant">GL_UNSIGNED_BYTE_2_3_3_REV
</code>,
562 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5
</code>, or
563 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5_REV
</code>
564 and
<em class=
"parameter"><code>format
</code></em> is not
<code class=
"constant">GL_RGB
</code>.
566 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<em class=
"parameter"><code>type
</code></em> is one of
567 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4
</code>,
568 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4_REV
</code>,
569 <code class=
"constant">GL_UNSIGNED_SHORT_5_5_5_1
</code>,
570 <code class=
"constant">GL_UNSIGNED_SHORT_1_5_5_5_REV
</code>,
571 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8
</code>,
572 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8_REV
</code>,
573 <code class=
"constant">GL_UNSIGNED_INT_10_10_10_2
</code>, or
574 <code class=
"constant">GL_UNSIGNED_INT_2_10_10_10_REV
</code>
575 and
<em class=
"parameter"><code>format
</code></em> is neither
<code class=
"constant">GL_RGBA
</code> nor
<code class=
"constant">GL_BGRA
</code>.
577 The formats
<code class=
"constant">GL_BGR
</code>, and
<code class=
"constant">GL_BGRA
</code> and types
578 <code class=
"constant">GL_UNSIGNED_BYTE_3_3_2
</code>,
579 <code class=
"constant">GL_UNSIGNED_BYTE_2_3_3_REV
</code>,
580 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5
</code>,
581 <code class=
"constant">GL_UNSIGNED_SHORT_5_6_5_REV
</code>,
582 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4
</code>,
583 <code class=
"constant">GL_UNSIGNED_SHORT_4_4_4_4_REV
</code>,
584 <code class=
"constant">GL_UNSIGNED_SHORT_5_5_5_1
</code>,
585 <code class=
"constant">GL_UNSIGNED_SHORT_1_5_5_5_REV
</code>,
586 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8
</code>,
587 <code class=
"constant">GL_UNSIGNED_INT_8_8_8_8_REV
</code>,
588 <code class=
"constant">GL_UNSIGNED_INT_10_10_10_2
</code>, and
589 <code class=
"constant">GL_UNSIGNED_INT_2_10_10_10_REV
</code> are available only if the GL version
592 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
593 <code class=
"constant">GL_PIXEL_PACK_BUFFER
</code> target and the buffer object's data store is currently mapped.
595 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
596 <code class=
"constant">GL_PIXEL_PACK_BUFFER
</code> target and the data would be packed to the buffer
597 object such that the memory writes required would exceed the data store size.
599 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if a non-zero buffer object name is bound to the
600 <code class=
"constant">GL_PIXEL_PACK_BUFFER
</code> target and
<em class=
"parameter"><code>data
</code></em> is not evenly divisible
601 into the number of bytes needed to store in memory a datum indicated by
<em class=
"parameter"><code>type
</code></em>.
603 <code class=
"constant">GL_INVALID_OPERATION
</code> is generated if
<code class=
"function">glReadPixels
</code>
604 is executed between the execution of
<a class=
"citerefentry" href=
"glBegin.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glBegin
</span></span></a>
605 and the corresponding execution of
<a class=
"citerefentry" href=
"glEnd.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glEnd
</span></span></a>.
606 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"associatedgets"></a><h2>Associated Gets
</h2><p>
607 <a class=
"citerefentry" href=
"glGet.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glGet
</span></span></a> with argument
<code class=
"constant">GL_INDEX_MODE
</code>
609 <a class=
"citerefentry" href=
"glGet.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glGet
</span></span></a> with argument
<code class=
"constant">GL_PIXEL_PACK_BUFFER_BINDING
</code>
610 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"seealso"></a><h2>See Also
</h2><p>
611 <a class=
"citerefentry" href=
"glCopyPixels.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glCopyPixels
</span></span></a>,
612 <a class=
"citerefentry" href=
"glDrawPixels.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glDrawPixels
</span></span></a>,
613 <a class=
"citerefentry" href=
"glPixelMap.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelMap
</span></span></a>,
614 <a class=
"citerefentry" href=
"glPixelStore.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelStore
</span></span></a>,
615 <a class=
"citerefentry" href=
"glPixelTransfer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glPixelTransfer
</span></span></a>,
616 <a class=
"citerefentry" href=
"glReadBuffer.xml"><span class=
"citerefentry"><span class=
"refentrytitle">glReadBuffer
</span></span></a>
617 </p></div><div class=
"refsect1" lang=
"en" xml:
lang=
"en"><a id=
"Copyright"></a><h2>Copyright
</h2><p>
618 Copyright
<span class=
"trademark"></span>©
1991-
2006
619 Silicon Graphics, Inc. This document is licensed under the SGI
620 Free Software B License. For details, see
621 <a class=
"ulink" href=
"http://oss.sgi.com/projects/FreeB/" target=
"_top">http://oss.sgi.com/projects/FreeB/
</a>.
622 </p></div></div></body></html>