HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Revert "update upstream sources"
[clinton/guile-figl.git] / upstream-doc / man4 / glReadPixels.xml
CommitLineData
7faf1d71
AW		 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4<refentry id="glReadPixels">
5 <refmeta>
6 <refmetainfo>
7 <copyright>
8 <year>1991-2006</year>
9 <holder>Silicon Graphics, Inc.</holder>
10 </copyright>
11 </refmetainfo>
12 <refentrytitle>glReadPixels</refentrytitle>
13 <manvolnum>3G</manvolnum>
14 </refmeta>
15 <refnamediv>
16 <refname>glReadPixels</refname>
17 <refpurpose>read a block of pixels from the frame buffer</refpurpose>
18 </refnamediv>
19 <refsynopsisdiv><title>C Specification</title>
20 <funcsynopsis>
21 <funcprototype>
22 <funcdef>void <function>glReadPixels</function></funcdef>
23 <paramdef>GLint <parameter>x</parameter></paramdef>
24 <paramdef>GLint <parameter>y</parameter></paramdef>
25 <paramdef>GLsizei <parameter>width</parameter></paramdef>
26 <paramdef>GLsizei <parameter>height</parameter></paramdef>
27 <paramdef>GLenum <parameter>format</parameter></paramdef>
28 <paramdef>GLenum <parameter>type</parameter></paramdef>
29 <paramdef>GLvoid * <parameter>data</parameter></paramdef>
30 </funcprototype>
31 </funcsynopsis>
32 </refsynopsisdiv>
33 <!-- eqn: ignoring delim $$ -->
34 <refsect1 id="parameters"><title>Parameters</title>
35 <variablelist>
36 <varlistentry>
37 <term><parameter>x</parameter></term>
38 <term><parameter>y</parameter></term>
39 <listitem>
40 <para>
41 Specify the window coordinates of the first pixel
42 that is read from the frame buffer.
43 This location is the lower left corner of a rectangular block of pixels.
44 </para>
45 </listitem>
46 </varlistentry>
47 <varlistentry>
48 <term><parameter>width</parameter></term>
49 <term><parameter>height</parameter></term>
50 <listitem>
51 <para>
52 Specify the dimensions of the pixel rectangle.
53 <parameter>width</parameter> and <parameter>height</parameter> of one correspond to a single pixel.
54 </para>
55 </listitem>
56 </varlistentry>
57 <varlistentry>
58 <term><parameter>format</parameter></term>
59 <listitem>
60 <para>
61 Specifies the format of the pixel data.
62 The following symbolic values are accepted:
63 <constant>GL_STENCIL_INDEX</constant>,
64 <constant>GL_DEPTH_COMPONENT</constant>,
65 <constant>GL_DEPTH_STENCIL</constant>,
66 <constant>GL_RED</constant>,
67 <constant>GL_GREEN</constant>,
68 <constant>GL_BLUE</constant>,
69 <constant>GL_RGB</constant>,
70 <constant>GL_BGR</constant>,
71 <constant>GL_RGBA</constant>, and
72 <constant>GL_BGRA</constant>.
73 </para>
74 </listitem>
75 </varlistentry>
76 <varlistentry>
77 <term><parameter>type</parameter></term>
78 <listitem>
79 <para>
80 Specifies the data type of the pixel data.
81 Must be one of
82 <constant>GL_UNSIGNED_BYTE</constant>,
83 <constant>GL_BYTE</constant>,
84 <constant>GL_UNSIGNED_SHORT</constant>,
85 <constant>GL_SHORT</constant>,
86 <constant>GL_UNSIGNED_INT</constant>,
87 <constant>GL_INT</constant>,
88 <constant>GL_HALF_FLOAT</constant>,
89 <constant>GL_FLOAT</constant>,
90 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
91 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
92 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
93 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
94 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
95 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
96 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
97 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
98 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
99 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
100 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>,
101 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>,
102 <constant>GL_UNSIGNED_INT_24_8</constant>,
103 <constant>GL_UNSIGNED_INT_10F_11F_11F_REV</constant>,
104 <constant>GL_UNSIGNED_INT_5_9_9_9_REV</constant>, or
105 <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV</constant>.
106 </para>
107 </listitem>
108 </varlistentry>
109 <varlistentry>
110 <term><parameter>data</parameter></term>
111 <listitem>
112 <para>
113 Returns the pixel data.
114 </para>
115 </listitem>
116 </varlistentry>
117 </variablelist>
118 </refsect1>
119 <refsect1 id="description"><title>Description</title>
120 <para>
121 <function>glReadPixels</function> returns pixel data from the frame buffer,
122 starting with the pixel whose lower left corner
123 is at location (<parameter>x</parameter>, <parameter>y</parameter>),
124 into client memory starting at location <parameter>data</parameter>.
125 Several parameters control the processing of the pixel data before
126 it is placed into client memory.
127 These parameters are set with <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>.
128 This reference page describes the effects on <function>glReadPixels</function> of most,
129 but not all of the parameters specified by these three commands.
130 </para>
131 <para>
132 If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
133 (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a block of pixels is
134 requested, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store
135 rather than a pointer to client memory.
136 </para>
137 <para>
138 <function>glReadPixels</function> returns values from each pixel with lower left corner at
139 <inlineequation><mml:math>
140 <!-- eqn: (x + i, y + j): -->
141 <mml:mfenced open="(" close=")">
142 <mml:mrow>
143 <mml:mi mathvariant="italic">x</mml:mi>
144 <mml:mo>+</mml:mo>
145 <mml:mi mathvariant="italic">i</mml:mi>
146 </mml:mrow>
147 <mml:mrow>
148 <mml:mi mathvariant="italic">y</mml:mi>
149 <mml:mo>+</mml:mo>
150 <mml:mi mathvariant="italic">j</mml:mi>
151 </mml:mrow>
152 </mml:mfenced>
153 </mml:math></inlineequation>
154 for
155 <inlineequation><mml:math>
156 <!-- eqn: 0 <= i < width: -->
157 <mml:mrow>
158 <mml:mn>0</mml:mn>
159 <mml:mo>&lt;=</mml:mo>
160 <mml:mi mathvariant="italic">i</mml:mi>
161 <mml:mo>&lt;</mml:mo>
162 <mml:mi mathvariant="italic">width</mml:mi>
163 </mml:mrow>
164 </mml:math></inlineequation>
165 and
166 <inlineequation><mml:math>
167 <!-- eqn: 0 <= j < height: -->
168 <mml:mrow>
169 <mml:mn>0</mml:mn>
170 <mml:mo>&lt;=</mml:mo>
171 <mml:mi mathvariant="italic">j</mml:mi>
172 <mml:mo>&lt;</mml:mo>
173 <mml:mi mathvariant="italic">height</mml:mi>
174 </mml:mrow>
175 </mml:math></inlineequation>.
176 This pixel is said to be the
177 <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
178 pixel in the
179 <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
180 row.
181 Pixels are returned in row order from the lowest to the highest row,
182 left to right in each row.
183 </para>
184 <para>
185 <parameter>format</parameter> specifies the format for the returned pixel values;
186 accepted values are:
187 </para>
188 <variablelist>
189 <varlistentry>
190 <term><constant>GL_STENCIL_INDEX</constant></term>
191 <listitem>
192 <para>
193 Stencil values are read from the stencil buffer.
f37e7e3d
DH		 194 Each index is converted to fixed point,
195 shifted left or right depending on the value and sign of <constant>GL_INDEX_SHIFT</constant>,
196 and added to <constant>GL_INDEX_OFFSET</constant>.
197 If <constant>GL_MAP_STENCIL</constant> is <constant>GL_TRUE</constant>,
198 indices are replaced by their mappings in the table <constant>GL_PIXEL_MAP_S_TO_S</constant>.
7faf1d71
AW		 199 </para>
200 </listitem>
201 </varlistentry>
202 <varlistentry>
203 <term><constant>GL_DEPTH_COMPONENT</constant></term>
204 <listitem>
205 <para>
206 Depth values are read from the depth buffer.
207 Each component is converted to floating point such that the minimum depth
208 value maps to 0 and the maximum value maps to 1.
f37e7e3d
DH		 209 Each component is then multiplied by <constant>GL_DEPTH_SCALE</constant>,
210 added to <constant>GL_DEPTH_BIAS</constant>,
211 and finally clamped to the range
7faf1d71
AW		 212 <inlineequation><mml:math>
213 <!-- eqn: [0,1]: -->
214 <mml:mfenced open="[" close="]">
215 <mml:mn>0</mml:mn>
216 <mml:mn>1</mml:mn>
217 </mml:mfenced>
218 </mml:math></inlineequation>.
219 </para>
220 </listitem>
221 </varlistentry>
222 <varlistentry>
223 <term><constant>GL_DEPTH_STENCIL</constant></term>
224 <listitem>
225 <para>
226 Values are taken from both the depth and stencil buffers. The <parameter>type</parameter> parameter
227 must be <constant>GL_UNSIGNED_INT_24_8</constant> or <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV</constant>.
228 </para>
229 </listitem>
230 </varlistentry>
231 <varlistentry>
232 <term><constant>GL_RED</constant></term>
233 <listitem>
234 </listitem>
235 </varlistentry>
236 <varlistentry>
237 <term><constant>GL_GREEN</constant></term>
238 <listitem>
239 </listitem>
240 </varlistentry>
241 <varlistentry>
242 <term><constant>GL_BLUE</constant></term>
243 <listitem>
244 </listitem>
245 </varlistentry>
246 <varlistentry>
247 <term><constant>GL_RGB</constant></term>
248 <listitem>
249 </listitem>
250 </varlistentry>
251 <varlistentry>
252 <term><constant>GL_BGR</constant></term>
253 <listitem>
254 </listitem>
255 </varlistentry>
256 <varlistentry>
257 <term><constant>GL_RGBA</constant></term>
258 <listitem>
259 </listitem>
260 </varlistentry>
261 <varlistentry>
262 <term><constant>GL_BGRA</constant></term>
263 <listitem>
264 </listitem>
265 </varlistentry>
266 </variablelist>
267 <para>
268 Finally, the indices or components
269 are converted to the proper format,
270 as specified by <parameter>type</parameter>.
271 If <parameter>format</parameter> is <constant>GL_STENCIL_INDEX</constant>
272 and <parameter>type</parameter> is not <constant>GL_FLOAT</constant>,
273 each index is masked with the mask value given in the following table.
274 If <parameter>type</parameter> is <constant>GL_FLOAT</constant>, then each integer index is converted to
275 single-precision floating-point format.
276 </para>
277 <para>
278 If <parameter>format</parameter> is
279 <constant>GL_RED</constant>,
280 <constant>GL_GREEN</constant>,
281 <constant>GL_BLUE</constant>,
282 <constant>GL_RGB</constant>,
283 <constant>GL_BGR</constant>,
284 <constant>GL_RGBA</constant>, or
285 <constant>GL_BGRA</constant> and <parameter>type</parameter> is not <constant>GL_FLOAT</constant>,
286 each component is multiplied by the multiplier shown in the following table.
287 If type is <constant>GL_FLOAT</constant>, then each component is passed as is
288 (or converted to the client's single-precision floating-point format if
289 it is different from the one used by the GL).
290 </para>
291 <para>
292 </para>
293 <informaltable frame="topbot">
294 <tgroup cols="3" align="left">
295 <colspec/>
296 <colspec align="center"/>
297 <colspec align="center"/>
298 <thead>
299 <row>
300 <entry rowsep="1" align="left">
301 <parameter>type</parameter>
302 </entry>
303 <entry rowsep="1" align="center"><emphasis role="bold">
304 Index Mask
305 </emphasis></entry>
306 <entry rowsep="1" align="center"><emphasis role="bold">
307 Component Conversion
308 </emphasis></entry>
309 </row>
310 </thead>
311 <tbody>
312 <row>
313 <entry align="left">
314 <constant>GL_UNSIGNED_BYTE</constant>
315 </entry>
316 <entry align="center">
317 <inlineequation><mml:math>
318 <!-- eqn: 2 sup 8 - 1: -->
319 <mml:mrow>
320 <mml:msup><mml:mn>2</mml:mn>
321 <mml:mn>8</mml:mn>
322 </mml:msup>
323 <mml:mo>-</mml:mo>
324 <mml:mn>1</mml:mn>
325 </mml:mrow>
326 </mml:math></inlineequation>
327 </entry>
328 <entry align="center">
329 <inlineequation><mml:math>
330 <!-- eqn: (2 sup 8 - 1) c: -->
331 <mml:mrow>
332 <mml:mfenced open="(" close=")">
333 <mml:mrow>
334 <mml:msup><mml:mn>2</mml:mn>
335 <mml:mn>8</mml:mn>
336 </mml:msup>
337 <mml:mo>-</mml:mo>
338 <mml:mn>1</mml:mn>
339 </mml:mrow>
340 </mml:mfenced>
341 <mml:mo>&it;</mml:mo>
342 <mml:mi mathvariant="italic">c</mml:mi>
343 </mml:mrow>
344 </mml:math></inlineequation>
345 </entry>
346 </row>
347 <row>
348 <entry align="left">
349 <constant>GL_BYTE</constant>
350 </entry>
351 <entry align="center">
352 <inlineequation><mml:math>
353 <!-- eqn: 2 sup 7 - 1: -->
354 <mml:mrow>
355 <mml:msup><mml:mn>2</mml:mn>
356 <mml:mn>7</mml:mn>
357 </mml:msup>
358 <mml:mo>-</mml:mo>
359 <mml:mn>1</mml:mn>
360 </mml:mrow>
361 </mml:math></inlineequation>
362 </entry>
363 <entry align="center">
364 <inlineequation><mml:math>
365 <!-- eqn: {(2 sup 8 - 1) c - 1} / 2: -->
366 <mml:mfrac>
367 <mml:mfenced open="" close="">
368 <mml:mrow>
369 <mml:mfenced open="(" close=")">
370 <mml:mrow>
371 <mml:msup><mml:mn>2</mml:mn>
372 <mml:mn>8</mml:mn>
373 </mml:msup>
374 <mml:mo>-</mml:mo>
375 <mml:mn>1</mml:mn>
376 </mml:mrow>
377 </mml:mfenced>
378 <mml:mo>&it;</mml:mo>
379 <mml:mi mathvariant="italic">c</mml:mi>
380 <mml:mo>-</mml:mo>
381 <mml:mn>1</mml:mn>
382 </mml:mrow>
383 </mml:mfenced>
384 <mml:mn>2</mml:mn>
385 </mml:mfrac>
386 </mml:math></inlineequation>
387 </entry>
388 </row>
389 <row>
390 <entry align="left">
391 <constant>GL_UNSIGNED_SHORT</constant>
392 </entry>
393 <entry align="center">
394 <inlineequation><mml:math>
395 <!-- eqn: 2 sup 16 - 1: -->
396 <mml:mrow>
397 <mml:msup><mml:mn>2</mml:mn>
398 <mml:mn>16</mml:mn>
399 </mml:msup>
400 <mml:mo>-</mml:mo>
401 <mml:mn>1</mml:mn>
402 </mml:mrow>
403 </mml:math></inlineequation>
404 </entry>
405 <entry align="center">
406 <inlineequation><mml:math>
407 <!-- eqn: (2 sup 16 - 1) c: -->
408 <mml:mrow>
409 <mml:mfenced open="(" close=")">
410 <mml:mrow>
411 <mml:msup><mml:mn>2</mml:mn>
412 <mml:mn>16</mml:mn>
413 </mml:msup>
414 <mml:mo>-</mml:mo>
415 <mml:mn>1</mml:mn>
416 </mml:mrow>
417 </mml:mfenced>
418 <mml:mo>&it;</mml:mo>
419 <mml:mi mathvariant="italic">c</mml:mi>
420 </mml:mrow>
421 </mml:math></inlineequation>
422 </entry>
423 </row>
424 <row>
425 <entry align="left">
426 <constant>GL_SHORT</constant>
427 </entry>
428 <entry align="center">
429 <inlineequation><mml:math>
430 <!-- eqn: 2 sup 15 - 1: -->
431 <mml:mrow>
432 <mml:msup><mml:mn>2</mml:mn>
433 <mml:mn>15</mml:mn>
434 </mml:msup>
435 <mml:mo>-</mml:mo>
436 <mml:mn>1</mml:mn>
437 </mml:mrow>
438 </mml:math></inlineequation>
439 </entry>
440 <entry align="center">
441 <inlineequation><mml:math>
442 <!-- eqn: {(2 sup 16 - 1) c - 1} / 2: -->
443 <mml:mfrac>
444 <mml:mfenced open="" close="">
445 <mml:mrow>
446 <mml:mfenced open="(" close=")">
447 <mml:mrow>
448 <mml:msup><mml:mn>2</mml:mn>
449 <mml:mn>16</mml:mn>
450 </mml:msup>
451 <mml:mo>-</mml:mo>
452 <mml:mn>1</mml:mn>
453 </mml:mrow>
454 </mml:mfenced>
455 <mml:mo>&it;</mml:mo>
456 <mml:mi mathvariant="italic">c</mml:mi>
457 <mml:mo>-</mml:mo>
458 <mml:mn>1</mml:mn>
459 </mml:mrow>
460 </mml:mfenced>
461 <mml:mn>2</mml:mn>
462 </mml:mfrac>
463 </mml:math></inlineequation>
464 </entry>
465 </row>
466 <row>
467 <entry align="left">
468 <constant>GL_UNSIGNED_INT</constant>
469 </entry>
470 <entry align="center">
471 <inlineequation><mml:math>
472 <!-- eqn: 2 sup 32 - 1: -->
473 <mml:mrow>
474 <mml:msup><mml:mn>2</mml:mn>
475 <mml:mn>32</mml:mn>
476 </mml:msup>
477 <mml:mo>-</mml:mo>
478 <mml:mn>1</mml:mn>
479 </mml:mrow>
480 </mml:math></inlineequation>
481 </entry>
482 <entry align="center">
483 <inlineequation><mml:math>
484 <!-- eqn: (2 sup 32 - 1) c: -->
485 <mml:mrow>
486 <mml:mfenced open="(" close=")">
487 <mml:mrow>
488 <mml:msup><mml:mn>2</mml:mn>
489 <mml:mn>32</mml:mn>
490 </mml:msup>
491 <mml:mo>-</mml:mo>
492 <mml:mn>1</mml:mn>
493 </mml:mrow>
494 </mml:mfenced>
495 <mml:mo>&it;</mml:mo>
496 <mml:mi mathvariant="italic">c</mml:mi>
497 </mml:mrow>
498 </mml:math></inlineequation>
499 </entry>
500 </row>
501 <row>
502 <entry align="left">
503 <constant>GL_INT</constant>
504 </entry>
505 <entry align="center">
506 <inlineequation><mml:math>
507 <!-- eqn: 2 sup 31 - 1: -->
508 <mml:mrow>
509 <mml:msup><mml:mn>2</mml:mn>
510 <mml:mn>31</mml:mn>
511 </mml:msup>
512 <mml:mo>-</mml:mo>
513 <mml:mn>1</mml:mn>
514 </mml:mrow>
515 </mml:math></inlineequation>
516 </entry>
517 <entry align="center">
518 <inlineequation><mml:math>
519 <!-- eqn: {(2 sup 32 - 1) c - 1} / 2: -->
520 <mml:mfrac>
521 <mml:mfenced open="" close="">
522 <mml:mrow>
523 <mml:mfenced open="(" close=")">
524 <mml:mrow>
525 <mml:msup><mml:mn>2</mml:mn>
526 <mml:mn>32</mml:mn>
527 </mml:msup>
528 <mml:mo>-</mml:mo>
529 <mml:mn>1</mml:mn>
530 </mml:mrow>
531 </mml:mfenced>
532 <mml:mo>&it;</mml:mo>
533 <mml:mi mathvariant="italic">c</mml:mi>
534 <mml:mo>-</mml:mo>
535 <mml:mn>1</mml:mn>
536 </mml:mrow>
537 </mml:mfenced>
538 <mml:mn>2</mml:mn>
539 </mml:mfrac>
540 </mml:math></inlineequation>
541 </entry>
542 </row>
543 <row>
544 <entry align="left">
545 <constant>GL_HALF_FLOAT</constant>
546 </entry>
547 <entry align="center">
548 none
549 </entry>
550 <entry align="center">
551 <inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
552 </entry>
553 </row>
554 <row>
555 <entry align="left">
556 <constant>GL_FLOAT</constant>
557 </entry>
558 <entry align="center">
559 none
560 </entry>
561 <entry align="center">
562 <inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
563 </entry>
564 </row>
565 <row>
566 <entry align="left">
567 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>
568 </entry>
569 <entry align="center">
570 <inlineequation><mml:math>
571 <!-- eqn: 2 sup N - 1: -->
572 <mml:mrow>
573 <mml:msup><mml:mn>2</mml:mn>
574 <mml:mn>N</mml:mn>
575 </mml:msup>
576 <mml:mo>-</mml:mo>
577 <mml:mn>1</mml:mn>
578 </mml:mrow>
579 </mml:math></inlineequation>
580 </entry>
581 <entry align="center">
582 <inlineequation><mml:math>
583 <!-- eqn: (2 sup N - 1) c: -->
584 <mml:mrow>
585 <mml:mfenced open="(" close=")">
586 <mml:mrow>
587 <mml:msup><mml:mn>2</mml:mn>
588 <mml:mn>N</mml:mn>
589 </mml:msup>
590 <mml:mo>-</mml:mo>
591 <mml:mn>1</mml:mn>
592 </mml:mrow>
593 </mml:mfenced>
594 <mml:mo>&it;</mml:mo>
595 <mml:mi mathvariant="italic">c</mml:mi>
596 </mml:mrow>
597 </mml:math></inlineequation>
598 </entry>
599 </row>
600 <row>
601 <entry align="left">
602 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>
603 </entry>
604 <entry align="center">
605 <inlineequation><mml:math>
606 <!-- eqn: 2 sup N - 1: -->
607 <mml:mrow>
608 <mml:msup><mml:mn>2</mml:mn>
609 <mml:mn>N</mml:mn>
610 </mml:msup>
611 <mml:mo>-</mml:mo>
612 <mml:mn>1</mml:mn>
613 </mml:mrow>
614 </mml:math></inlineequation>
615 </entry>
616 <entry align="center">
617 <inlineequation><mml:math>
618 <!-- eqn: (2 sup N - 1) c: -->
619 <mml:mrow>
620 <mml:mfenced open="(" close=")">
621 <mml:mrow>
622 <mml:msup><mml:mn>2</mml:mn>
623 <mml:mn>N</mml:mn>
624 </mml:msup>
625 <mml:mo>-</mml:mo>
626 <mml:mn>1</mml:mn>
627 </mml:mrow>
628 </mml:mfenced>
629 <mml:mo>&it;</mml:mo>
630 <mml:mi mathvariant="italic">c</mml:mi>
631 </mml:mrow>
632 </mml:math></inlineequation>
633 </entry>
634 </row>
635 <row>
636 <entry align="left">
637 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>
638 </entry>
639 <entry align="center">
640 <inlineequation><mml:math>
641 <!-- eqn: 2 sup N - 1: -->
642 <mml:mrow>
643 <mml:msup><mml:mn>2</mml:mn>
644 <mml:mn>N</mml:mn>
645 </mml:msup>
646 <mml:mo>-</mml:mo>
647 <mml:mn>1</mml:mn>
648 </mml:mrow>
649 </mml:math></inlineequation>
650 </entry>
651 <entry align="center">
652 <inlineequation><mml:math>
653 <!-- eqn: (2 sup N - 1) c: -->
654 <mml:mrow>
655 <mml:mfenced open="(" close=")">
656 <mml:mrow>
657 <mml:msup><mml:mn>2</mml:mn>
658 <mml:mn>N</mml:mn>
659 </mml:msup>
660 <mml:mo>-</mml:mo>
661 <mml:mn>1</mml:mn>
662 </mml:mrow>
663 </mml:mfenced>
664 <mml:mo>&it;</mml:mo>
665 <mml:mi mathvariant="italic">c</mml:mi>
666 </mml:mrow>
667 </mml:math></inlineequation>
668 </entry>
669 </row>
670 <row>
671 <entry align="left">
672 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
673 </entry>
674 <entry align="center">
675 <inlineequation><mml:math>
676 <!-- eqn: 2 sup N - 1: -->
677 <mml:mrow>
678 <mml:msup><mml:mn>2</mml:mn>
679 <mml:mn>N</mml:mn>
680 </mml:msup>
681 <mml:mo>-</mml:mo>
682 <mml:mn>1</mml:mn>
683 </mml:mrow>
684 </mml:math></inlineequation>
685 </entry>
686 <entry align="center">
687 <inlineequation><mml:math>
688 <!-- eqn: (2 sup N - 1) c: -->
689 <mml:mrow>
690 <mml:mfenced open="(" close=")">
691 <mml:mrow>
692 <mml:msup><mml:mn>2</mml:mn>
693 <mml:mn>N</mml:mn>
694 </mml:msup>
695 <mml:mo>-</mml:mo>
696 <mml:mn>1</mml:mn>
697 </mml:mrow>
698 </mml:mfenced>
699 <mml:mo>&it;</mml:mo>
700 <mml:mi mathvariant="italic">c</mml:mi>
701 </mml:mrow>
702 </mml:math></inlineequation>
703 </entry>
704 </row>
705 <row>
706 <entry align="left">
707 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>
708 </entry>
709 <entry align="center">
710 <inlineequation><mml:math>
711 <!-- eqn: 2 sup N - 1: -->
712 <mml:mrow>
713 <mml:msup><mml:mn>2</mml:mn>
714 <mml:mn>N</mml:mn>
715 </mml:msup>
716 <mml:mo>-</mml:mo>
717 <mml:mn>1</mml:mn>
718 </mml:mrow>
719 </mml:math></inlineequation>
720 </entry>
721 <entry align="center">
722 <inlineequation><mml:math>
723 <!-- eqn: (2 sup N - 1) c: -->
724 <mml:mrow>
725 <mml:mfenced open="(" close=")">
726 <mml:mrow>
727 <mml:msup><mml:mn>2</mml:mn>
728 <mml:mn>N</mml:mn>
729 </mml:msup>
730 <mml:mo>-</mml:mo>
731 <mml:mn>1</mml:mn>
732 </mml:mrow>
733 </mml:mfenced>
734 <mml:mo>&it;</mml:mo>
735 <mml:mi mathvariant="italic">c</mml:mi>
736 </mml:mrow>
737 </mml:math></inlineequation>
738 </entry>
739 </row>
740 <row>
741 <entry align="left">
742 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>
743 </entry>
744 <entry align="center">
745 <inlineequation><mml:math>
746 <!-- eqn: 2 sup N - 1: -->
747 <mml:mrow>
748 <mml:msup><mml:mn>2</mml:mn>
749 <mml:mn>N</mml:mn>
750 </mml:msup>
751 <mml:mo>-</mml:mo>
752 <mml:mn>1</mml:mn>
753 </mml:mrow>
754 </mml:math></inlineequation>
755 </entry>
756 <entry align="center">
757 <inlineequation><mml:math>
758 <!-- eqn: (2 sup N - 1) c: -->
759 <mml:mrow>
760 <mml:mfenced open="(" close=")">
761 <mml:mrow>
762 <mml:msup><mml:mn>2</mml:mn>
763 <mml:mn>N</mml:mn>
764 </mml:msup>
765 <mml:mo>-</mml:mo>
766 <mml:mn>1</mml:mn>
767 </mml:mrow>
768 </mml:mfenced>
769 <mml:mo>&it;</mml:mo>
770 <mml:mi mathvariant="italic">c</mml:mi>
771 </mml:mrow>
772 </mml:math></inlineequation>
773 </entry>
774 </row>
775 <row>
776 <entry align="left">
777 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>
778 </entry>
779 <entry align="center">
780 <inlineequation><mml:math>
781 <!-- eqn: 2 sup N - 1: -->
782 <mml:mrow>
783 <mml:msup><mml:mn>2</mml:mn>
784 <mml:mn>N</mml:mn>
785 </mml:msup>
786 <mml:mo>-</mml:mo>
787 <mml:mn>1</mml:mn>
788 </mml:mrow>
789 </mml:math></inlineequation>
790 </entry>
791 <entry align="center">
792 <inlineequation><mml:math>
793 <!-- eqn: (2 sup N - 1) c: -->
794 <mml:mrow>
795 <mml:mfenced open="(" close=")">
796 <mml:mrow>
797 <mml:msup><mml:mn>2</mml:mn>
798 <mml:mn>N</mml:mn>
799 </mml:msup>
800 <mml:mo>-</mml:mo>
801 <mml:mn>1</mml:mn>
802 </mml:mrow>
803 </mml:mfenced>
804 <mml:mo>&it;</mml:mo>
805 <mml:mi mathvariant="italic">c</mml:mi>
806 </mml:mrow>
807 </mml:math></inlineequation>
808 </entry>
809 </row>
810 <row>
811 <entry align="left">
812 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>
813 </entry>
814 <entry align="center">
815 <inlineequation><mml:math>
816 <!-- eqn: 2 sup N - 1: -->
817 <mml:mrow>
818 <mml:msup><mml:mn>2</mml:mn>
819 <mml:mn>N</mml:mn>
820 </mml:msup>
821 <mml:mo>-</mml:mo>
822 <mml:mn>1</mml:mn>
823 </mml:mrow>
824 </mml:math></inlineequation>
825 </entry>
826 <entry align="center">
827 <inlineequation><mml:math>
828 <!-- eqn: (2 sup N - 1) c: -->
829 <mml:mrow>
830 <mml:mfenced open="(" close=")">
831 <mml:mrow>
832 <mml:msup><mml:mn>2</mml:mn>
833 <mml:mn>N</mml:mn>
834 </mml:msup>
835 <mml:mo>-</mml:mo>
836 <mml:mn>1</mml:mn>
837 </mml:mrow>
838 </mml:mfenced>
839 <mml:mo>&it;</mml:mo>
840 <mml:mi mathvariant="italic">c</mml:mi>
841 </mml:mrow>
842 </mml:math></inlineequation>
843 </entry>
844 </row>
845 <row>
846 <entry align="left">
847 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>
848 </entry>
849 <entry align="center">
850 <inlineequation><mml:math>
851 <!-- eqn: 2 sup N - 1: -->
852 <mml:mrow>
853 <mml:msup><mml:mn>2</mml:mn>
854 <mml:mn>N</mml:mn>
855 </mml:msup>
856 <mml:mo>-</mml:mo>
857 <mml:mn>1</mml:mn>
858 </mml:mrow>
859 </mml:math></inlineequation>
860 </entry>
861 <entry align="center">
862 <inlineequation><mml:math>
863 <!-- eqn: (2 sup N - 1) c: -->
864 <mml:mrow>
865 <mml:mfenced open="(" close=")">
866 <mml:mrow>
867 <mml:msup><mml:mn>2</mml:mn>
868 <mml:mn>N</mml:mn>
869 </mml:msup>
870 <mml:mo>-</mml:mo>
871 <mml:mn>1</mml:mn>
872 </mml:mrow>
873 </mml:mfenced>
874 <mml:mo>&it;</mml:mo>
875 <mml:mi mathvariant="italic">c</mml:mi>
876 </mml:mrow>
877 </mml:math></inlineequation>
878 </entry>
879 </row>
880 <row>
881 <entry align="left">
882 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>
883 </entry>
884 <entry align="center">
885 <inlineequation><mml:math>
886 <!-- eqn: 2 sup N - 1: -->
887 <mml:mrow>
888 <mml:msup><mml:mn>2</mml:mn>
889 <mml:mn>N</mml:mn>
890 </mml:msup>
891 <mml:mo>-</mml:mo>
892 <mml:mn>1</mml:mn>
893 </mml:mrow>
894 </mml:math></inlineequation>
895 </entry>
896 <entry align="center">
897 <inlineequation><mml:math>
898 <!-- eqn: (2 sup N - 1) c: -->
899 <mml:mrow>
900 <mml:mfenced open="(" close=")">
901 <mml:mrow>
902 <mml:msup><mml:mn>2</mml:mn>
903 <mml:mn>N</mml:mn>
904 </mml:msup>
905 <mml:mo>-</mml:mo>
906 <mml:mn>1</mml:mn>
907 </mml:mrow>
908 </mml:mfenced>
909 <mml:mo>&it;</mml:mo>
910 <mml:mi mathvariant="italic">c</mml:mi>
911 </mml:mrow>
912 </mml:math></inlineequation>
913 </entry>
914 </row>
915 <row>
916 <entry align="left">
917 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>
918 </entry>
919 <entry align="center">
920 <inlineequation><mml:math>
921 <!-- eqn: 2 sup N - 1: -->
922 <mml:mrow>
923 <mml:msup><mml:mn>2</mml:mn>
924 <mml:mn>N</mml:mn>
925 </mml:msup>
926 <mml:mo>-</mml:mo>
927 <mml:mn>1</mml:mn>
928 </mml:mrow>
929 </mml:math></inlineequation>
930 </entry>
931 <entry align="center">
932 <inlineequation><mml:math>
933 <!-- eqn: (2 sup N - 1) c: -->
934 <mml:mrow>
935 <mml:mfenced open="(" close=")">
936 <mml:mrow>
937 <mml:msup><mml:mn>2</mml:mn>
938 <mml:mn>N</mml:mn>
939 </mml:msup>
940 <mml:mo>-</mml:mo>
941 <mml:mn>1</mml:mn>
942 </mml:mrow>
943 </mml:mfenced>
944 <mml:mo>&it;</mml:mo>
945 <mml:mi mathvariant="italic">c</mml:mi>
946 </mml:mrow>
947 </mml:math></inlineequation>
948 </entry>
949 </row>
950 <row>
951 <entry align="left">
952 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
953 </entry>
954 <entry align="center">
955 <inlineequation><mml:math>
956 <!-- eqn: 2 sup N - 1: -->
957 <mml:mrow>
958 <mml:msup><mml:mn>2</mml:mn>
959 <mml:mn>N</mml:mn>
960 </mml:msup>
961 <mml:mo>-</mml:mo>
962 <mml:mn>1</mml:mn>
963 </mml:mrow>
964 </mml:math></inlineequation>
965 </entry>
966 <entry align="center">
967 <inlineequation><mml:math>
968 <!-- eqn: (2 sup N - 1) c: -->
969 <mml:mrow>
970 <mml:mfenced open="(" close=")">
971 <mml:mrow>
972 <mml:msup><mml:mn>2</mml:mn>
973 <mml:mn>N</mml:mn>
974 </mml:msup>
975 <mml:mo>-</mml:mo>
976 <mml:mn>1</mml:mn>
977 </mml:mrow>
978 </mml:mfenced>
979 <mml:mo>&it;</mml:mo>
980 <mml:mi mathvariant="italic">c</mml:mi>
981 </mml:mrow>
982 </mml:math></inlineequation>
983 </entry>
984 </row>
985 <row>
986 <entry align="left">
987 <constant>GL_UNSIGNED_INT_24_8</constant>
988 </entry>
989 <entry align="center">
990 <inlineequation><mml:math>
991 <!-- eqn: 2 sup N - 1: -->
992 <mml:mrow>
993 <mml:msup><mml:mn>2</mml:mn>
994 <mml:mn>N</mml:mn>
995 </mml:msup>
996 <mml:mo>-</mml:mo>
997 <mml:mn>1</mml:mn>
998 </mml:mrow>
999 </mml:math></inlineequation>
1000 </entry>
1001 <entry align="center">
1002 <inlineequation><mml:math>
1003 <!-- eqn: (2 sup N - 1) c: -->
1004 <mml:mrow>
1005 <mml:mfenced open="(" close=")">
1006 <mml:mrow>
1007 <mml:msup><mml:mn>2</mml:mn>
1008 <mml:mn>N</mml:mn>
1009 </mml:msup>
1010 <mml:mo>-</mml:mo>
1011 <mml:mn>1</mml:mn>
1012 </mml:mrow>
1013 </mml:mfenced>
1014 <mml:mo>&it;</mml:mo>
1015 <mml:mi mathvariant="italic">c</mml:mi>
1016 </mml:mrow>
1017 </mml:math></inlineequation>
1018 </entry>
1019 </row>
1020 <row>
1021 <entry align="left">
1022 <constant>GL_UNSIGNED_INT_10F_11F_11F_REV</constant>
1023 </entry>
1024 <entry align="center">
1025 --
1026 </entry>
1027 <entry align="left">
1028 Special
1029 </entry>
1030 </row>
1031 <row>
1032 <entry align="left">
1033 <constant>GL_UNSIGNED_INT_5_9_9_9_REV</constant>
1034 </entry>
1035 <entry align="center">
1036 --
1037 </entry>
1038 <entry align="left">
1039 Special
1040 </entry>
1041 </row>
1042 <row>
1043 <entry align="left">
1044 <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV</constant>
1045 </entry>
1046 <entry align="center">
1047 none
1048 </entry>
1049 <entry align="center">
1050 <inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation> (Depth Only)
1051 </entry>
1052 </row>
1053 </tbody>
1054 </tgroup>
1055 </informaltable>
1056 <para>
1057 Return values are placed in memory as follows.
1058 If <parameter>format</parameter> is
1059 <constant>GL_STENCIL_INDEX</constant>,
1060 <constant>GL_DEPTH_COMPONENT</constant>,
1061 <constant>GL_RED</constant>,
1062 <constant>GL_GREEN</constant>, or
1063 <constant>GL_BLUE</constant>,
1064 a single value is returned and the data for the
1065 <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
1066 pixel in the
1067 <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
1068 row
1069 is placed in location
1070 <inlineequation><mml:math>
1071 <!-- eqn: (j) width + i: -->
1072 <mml:mrow>
1073 <mml:mfenced open="(" close=")">
1074 <mml:mi mathvariant="italic">j</mml:mi>
1075 </mml:mfenced>
1076 <mml:mo>&it;</mml:mo>
1077 <mml:mi mathvariant="italic">width</mml:mi>
1078 <mml:mo>+</mml:mo>
1079 <mml:mi mathvariant="italic">i</mml:mi>
1080 </mml:mrow>
1081 </mml:math></inlineequation>.
1082 <constant>GL_RGB</constant> and <constant>GL_BGR</constant> return three values,
1083 <constant>GL_RGBA</constant> and <constant>GL_BGRA</constant> return four values for each pixel,
1084 with all values corresponding to a single pixel occupying contiguous space
1085 in <parameter>data</parameter>.
1086 Storage parameters set by <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
1087 such as <constant>GL_PACK_LSB_FIRST</constant> and <constant>GL_PACK_SWAP_BYTES</constant>,
1088 affect the way that data is written into memory.
1089 See <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> for a description.
1090 </para>
1091 </refsect1>
1092 <refsect1 id="notes"><title>Notes</title>
1093 <para>
1094 Values for pixels that lie outside the window
1095 connected to the current GL context are undefined.
1096 </para>
1097 <para>
1098 If an error is generated,
1099 no change is made to the contents of <parameter>data</parameter>.
1100 </para>
1101 </refsect1>
1102 <refsect1 id="errors"><title>Errors</title>
1103 <para>
1104 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> or <parameter>type</parameter> is not an
1105 accepted value.
1106 </para>
1107 <para>
1108 <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
1109 </para>
1110 <para>
1111 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_STENCIL_INDEX</constant>
1112 and there is no stencil buffer.
1113 </para>
1114 <para>
1115 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_DEPTH_COMPONENT</constant>
1116 and there is no depth buffer.
1117 </para>
1118 <para>
1119 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_DEPTH_STENCIL</constant>
1120 and there is no depth buffer or if there is no stencil buffer.
1121 </para>
1122 <para>
1123 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is <constant>GL_DEPTH_STENCIL</constant>
1124 and <parameter>type</parameter> is not <constant>GL_UNSIGNED_INT_24_8</constant> or <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV</constant>.
1125 </para>
1126 <para>
1127 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
1128 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
1129 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
1130 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
1131 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
1132 and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
1133 </para>
1134 <para>
1135 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
1136 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
1137 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
1138 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
1139 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
1140 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
1141 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
1142 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
1143 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
1144 and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
1145 </para>
1146 <para>
1147 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1148 <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
1149 </para>
1150 <para>
1151 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1152 <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
1153 object such that the memory writes required would exceed the data store size.
1154 </para>
1155 <para>
1156 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
1157 <constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
1158 into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
1159 </para>
1160 <para>
1161 <constant>GL_INVALID_OPERATION</constant> is generated if <constant>GL_READ_FRAMEBUFFER_BINDING</constant>
1162 is non-zero, the read framebuffer is complete, and the value of <constant>GL_SAMPLE_BUFFERS</constant>
1163 for the read framebuffer is greater than zero.
1164 </para>
1165 </refsect1>
1166 <refsect1 id="associatedgets"><title>Associated Gets</title>
f37e7e3d
DH		 1167 <para>
1168 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_MODE</constant>
1169 </para>
7faf1d71
AW		 1170 <para>
1171 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
1172 </para>
1173 </refsect1>
1174 <refsect1 id="seealso"><title>See Also</title>
1175 <para>
1176 <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
1177 <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>
1178 </para>
1179 </refsect1>
1180 <refsect1 id="Copyright"><title>Copyright</title>
1181 <para>
1182 Copyright <trademark class="copyright"></trademark> 1991-2006
1183 Silicon Graphics, Inc. This document is licensed under the SGI
1184 Free Software B License. For details, see
1185 <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
1186 </para>
1187 </refsect1>
1188</refentry>
Unnamed repository; edit this file 'description' to name the repository.