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">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glReadPixels
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glReadPixels
</refname>
17 <refpurpose>read a block of pixels from the frame buffer
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
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>
33 <!-- eqn: ignoring delim $$ -->
34 <refsect1 id=
"parameters"><title>Parameters
</title>
37 <term><parameter>x
</parameter></term>
38 <term><parameter>y
</parameter></term>
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.
48 <term><parameter>width
</parameter></term>
49 <term><parameter>height
</parameter></term>
52 Specify the dimensions of the pixel rectangle.
53 <parameter>width
</parameter> and
<parameter>height
</parameter> of one correspond to a single pixel.
58 <term><parameter>format
</parameter></term>
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>.
77 <term><parameter>type
</parameter></term>
80 Specifies the data type of the pixel data.
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>.
110 <term><parameter>data
</parameter></term>
113 Returns the pixel data.
119 <refsect1 id=
"description"><title>Description
</title>
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.
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.
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=
")">
143 <mml:mi mathvariant=
"italic">x
</mml:mi>
145 <mml:mi mathvariant=
"italic">i
</mml:mi>
148 <mml:mi mathvariant=
"italic">y
</mml:mi>
150 <mml:mi mathvariant=
"italic">j
</mml:mi>
153 </mml:math></inlineequation>
155 <inlineequation><mml:math>
156 <!-- eqn: 0 <= i < width: -->
159 <mml:mo><=
</mml:mo>
160 <mml:mi mathvariant=
"italic">i
</mml:mi>
161 <mml:mo><</mml:mo>
162 <mml:mi mathvariant=
"italic">width
</mml:mi>
164 </mml:math></inlineequation>
166 <inlineequation><mml:math>
167 <!-- eqn: 0 <= j < height: -->
170 <mml:mo><=
</mml:mo>
171 <mml:mi mathvariant=
"italic">j
</mml:mi>
172 <mml:mo><</mml:mo>
173 <mml:mi mathvariant=
"italic">height
</mml:mi>
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
179 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>th
181 Pixels are returned in row order from the lowest to the highest row,
182 left to right in each row.
185 <parameter>format
</parameter> specifies the format for the returned pixel values;
190 <term><constant>GL_STENCIL_INDEX
</constant></term>
193 Stencil values are read from the stencil buffer.
198 <term><constant>GL_DEPTH_COMPONENT
</constant></term>
201 Depth values are read from the depth buffer.
202 Each component is converted to floating point such that the minimum depth
203 value maps to
0 and the maximum value maps to
1.
204 Each component is clamped to the range
205 <inlineequation><mml:math>
207 <mml:mfenced open=
"[" close=
"]">
211 </mml:math></inlineequation>.
216 <term><constant>GL_DEPTH_STENCIL
</constant></term>
219 Values are taken from both the depth and stencil buffers. The
<parameter>type
</parameter> parameter
220 must be
<constant>GL_UNSIGNED_INT_24_8
</constant> or
<constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV
</constant>.
225 <term><constant>GL_RED
</constant></term>
230 <term><constant>GL_GREEN
</constant></term>
235 <term><constant>GL_BLUE
</constant></term>
240 <term><constant>GL_RGB
</constant></term>
245 <term><constant>GL_BGR
</constant></term>
250 <term><constant>GL_RGBA
</constant></term>
255 <term><constant>GL_BGRA
</constant></term>
261 Finally, the indices or components
262 are converted to the proper format,
263 as specified by
<parameter>type
</parameter>.
264 If
<parameter>format
</parameter> is
<constant>GL_STENCIL_INDEX
</constant>
265 and
<parameter>type
</parameter> is not
<constant>GL_FLOAT
</constant>,
266 each index is masked with the mask value given in the following table.
267 If
<parameter>type
</parameter> is
<constant>GL_FLOAT
</constant>, then each integer index is converted to
268 single-precision floating-point format.
271 If
<parameter>format
</parameter> is
272 <constant>GL_RED
</constant>,
273 <constant>GL_GREEN
</constant>,
274 <constant>GL_BLUE
</constant>,
275 <constant>GL_RGB
</constant>,
276 <constant>GL_BGR
</constant>,
277 <constant>GL_RGBA
</constant>, or
278 <constant>GL_BGRA
</constant> and
<parameter>type
</parameter> is not
<constant>GL_FLOAT
</constant>,
279 each component is multiplied by the multiplier shown in the following table.
280 If type is
<constant>GL_FLOAT
</constant>, then each component is passed as is
281 (or converted to the client's single-precision floating-point format if
282 it is different from the one used by the GL).
286 <informaltable frame=
"topbot">
287 <tgroup cols=
"3" align=
"left">
289 <colspec align=
"center"/>
290 <colspec align=
"center"/>
293 <entry rowsep=
"1" align=
"left">
294 <parameter>type
</parameter>
296 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
299 <entry rowsep=
"1" align=
"center"><emphasis role=
"bold">
307 <constant>GL_UNSIGNED_BYTE
</constant>
309 <entry align=
"center">
310 <inlineequation><mml:math>
311 <!-- eqn: 2 sup 8 - 1: -->
313 <mml:msup><mml:mn>2</mml:mn>
319 </mml:math></inlineequation>
321 <entry align=
"center">
322 <inlineequation><mml:math>
323 <!-- eqn: (2 sup 8 - 1) c: -->
325 <mml:mfenced open=
"(" close=
")">
327 <mml:msup><mml:mn>2</mml:mn>
334 <mml:mo>⁢</mml:mo>
335 <mml:mi mathvariant=
"italic">c
</mml:mi>
337 </mml:math></inlineequation>
342 <constant>GL_BYTE
</constant>
344 <entry align=
"center">
345 <inlineequation><mml:math>
346 <!-- eqn: 2 sup 7 - 1: -->
348 <mml:msup><mml:mn>2</mml:mn>
354 </mml:math></inlineequation>
356 <entry align=
"center">
357 <inlineequation><mml:math>
358 <!-- eqn: {(2 sup 8 - 1) c - 1} / 2: -->
360 <mml:mfenced open=
"" close=
"">
362 <mml:mfenced open=
"(" close=
")">
364 <mml:msup><mml:mn>2</mml:mn>
371 <mml:mo>⁢</mml:mo>
372 <mml:mi mathvariant=
"italic">c
</mml:mi>
379 </mml:math></inlineequation>
384 <constant>GL_UNSIGNED_SHORT
</constant>
386 <entry align=
"center">
387 <inlineequation><mml:math>
388 <!-- eqn: 2 sup 16 - 1: -->
390 <mml:msup><mml:mn>2</mml:mn>
396 </mml:math></inlineequation>
398 <entry align=
"center">
399 <inlineequation><mml:math>
400 <!-- eqn: (2 sup 16 - 1) c: -->
402 <mml:mfenced open=
"(" close=
")">
404 <mml:msup><mml:mn>2</mml:mn>
411 <mml:mo>⁢</mml:mo>
412 <mml:mi mathvariant=
"italic">c
</mml:mi>
414 </mml:math></inlineequation>
419 <constant>GL_SHORT
</constant>
421 <entry align=
"center">
422 <inlineequation><mml:math>
423 <!-- eqn: 2 sup 15 - 1: -->
425 <mml:msup><mml:mn>2</mml:mn>
431 </mml:math></inlineequation>
433 <entry align=
"center">
434 <inlineequation><mml:math>
435 <!-- eqn: {(2 sup 16 - 1) c - 1} / 2: -->
437 <mml:mfenced open=
"" close=
"">
439 <mml:mfenced open=
"(" close=
")">
441 <mml:msup><mml:mn>2</mml:mn>
448 <mml:mo>⁢</mml:mo>
449 <mml:mi mathvariant=
"italic">c
</mml:mi>
456 </mml:math></inlineequation>
461 <constant>GL_UNSIGNED_INT
</constant>
463 <entry align=
"center">
464 <inlineequation><mml:math>
465 <!-- eqn: 2 sup 32 - 1: -->
467 <mml:msup><mml:mn>2</mml:mn>
473 </mml:math></inlineequation>
475 <entry align=
"center">
476 <inlineequation><mml:math>
477 <!-- eqn: (2 sup 32 - 1) c: -->
479 <mml:mfenced open=
"(" close=
")">
481 <mml:msup><mml:mn>2</mml:mn>
488 <mml:mo>⁢</mml:mo>
489 <mml:mi mathvariant=
"italic">c
</mml:mi>
491 </mml:math></inlineequation>
496 <constant>GL_INT
</constant>
498 <entry align=
"center">
499 <inlineequation><mml:math>
500 <!-- eqn: 2 sup 31 - 1: -->
502 <mml:msup><mml:mn>2</mml:mn>
508 </mml:math></inlineequation>
510 <entry align=
"center">
511 <inlineequation><mml:math>
512 <!-- eqn: {(2 sup 32 - 1) c - 1} / 2: -->
514 <mml:mfenced open=
"" close=
"">
516 <mml:mfenced open=
"(" close=
")">
518 <mml:msup><mml:mn>2</mml:mn>
525 <mml:mo>⁢</mml:mo>
526 <mml:mi mathvariant=
"italic">c
</mml:mi>
533 </mml:math></inlineequation>
538 <constant>GL_HALF_FLOAT
</constant>
540 <entry align=
"center">
543 <entry align=
"center">
544 <inlineequation><mml:math><mml:mi mathvariant=
"italic">c
</mml:mi></mml:math></inlineequation>
549 <constant>GL_FLOAT
</constant>
551 <entry align=
"center">
554 <entry align=
"center">
555 <inlineequation><mml:math><mml:mi mathvariant=
"italic">c
</mml:mi></mml:math></inlineequation>
560 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>
562 <entry align=
"center">
563 <inlineequation><mml:math>
564 <!-- eqn: 2 sup N - 1: -->
566 <mml:msup><mml:mn>2</mml:mn>
572 </mml:math></inlineequation>
574 <entry align=
"center">
575 <inlineequation><mml:math>
576 <!-- eqn: (2 sup N - 1) c: -->
578 <mml:mfenced open=
"(" close=
")">
580 <mml:msup><mml:mn>2</mml:mn>
587 <mml:mo>⁢</mml:mo>
588 <mml:mi mathvariant=
"italic">c
</mml:mi>
590 </mml:math></inlineequation>
595 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>
597 <entry align=
"center">
598 <inlineequation><mml:math>
599 <!-- eqn: 2 sup N - 1: -->
601 <mml:msup><mml:mn>2</mml:mn>
607 </mml:math></inlineequation>
609 <entry align=
"center">
610 <inlineequation><mml:math>
611 <!-- eqn: (2 sup N - 1) c: -->
613 <mml:mfenced open=
"(" close=
")">
615 <mml:msup><mml:mn>2</mml:mn>
622 <mml:mo>⁢</mml:mo>
623 <mml:mi mathvariant=
"italic">c
</mml:mi>
625 </mml:math></inlineequation>
630 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>
632 <entry align=
"center">
633 <inlineequation><mml:math>
634 <!-- eqn: 2 sup N - 1: -->
636 <mml:msup><mml:mn>2</mml:mn>
642 </mml:math></inlineequation>
644 <entry align=
"center">
645 <inlineequation><mml:math>
646 <!-- eqn: (2 sup N - 1) c: -->
648 <mml:mfenced open=
"(" close=
")">
650 <mml:msup><mml:mn>2</mml:mn>
657 <mml:mo>⁢</mml:mo>
658 <mml:mi mathvariant=
"italic">c
</mml:mi>
660 </mml:math></inlineequation>
665 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>
667 <entry align=
"center">
668 <inlineequation><mml:math>
669 <!-- eqn: 2 sup N - 1: -->
671 <mml:msup><mml:mn>2</mml:mn>
677 </mml:math></inlineequation>
679 <entry align=
"center">
680 <inlineequation><mml:math>
681 <!-- eqn: (2 sup N - 1) c: -->
683 <mml:mfenced open=
"(" close=
")">
685 <mml:msup><mml:mn>2</mml:mn>
692 <mml:mo>⁢</mml:mo>
693 <mml:mi mathvariant=
"italic">c
</mml:mi>
695 </mml:math></inlineequation>
700 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>
702 <entry align=
"center">
703 <inlineequation><mml:math>
704 <!-- eqn: 2 sup N - 1: -->
706 <mml:msup><mml:mn>2</mml:mn>
712 </mml:math></inlineequation>
714 <entry align=
"center">
715 <inlineequation><mml:math>
716 <!-- eqn: (2 sup N - 1) c: -->
718 <mml:mfenced open=
"(" close=
")">
720 <mml:msup><mml:mn>2</mml:mn>
727 <mml:mo>⁢</mml:mo>
728 <mml:mi mathvariant=
"italic">c
</mml:mi>
730 </mml:math></inlineequation>
735 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>
737 <entry align=
"center">
738 <inlineequation><mml:math>
739 <!-- eqn: 2 sup N - 1: -->
741 <mml:msup><mml:mn>2</mml:mn>
747 </mml:math></inlineequation>
749 <entry align=
"center">
750 <inlineequation><mml:math>
751 <!-- eqn: (2 sup N - 1) c: -->
753 <mml:mfenced open=
"(" close=
")">
755 <mml:msup><mml:mn>2</mml:mn>
762 <mml:mo>⁢</mml:mo>
763 <mml:mi mathvariant=
"italic">c
</mml:mi>
765 </mml:math></inlineequation>
770 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>
772 <entry align=
"center">
773 <inlineequation><mml:math>
774 <!-- eqn: 2 sup N - 1: -->
776 <mml:msup><mml:mn>2</mml:mn>
782 </mml:math></inlineequation>
784 <entry align=
"center">
785 <inlineequation><mml:math>
786 <!-- eqn: (2 sup N - 1) c: -->
788 <mml:mfenced open=
"(" close=
")">
790 <mml:msup><mml:mn>2</mml:mn>
797 <mml:mo>⁢</mml:mo>
798 <mml:mi mathvariant=
"italic">c
</mml:mi>
800 </mml:math></inlineequation>
805 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>
807 <entry align=
"center">
808 <inlineequation><mml:math>
809 <!-- eqn: 2 sup N - 1: -->
811 <mml:msup><mml:mn>2</mml:mn>
817 </mml:math></inlineequation>
819 <entry align=
"center">
820 <inlineequation><mml:math>
821 <!-- eqn: (2 sup N - 1) c: -->
823 <mml:mfenced open=
"(" close=
")">
825 <mml:msup><mml:mn>2</mml:mn>
832 <mml:mo>⁢</mml:mo>
833 <mml:mi mathvariant=
"italic">c
</mml:mi>
835 </mml:math></inlineequation>
840 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>
842 <entry align=
"center">
843 <inlineequation><mml:math>
844 <!-- eqn: 2 sup N - 1: -->
846 <mml:msup><mml:mn>2</mml:mn>
852 </mml:math></inlineequation>
854 <entry align=
"center">
855 <inlineequation><mml:math>
856 <!-- eqn: (2 sup N - 1) c: -->
858 <mml:mfenced open=
"(" close=
")">
860 <mml:msup><mml:mn>2</mml:mn>
867 <mml:mo>⁢</mml:mo>
868 <mml:mi mathvariant=
"italic">c
</mml:mi>
870 </mml:math></inlineequation>
875 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>
877 <entry align=
"center">
878 <inlineequation><mml:math>
879 <!-- eqn: 2 sup N - 1: -->
881 <mml:msup><mml:mn>2</mml:mn>
887 </mml:math></inlineequation>
889 <entry align=
"center">
890 <inlineequation><mml:math>
891 <!-- eqn: (2 sup N - 1) c: -->
893 <mml:mfenced open=
"(" close=
")">
895 <mml:msup><mml:mn>2</mml:mn>
902 <mml:mo>⁢</mml:mo>
903 <mml:mi mathvariant=
"italic">c
</mml:mi>
905 </mml:math></inlineequation>
910 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>
912 <entry align=
"center">
913 <inlineequation><mml:math>
914 <!-- eqn: 2 sup N - 1: -->
916 <mml:msup><mml:mn>2</mml:mn>
922 </mml:math></inlineequation>
924 <entry align=
"center">
925 <inlineequation><mml:math>
926 <!-- eqn: (2 sup N - 1) c: -->
928 <mml:mfenced open=
"(" close=
")">
930 <mml:msup><mml:mn>2</mml:mn>
937 <mml:mo>⁢</mml:mo>
938 <mml:mi mathvariant=
"italic">c
</mml:mi>
940 </mml:math></inlineequation>
945 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>
947 <entry align=
"center">
948 <inlineequation><mml:math>
949 <!-- eqn: 2 sup N - 1: -->
951 <mml:msup><mml:mn>2</mml:mn>
957 </mml:math></inlineequation>
959 <entry align=
"center">
960 <inlineequation><mml:math>
961 <!-- eqn: (2 sup N - 1) c: -->
963 <mml:mfenced open=
"(" close=
")">
965 <mml:msup><mml:mn>2</mml:mn>
972 <mml:mo>⁢</mml:mo>
973 <mml:mi mathvariant=
"italic">c
</mml:mi>
975 </mml:math></inlineequation>
980 <constant>GL_UNSIGNED_INT_24_8
</constant>
982 <entry align=
"center">
983 <inlineequation><mml:math>
984 <!-- eqn: 2 sup N - 1: -->
986 <mml:msup><mml:mn>2</mml:mn>
992 </mml:math></inlineequation>
994 <entry align=
"center">
995 <inlineequation><mml:math>
996 <!-- eqn: (2 sup N - 1) c: -->
998 <mml:mfenced open=
"(" close=
")">
1000 <mml:msup><mml:mn>2</mml:mn>
1007 <mml:mo>⁢</mml:mo>
1008 <mml:mi mathvariant=
"italic">c
</mml:mi>
1010 </mml:math></inlineequation>
1014 <entry align=
"left">
1015 <constant>GL_UNSIGNED_INT_10F_11F_11F_REV
</constant>
1017 <entry align=
"center">
1020 <entry align=
"left">
1025 <entry align=
"left">
1026 <constant>GL_UNSIGNED_INT_5_9_9_9_REV
</constant>
1028 <entry align=
"center">
1031 <entry align=
"left">
1036 <entry align=
"left">
1037 <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV
</constant>
1039 <entry align=
"center">
1042 <entry align=
"center">
1043 <inlineequation><mml:math><mml:mi mathvariant=
"italic">c
</mml:mi></mml:math></inlineequation> (Depth Only)
1050 Return values are placed in memory as follows.
1051 If
<parameter>format
</parameter> is
1052 <constant>GL_STENCIL_INDEX
</constant>,
1053 <constant>GL_DEPTH_COMPONENT
</constant>,
1054 <constant>GL_RED
</constant>,
1055 <constant>GL_GREEN
</constant>, or
1056 <constant>GL_BLUE
</constant>,
1057 a single value is returned and the data for the
1058 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>th
1060 <inlineequation><mml:math><mml:mi mathvariant=
"italic">j
</mml:mi></mml:math></inlineequation>th
1062 is placed in location
1063 <inlineequation><mml:math>
1064 <!-- eqn: (j) width + i: -->
1066 <mml:mfenced open=
"(" close=
")">
1067 <mml:mi mathvariant=
"italic">j
</mml:mi>
1069 <mml:mo>⁢</mml:mo>
1070 <mml:mi mathvariant=
"italic">width
</mml:mi>
1072 <mml:mi mathvariant=
"italic">i
</mml:mi>
1074 </mml:math></inlineequation>.
1075 <constant>GL_RGB
</constant> and
<constant>GL_BGR
</constant> return three values,
1076 <constant>GL_RGBA
</constant> and
<constant>GL_BGRA
</constant> return four values for each pixel,
1077 with all values corresponding to a single pixel occupying contiguous space
1078 in
<parameter>data
</parameter>.
1079 Storage parameters set by
<citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
1080 such as
<constant>GL_PACK_LSB_FIRST
</constant> and
<constant>GL_PACK_SWAP_BYTES
</constant>,
1081 affect the way that data is written into memory.
1082 See
<citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> for a description.
1085 <refsect1 id=
"notes"><title>Notes
</title>
1087 Values for pixels that lie outside the window
1088 connected to the current GL context are undefined.
1091 If an error is generated,
1092 no change is made to the contents of
<parameter>data
</parameter>.
1095 <refsect1 id=
"errors"><title>Errors
</title>
1097 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> or
<parameter>type
</parameter> is not an
1101 <constant>GL_INVALID_VALUE
</constant> is generated if either
<parameter>width
</parameter> or
<parameter>height
</parameter> is negative.
1104 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>format
</parameter> is
<constant>GL_STENCIL_INDEX
</constant>
1105 and there is no stencil buffer.
1108 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>format
</parameter> is
<constant>GL_DEPTH_COMPONENT
</constant>
1109 and there is no depth buffer.
1112 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>format
</parameter> is
<constant>GL_DEPTH_STENCIL
</constant>
1113 and there is no depth buffer or if there is no stencil buffer.
1116 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is
<constant>GL_DEPTH_STENCIL
</constant>
1117 and
<parameter>type
</parameter> is not
<constant>GL_UNSIGNED_INT_24_8
</constant> or
<constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV
</constant>.
1120 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
1121 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
1122 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
1123 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>, or
1124 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>
1125 and
<parameter>format
</parameter> is not
<constant>GL_RGB
</constant>.
1128 <constant>GL_INVALID_OPERATION
</constant> is generated if
<parameter>type
</parameter> is one of
1129 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
1130 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
1131 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
1132 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
1133 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
1134 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
1135 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, or
1136 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>
1137 and
<parameter>format
</parameter> is neither
<constant>GL_RGBA
</constant> nor
<constant>GL_BGRA
</constant>.
1140 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
1141 <constant>GL_PIXEL_PACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
1144 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
1145 <constant>GL_PIXEL_PACK_BUFFER
</constant> target and the data would be packed to the buffer
1146 object such that the memory writes required would exceed the data store size.
1149 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
1150 <constant>GL_PIXEL_PACK_BUFFER
</constant> target and
<parameter>data
</parameter> is not evenly divisible
1151 into the number of bytes needed to store in memory a datum indicated by
<parameter>type
</parameter>.
1154 <constant>GL_INVALID_OPERATION
</constant> is generated if
<constant>GL_READ_FRAMEBUFFER_BINDING
</constant>
1155 is non-zero, the read framebuffer is complete, and the value of
<constant>GL_SAMPLE_BUFFERS
</constant>
1156 for the read framebuffer is greater than zero.
1159 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
1161 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_PACK_BUFFER_BINDING
</constant>
1164 <refsect1 id=
"seealso"><title>See Also
</title>
1166 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
1167 <citerefentry><refentrytitle>glReadBuffer
</refentrytitle></citerefentry>
1170 <refsect1 id=
"Copyright"><title>Copyright
</title>
1172 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
1173 Silicon Graphics, Inc. This document is licensed under the SGI
1174 Free Software B License. For details, see
1175 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.