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