HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man2 / xhtml / glReadPixels.xml
CommitLineData
7faf1d71
AW		 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.
28 Must be one of
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.
64 </p><p>
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.
69 </p><p>
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.
74 </p><p>
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">
77
78 <mml:mfenced open="(" close=")">
79 <mml:mrow>
80 <mml:mi mathvariant="italic">x</mml:mi>
81 <mml:mo>+</mml:mo>
82 <mml:mi mathvariant="italic">i</mml:mi>
83 </mml:mrow>
84 <mml:mrow>
85 <mml:mi mathvariant="italic">y</mml:mi>
86 <mml:mo>+</mml:mo>
87 <mml:mi mathvariant="italic">j</mml:mi>
88 </mml:mrow>
89 </mml:mfenced>
90 </mml:math>
91 for
92 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
93
94 <mml:mrow>
95 <mml:mn>0</mml:mn>
96 <mml:mo>&lt;=</mml:mo>
97 <mml:mi mathvariant="italic">i</mml:mi>
98 <mml:mo>&lt;</mml:mo>
99 <mml:mi mathvariant="italic">width</mml:mi>
100 </mml:mrow>
101 </mml:math>
102 and
103 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
104
105 <mml:mrow>
106 <mml:mn>0</mml:mn>
107 <mml:mo>&lt;=</mml:mo>
108 <mml:mi mathvariant="italic">j</mml:mi>
109 <mml:mo>&lt;</mml:mo>
110 <mml:mi mathvariant="italic">height</mml:mi>
111 </mml:mrow>
112 </mml:math>.
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
115 pixel in the
116 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">j</mml:mi></mml:math>th
117 row.
118 Pixels are returned in row order from the lowest to the highest row,
119 left to right in each row.
120 </p><p>
121 <em class="parameter"><code>format</code></em> specifies the format for the returned pixel values;
122 accepted values are:
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">
146
147 <mml:mfenced open="[" close="]">
148 <mml:mn>0</mml:mn>
149 <mml:mn>1</mml:mn>
150 </mml:mfenced>
151 </mml:math>.
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,
161 green,
162 blue,
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">
170
171 <mml:msup><mml:mn>2</mml:mn>
172 <mml:mi mathvariant="italic">n</mml:mi>
173 </mml:msup>
174 </mml:math>,
175 but
176 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
177 may be different for
178 different tables.
179 Before an index is used to look up a value in a table of
180 size
181 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
182
183 <mml:msup><mml:mn>2</mml:mn>
184 <mml:mi mathvariant="italic">n</mml:mi>
185 </mml:msup>
186 </mml:math>,
187 it must be masked against
188 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
189
190 <mml:mrow>
191 <mml:msup><mml:mn>2</mml:mn>
192 <mml:mi mathvariant="italic">n</mml:mi>
193 </mml:msup>
194 <mml:mo>-</mml:mo>
195 <mml:mn>1</mml:mn>
196 </mml:mrow>
197 </mml:math>.
198 </p><p>
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.
206 Finally,
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">
210
211 <mml:mfenced open="[" close="]">
212 <mml:mn>0</mml:mn>
213 <mml:mn>1</mml:mn>
214 </mml:mfenced>
215 </mml:math>,
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.
220 </p><p>
221 Unneeded data is then discarded.
222 For example,
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
226 the red,
227 green,
228 and blue components,
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">
233
234 <mml:mfenced open="[" close="]">
235 <mml:mn>0</mml:mn>
236 <mml:mn>1</mml:mn>
237 </mml:mfenced>
238 </mml:math>.
239 </p></dd></dl></div><p>
240 The shift,
241 scale,
242 bias,
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>.
246 </p><p>
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.
255 </p><p>
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).
271 </p><p>
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>
275 Index Mask
276 </strong></span></th><th align="center"><span class="bold"><strong>
277 Component Conversion
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">
282
283 <mml:mrow>
284 <mml:msup><mml:mn>2</mml:mn>
285 <mml:mn>8</mml:mn>
286 </mml:msup>
287 <mml:mo>-</mml:mo>
288 <mml:mn>1</mml:mn>
289 </mml:mrow>
290 </mml:math>
291 </td><td align="center">
292 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
293
294 <mml:mrow>
295 <mml:mfenced open="(" close=")">
296 <mml:mrow>
297 <mml:msup><mml:mn>2</mml:mn>
298 <mml:mn>8</mml:mn>
299 </mml:msup>
300 <mml:mo>-</mml:mo>
301 <mml:mn>1</mml:mn>
302 </mml:mrow>
303 </mml:mfenced>
304 <mml:mo>⁢</mml:mo>
305 <mml:mi mathvariant="italic">c</mml:mi>
306 </mml:mrow>
307 </mml:math>
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">
312
313 <mml:mrow>
314 <mml:msup><mml:mn>2</mml:mn>
315 <mml:mn>7</mml:mn>
316 </mml:msup>
317 <mml:mo>-</mml:mo>
318 <mml:mn>1</mml:mn>
319 </mml:mrow>
320 </mml:math>
321 </td><td align="center">
322 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
323
324 <mml:mfrac>
325 <mml:mfenced open="" close="">
326 <mml:mrow>
327 <mml:mfenced open="(" close=")">
328 <mml:mrow>
329 <mml:msup><mml:mn>2</mml:mn>
330 <mml:mn>8</mml:mn>
331 </mml:msup>
332 <mml:mo>-</mml:mo>
333 <mml:mn>1</mml:mn>
334 </mml:mrow>
335 </mml:mfenced>
336 <mml:mo>⁢</mml:mo>
337 <mml:mi mathvariant="italic">c</mml:mi>
338 <mml:mo>-</mml:mo>
339 <mml:mn>1</mml:mn>
340 </mml:mrow>
341 </mml:mfenced>
342 <mml:mn>2</mml:mn>
343 </mml:mfrac>
344 </mml:math>
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">
349
350 <mml:mn>1</mml:mn>
351 </mml:math>
352 </td><td align="center">
353 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
354
355 <mml:mn>1</mml:mn>
356 </mml:math>
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">
361
362 <mml:mrow>
363 <mml:msup><mml:mn>2</mml:mn>
364 <mml:mn>16</mml:mn>
365 </mml:msup>
366 <mml:mo>-</mml:mo>
367 <mml:mn>1</mml:mn>
368 </mml:mrow>
369 </mml:math>
370 </td><td align="center">
371 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
372
373 <mml:mrow>
374 <mml:mfenced open="(" close=")">
375 <mml:mrow>
376 <mml:msup><mml:mn>2</mml:mn>
377 <mml:mn>16</mml:mn>
378 </mml:msup>
379 <mml:mo>-</mml:mo>
380 <mml:mn>1</mml:mn>
381 </mml:mrow>
382 </mml:mfenced>
383 <mml:mo>⁢</mml:mo>
384 <mml:mi mathvariant="italic">c</mml:mi>
385 </mml:mrow>
386 </mml:math>
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">
391
392 <mml:mrow>
393 <mml:msup><mml:mn>2</mml:mn>
394 <mml:mn>15</mml:mn>
395 </mml:msup>
396 <mml:mo>-</mml:mo>
397 <mml:mn>1</mml:mn>
398 </mml:mrow>
399 </mml:math>
400 </td><td align="center">
401 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
402
403 <mml:mfrac>
404 <mml:mfenced open="" close="">
405 <mml:mrow>
406 <mml:mfenced open="(" close=")">
407 <mml:mrow>
408 <mml:msup><mml:mn>2</mml:mn>
409 <mml:mn>16</mml:mn>
410 </mml:msup>
411 <mml:mo>-</mml:mo>
412 <mml:mn>1</mml:mn>
413 </mml:mrow>
414 </mml:mfenced>
415 <mml:mo>⁢</mml:mo>
416 <mml:mi mathvariant="italic">c</mml:mi>
417 <mml:mo>-</mml:mo>
418 <mml:mn>1</mml:mn>
419 </mml:mrow>
420 </mml:mfenced>
421 <mml:mn>2</mml:mn>
422 </mml:mfrac>
423 </mml:math>
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">
428
429 <mml:mrow>
430 <mml:msup><mml:mn>2</mml:mn>
431 <mml:mn>32</mml:mn>
432 </mml:msup>
433 <mml:mo>-</mml:mo>
434 <mml:mn>1</mml:mn>
435 </mml:mrow>
436 </mml:math>
437 </td><td align="center">
438 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
439
440 <mml:mrow>
441 <mml:mfenced open="(" close=")">
442 <mml:mrow>
443 <mml:msup><mml:mn>2</mml:mn>
444 <mml:mn>32</mml:mn>
445 </mml:msup>
446 <mml:mo>-</mml:mo>
447 <mml:mn>1</mml:mn>
448 </mml:mrow>
449 </mml:mfenced>
450 <mml:mo>⁢</mml:mo>
451 <mml:mi mathvariant="italic">c</mml:mi>
452 </mml:mrow>
453 </mml:math>
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">
458
459 <mml:mrow>
460 <mml:msup><mml:mn>2</mml:mn>
461 <mml:mn>31</mml:mn>
462 </mml:msup>
463 <mml:mo>-</mml:mo>
464 <mml:mn>1</mml:mn>
465 </mml:mrow>
466 </mml:math>
467 </td><td align="center">
468 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
469
470 <mml:mfrac>
471 <mml:mfenced open="" close="">
472 <mml:mrow>
473 <mml:mfenced open="(" close=")">
474 <mml:mrow>
475 <mml:msup><mml:mn>2</mml:mn>
476 <mml:mn>32</mml:mn>
477 </mml:msup>
478 <mml:mo>-</mml:mo>
479 <mml:mn>1</mml:mn>
480 </mml:mrow>
481 </mml:mfenced>
482 <mml:mo>⁢</mml:mo>
483 <mml:mi mathvariant="italic">c</mml:mi>
484 <mml:mo>-</mml:mo>
485 <mml:mn>1</mml:mn>
486 </mml:mrow>
487 </mml:mfenced>
488 <mml:mn>2</mml:mn>
489 </mml:mfrac>
490 </mml:math>
491 </td></tr><tr><td align="left">
492 <code class="constant">GL_FLOAT</code>
493 </td><td align="center">
494 none
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
510 pixel in the
511 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">j</mml:mi></mml:math>th
512 row
513 is placed in location
514 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
515
516 <mml:mrow>
517 <mml:mfenced open="(" close=")">
518 <mml:mi mathvariant="italic">j</mml:mi>
519 </mml:mfenced>
520 <mml:mo>⁢</mml:mo>
521 <mml:mi mathvariant="italic">width</mml:mi>
522 <mml:mo>+</mml:mo>
523 <mml:mi mathvariant="italic">i</mml:mi>
524 </mml:mrow>
525 </mml:math>.
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.
538 </p><p>
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
543 accepted value.
544 </p><p>
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>.
547 </p><p>
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.
549 </p><p>
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.
552 </p><p>
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.
555 </p><p>
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.
558 </p><p>
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>.
565 </p><p>
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>.
576 </p><p>
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
590 is 1.2 or greater.
591 </p><p>
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.
594 </p><p>
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.
598 </p><p>
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>.
602 </p><p>
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>
608 </p><p>
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>
Unnamed repository; edit this file 'description' to name the repository.