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 / 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.
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>.
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.
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
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>
1167 <para>
1168 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_MODE</constant>
1169 </para>
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.