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