upstream-doc/man2/glReadPixels.xml

   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_COLOR_INDEX</constant>,
  64                     <constant>GL_STENCIL_INDEX</constant>,
  65                     <constant>GL_DEPTH_COMPONENT</constant>,
  66                     <constant>GL_RED</constant>,
  67                     <constant>GL_GREEN</constant>,
  68                     <constant>GL_BLUE</constant>,
  69                     <constant>GL_ALPHA</constant>,
  70                     <constant>GL_RGB</constant>,
  71                     <constant>GL_BGR</constant>,
  72                     <constant>GL_RGBA</constant>,
  73                     <constant>GL_BGRA</constant>,
  74                     <constant>GL_LUMINANCE</constant>, and
  75                     <constant>GL_LUMINANCE_ALPHA</constant>.
  76                 </para>
  77             </listitem>
  78         </varlistentry>
  79         <varlistentry>
  80             <term><parameter>type</parameter></term>
  81             <listitem>
  82                 <para>
  83                     Specifies the data type of the pixel data.
  84                     Must be one of
  85                     <constant>GL_UNSIGNED_BYTE</constant>,
  86                     <constant>GL_BYTE</constant>,
  87                     <constant>GL_BITMAP</constant>,
  88                     <constant>GL_UNSIGNED_SHORT</constant>,
  89                     <constant>GL_SHORT</constant>,
  90                     <constant>GL_UNSIGNED_INT</constant>,
  91                     <constant>GL_INT</constant>,
  92                     <constant>GL_FLOAT</constant>,
  93                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
  94                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
  95                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
  96                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
  97                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
  98                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
  99                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 100                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 101                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 102                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 103                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 104                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 105                 </para>
 106             </listitem>
 107         </varlistentry>
 108         <varlistentry>
 109             <term><parameter>data</parameter></term>
 110             <listitem>
 111                 <para>
 112                     Returns the pixel data.
 113                 </para>
 114             </listitem>
 115         </varlistentry>
 116         </variablelist>
 117     </refsect1>
 118     <refsect1 id="description"><title>Description</title>
 119         <para>
 120             <function>glReadPixels</function> returns pixel data from the frame buffer,
 121             starting with the pixel whose lower left corner
 122             is at location (<parameter>x</parameter>, <parameter>y</parameter>),
 123             into client memory starting at location <parameter>data</parameter>.
 124             Several parameters control the processing of the pixel data before
 125             it is placed into client memory.
 126             These parameters are set with three commands:
 127             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 128             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>, and
 129             <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>.
 130             This reference page describes the effects on <function>glReadPixels</function> of most,
 131             but not all of the parameters specified by these three commands.
 132         </para>
 133         <para>
 134             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
 135             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a block of pixels is
 136             requested, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store
 137             rather than a pointer to client memory.
 138         </para>
 139         <para>
 140             When the <code>ARB_imaging</code> extension is supported, the pixel data may
 141             be processed by additional operations including color table lookup,
 142             color matrix transformations, convolutions, histograms, and minimum and
 143             maximum pixel value computations.
 144         </para>
 145         <para>
 146             <function>glReadPixels</function> returns values from each pixel with lower left corner at
 147             <inlineequation><mml:math>
 148                 <!-- eqn: (x + i, y + j):-->
 149                 <mml:mfenced open="(" close=")">
 150                     <mml:mrow>
 151                         <mml:mi mathvariant="italic">x</mml:mi>
 152                         <mml:mo>+</mml:mo>
 153                         <mml:mi mathvariant="italic">i</mml:mi>
 154                     </mml:mrow>
 155                     <mml:mrow>
 156                         <mml:mi mathvariant="italic">y</mml:mi>
 157                         <mml:mo>+</mml:mo>
 158                         <mml:mi mathvariant="italic">j</mml:mi>
 159                     </mml:mrow>
 160                 </mml:mfenced>
 161             </mml:math></inlineequation>
 162             for
 163             <inlineequation><mml:math>
 164                 <!-- eqn: 0 <= i < width:-->
 165                 <mml:mrow>
 166                     <mml:mn>0</mml:mn>
 167                     <mml:mo>&lt;=</mml:mo>
 168                     <mml:mi mathvariant="italic">i</mml:mi>
 169                     <mml:mo>&lt;</mml:mo>
 170                     <mml:mi mathvariant="italic">width</mml:mi>
 171                 </mml:mrow>
 172             </mml:math></inlineequation>
 173             and
 174             <inlineequation><mml:math>
 175                 <!-- eqn: 0 <= j < height:-->
 176                 <mml:mrow>
 177                     <mml:mn>0</mml:mn>
 178                     <mml:mo>&lt;=</mml:mo>
 179                     <mml:mi mathvariant="italic">j</mml:mi>
 180                     <mml:mo>&lt;</mml:mo>
 181                     <mml:mi mathvariant="italic">height</mml:mi>
 182                 </mml:mrow>
 183             </mml:math></inlineequation>.
 184             This pixel is said to be the
 185             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 186             pixel in the
 187             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 188             row.
 189             Pixels are returned in row order from the lowest to the highest row,
 190             left to right in each row.
 191         </para>
 192         <para>
 193             <parameter>format</parameter> specifies the format for the returned pixel values;
 194             accepted values are:
 195         </para>
 196         <variablelist>
 197             <varlistentry>
 198                 <term><constant>GL_COLOR_INDEX</constant></term>
 199                 <listitem>
 200                     <para>
 201                         Color indices are read from the color buffer
 202                         selected by <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>.
 203                         Each index is converted to fixed point,
 204                         shifted left or right depending on the value and sign of <constant>GL_INDEX_SHIFT</constant>,
 205                         and added to <constant>GL_INDEX_OFFSET</constant>.
 206                         If <constant>GL_MAP_COLOR</constant> is <constant>GL_TRUE</constant>,
 207                         indices are replaced by their mappings in the table <constant>GL_PIXEL_MAP_I_TO_I</constant>.
 208                     </para>
 209                 </listitem>
 210             </varlistentry>
 211             <varlistentry>
 212                 <term><constant>GL_STENCIL_INDEX</constant></term>
 213                 <listitem>
 214                     <para>
 215                         Stencil values are read from the stencil buffer.
 216                         Each index is converted to fixed point,
 217                         shifted left or right depending on the value and sign of <constant>GL_INDEX_SHIFT</constant>,
 218                         and added to <constant>GL_INDEX_OFFSET</constant>.
 219                         If <constant>GL_MAP_STENCIL</constant> is <constant>GL_TRUE</constant>,
 220                         indices are replaced by their mappings in the table <constant>GL_PIXEL_MAP_S_TO_S</constant>.
 221                     </para>
 222                 </listitem>
 223             </varlistentry>
 224             <varlistentry>
 225                 <term><constant>GL_DEPTH_COMPONENT</constant></term>
 226                 <listitem>
 227                     <para>
 228                         Depth values are read from the depth buffer.
 229                         Each component is converted to floating point such that the minimum depth
 230                         value maps to 0 and the maximum value maps to 1.
 231                         Each component is then multiplied by <constant>GL_DEPTH_SCALE</constant>,
 232                         added to <constant>GL_DEPTH_BIAS</constant>,
 233                         and finally clamped to the range
 234                         <inlineequation><mml:math>
 235                             <!-- eqn: [0,1]:-->
 236                             <mml:mfenced open="[" close="]">
 237                                 <mml:mn>0</mml:mn>
 238                                 <mml:mn>1</mml:mn>
 239                             </mml:mfenced>
 240                         </mml:math></inlineequation>.
 241                     </para>
 242                 </listitem>
 243             </varlistentry>
 244             <varlistentry>
 245                 <term><constant>GL_RED</constant></term>
 246                 <listitem>
 247                 </listitem>
 248             </varlistentry>
 249             <varlistentry>
 250                 <term><constant>GL_GREEN</constant></term>
 251                 <listitem>
 252                 </listitem>
 253             </varlistentry>
 254             <varlistentry>
 255                 <term><constant>GL_BLUE</constant></term>
 256                 <listitem>
 257                 </listitem>
 258             </varlistentry>
 259             <varlistentry>
 260                 <term><constant>GL_ALPHA</constant></term>
 261                 <listitem>
 262                 </listitem>
 263             </varlistentry>
 264             <varlistentry>
 265                 <term><constant>GL_RGB</constant></term>
 266                 <listitem>
 267                 </listitem>
 268             </varlistentry>
 269             <varlistentry>
 270                 <term><constant>GL_BGR</constant></term>
 271                 <listitem>
 272                 </listitem>
 273             </varlistentry>
 274             <varlistentry>
 275                 <term><constant>GL_RGBA</constant></term>
 276                 <listitem>
 277                 </listitem>
 278             </varlistentry>
 279             <varlistentry>
 280                 <term><constant>GL_BGRA</constant></term>
 281                 <listitem>
 282                 </listitem>
 283             </varlistentry>
 284             <varlistentry>
 285                 <term><constant>GL_LUMINANCE</constant></term>
 286                 <listitem>
 287                 </listitem>
 288             </varlistentry>
 289             <varlistentry>
 290                 <term><constant>GL_LUMINANCE_ALPHA</constant></term>
 291                 <listitem>
 292                     <para>
 293                         Processing differs depending on whether color buffers store color indices
 294                         or RGBA color components.
 295                         If color indices are stored,
 296                         they are read from the color buffer selected by <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>.
 297                         Each index is converted to fixed point,
 298                         shifted left or right depending on the value and sign of <constant>GL_INDEX_SHIFT</constant>,
 299                         and added to <constant>GL_INDEX_OFFSET</constant>.
 300                         Indices are then replaced by the red,
 301                         green,
 302                         blue,
 303                         and alpha values obtained by indexing the tables
 304                         <constant>GL_PIXEL_MAP_I_TO_R</constant>,
 305                         <constant>GL_PIXEL_MAP_I_TO_G</constant>,
 306                         <constant>GL_PIXEL_MAP_I_TO_B</constant>, and
 307                         <constant>GL_PIXEL_MAP_I_TO_A</constant>.
 308                         Each table must be of size
 309                         <inlineequation><mml:math>
 310                             <!-- eqn: 2 sup n:-->
 311                             <mml:msup><mml:mn>2</mml:mn>
 312                             <mml:mi mathvariant="italic">n</mml:mi>
 313                             </mml:msup>
 314                         </mml:math></inlineequation>,
 315                         but
 316                         <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
 317                         may be different for
 318                         different tables.
 319                         Before an index is used to look up a value in a table of
 320                         size
 321                         <inlineequation><mml:math>
 322                             <!-- eqn: 2 sup n:-->
 323                             <mml:msup><mml:mn>2</mml:mn>
 324                             <mml:mi mathvariant="italic">n</mml:mi>
 325                             </mml:msup>
 326                         </mml:math></inlineequation>,
 327                         it must be masked against
 328                         <inlineequation><mml:math>
 329                             <!-- eqn: 2 sup n - 1:-->
 330                             <mml:mrow>
 331                                 <mml:msup><mml:mn>2</mml:mn>
 332                                 <mml:mi mathvariant="italic">n</mml:mi>
 333                                 </mml:msup>
 334                                 <mml:mo>-</mml:mo>
 335                                 <mml:mn>1</mml:mn>
 336                             </mml:mrow>
 337                         </mml:math></inlineequation>.
 338                     </para>
 339                     <para>
 340                         If RGBA color components are stored in the color buffers,
 341                         they are read from the color buffer selected by <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>.
 342                         Each color component is converted to floating point such that zero intensity
 343                         maps to 0.0 and full intensity maps to 1.0.
 344                         Each component is then multiplied by <constant>GL_c_SCALE</constant> and
 345                         added to <constant>GL_c_BIAS</constant>,
 346                         where <emphasis>c</emphasis> is RED, GREEN, BLUE, or ALPHA.
 347                         Finally,
 348                         if <constant>GL_MAP_COLOR</constant> is <constant>GL_TRUE</constant>,
 349                         each component is clamped to the range
 350                         <inlineequation><mml:math>
 351                             <!-- eqn: [0,1]:-->
 352                             <mml:mfenced open="[" close="]">
 353                                 <mml:mn>0</mml:mn>
 354                                 <mml:mn>1</mml:mn>
 355                             </mml:mfenced>
 356                         </mml:math></inlineequation>,
 357                         scaled to the size of its corresponding table, and is then
 358                         replaced by its mapping in the table
 359                         <constant>GL_PIXEL_MAP_c_TO_c</constant>,
 360                         where <emphasis>c</emphasis> is R, G, B, or A.
 361                     </para>
 362                     <para>
 363                         Unneeded data is then discarded.
 364                         For example,
 365                         <constant>GL_RED</constant> discards the green, blue, and alpha components,
 366                         while <constant>GL_RGB</constant> discards only the alpha component.
 367                         <constant>GL_LUMINANCE</constant> computes a single-component value as the sum of
 368                         the red,
 369                         green,
 370                         and blue components,
 371                         and <constant>GL_LUMINANCE_ALPHA</constant> does the same,
 372                         while keeping alpha as a second value.
 373                         The final values are clamped to the range
 374                         <inlineequation><mml:math>
 375                             <!-- eqn: [0,1]:-->
 376                             <mml:mfenced open="[" close="]">
 377                                 <mml:mn>0</mml:mn>
 378                                 <mml:mn>1</mml:mn>
 379                             </mml:mfenced>
 380                         </mml:math></inlineequation>.
 381                     </para>
 382                 </listitem>
 383             </varlistentry>
 384         </variablelist>
 385         <para>
 386             The shift,
 387             scale,
 388             bias,
 389             and lookup factors just described are all specified by
 390             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
 391             The lookup table contents themselves are specified by <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>.
 392         </para>
 393         <para>
 394             Finally, the indices or components
 395             are converted to the proper format,
 396             as specified by <parameter>type</parameter>.
 397             If <parameter>format</parameter> is <constant>GL_COLOR_INDEX</constant> or <constant>GL_STENCIL_INDEX</constant>
 398             and <parameter>type</parameter> is not <constant>GL_FLOAT</constant>,
 399             each index is masked with the mask value given in the following table.
 400             If <parameter>type</parameter> is <constant>GL_FLOAT</constant>, then each integer index is converted to
 401             single-precision floating-point format.
 402         </para>
 403         <para>
 404             If <parameter>format</parameter> is
 405             <constant>GL_RED</constant>,
 406             <constant>GL_GREEN</constant>,
 407             <constant>GL_BLUE</constant>,
 408             <constant>GL_ALPHA</constant>,
 409             <constant>GL_RGB</constant>,
 410             <constant>GL_BGR</constant>,
 411             <constant>GL_RGBA</constant>,
 412             <constant>GL_BGRA</constant>,
 413             <constant>GL_LUMINANCE</constant>, or
 414             <constant>GL_LUMINANCE_ALPHA</constant> and <parameter>type</parameter> is not <constant>GL_FLOAT</constant>,
 415             each component is multiplied by the multiplier shown in the following table.
 416             If type is <constant>GL_FLOAT</constant>, then each component is passed as is
 417             (or converted to the client's single-precision floating-point format if
 418             it is different from the one used by the GL).
 419         </para>
 420         <para>
 421         </para>
 422         <informaltable frame="topbot">
 423             <tgroup cols="3" align="left">
 424                 <colspec/>
 425                 <colspec align="center"/>
 426                 <colspec align="center"/>
 427                 <thead>
 428                     <row>
 429                         <entry rowsep="1" align="left">
 430                         <parameter>type</parameter>
 431                         </entry>
 432                         <entry rowsep="1" align="center"><emphasis role="bold">
 433                         Index Mask
 434                         </emphasis></entry>
 435                         <entry rowsep="1" align="center"><emphasis role="bold">
 436                         Component Conversion
 437                         </emphasis></entry>
 438                     </row>
 439                 </thead>
 440                 <tbody>
 441                     <row>
 442                         <entry align="left">
 443                         <constant>GL_UNSIGNED_BYTE</constant>
 444                         </entry>
 445                         <entry align="center">
 446                         <inlineequation><mml:math>
 447                             <!-- eqn: 2 sup 8 - 1:-->
 448                             <mml:mrow>
 449                                 <mml:msup><mml:mn>2</mml:mn>
 450                                 <mml:mn>8</mml:mn>
 451                                 </mml:msup>
 452                                 <mml:mo>-</mml:mo>
 453                                 <mml:mn>1</mml:mn>
 454                             </mml:mrow>
 455                         </mml:math></inlineequation>
 456                         </entry>
 457                         <entry align="center">
 458                         <inlineequation><mml:math>
 459                             <!-- eqn: (2 sup 8 - 1) c:-->
 460                             <mml:mrow>
 461                                 <mml:mfenced open="(" close=")">
 462                                     <mml:mrow>
 463                                         <mml:msup><mml:mn>2</mml:mn>
 464                                         <mml:mn>8</mml:mn>
 465                                         </mml:msup>
 466                                         <mml:mo>-</mml:mo>
 467                                         <mml:mn>1</mml:mn>
 468                                     </mml:mrow>
 469                                 </mml:mfenced>
 470                                 <mml:mo>&it;</mml:mo>
 471                                 <mml:mi mathvariant="italic">c</mml:mi>
 472                             </mml:mrow>
 473                         </mml:math></inlineequation>
 474                         </entry>
 475                     </row>
 476                     <row>
 477                         <entry align="left">
 478                         <constant>GL_BYTE</constant>
 479                         </entry>
 480                         <entry align="center">
 481                         <inlineequation><mml:math>
 482                             <!-- eqn: 2 sup 7 - 1:-->
 483                             <mml:mrow>
 484                                 <mml:msup><mml:mn>2</mml:mn>
 485                                 <mml:mn>7</mml:mn>
 486                                 </mml:msup>
 487                                 <mml:mo>-</mml:mo>
 488                                 <mml:mn>1</mml:mn>
 489                             </mml:mrow>
 490                         </mml:math></inlineequation>
 491                         </entry>
 492                         <entry align="center">
 493                         <inlineequation><mml:math>
 494                             <!-- eqn: {(2 sup 8 - 1) c - 1} / 2:-->
 495                             <mml:mfrac>
 496                                 <mml:mfenced open="" close="">
 497                                     <mml:mrow>
 498                                         <mml:mfenced open="(" close=")">
 499                                             <mml:mrow>
 500                                                 <mml:msup><mml:mn>2</mml:mn>
 501                                                 <mml:mn>8</mml:mn>
 502                                                 </mml:msup>
 503                                                 <mml:mo>-</mml:mo>
 504                                                 <mml:mn>1</mml:mn>
 505                                             </mml:mrow>
 506                                         </mml:mfenced>
 507                                         <mml:mo>&it;</mml:mo>
 508                                         <mml:mi mathvariant="italic">c</mml:mi>
 509                                         <mml:mo>-</mml:mo>
 510                                         <mml:mn>1</mml:mn>
 511                                     </mml:mrow>
 512                                 </mml:mfenced>
 513                                 <mml:mn>2</mml:mn>
 514                             </mml:mfrac>
 515                         </mml:math></inlineequation>
 516                         </entry>
 517                     </row>
 518                     <row>
 519                         <entry align="left">
 520                         <constant>GL_BITMAP</constant>
 521                         </entry>
 522                         <entry align="center">
 523                         <inlineequation><mml:math>
 524                             <!-- eqn: 1:-->
 525                             <mml:mn>1</mml:mn>
 526                         </mml:math></inlineequation>
 527                         </entry>
 528                         <entry align="center">
 529                         <inlineequation><mml:math>
 530                             <!-- eqn: 1:-->
 531                             <mml:mn>1</mml:mn>
 532                         </mml:math></inlineequation>
 533                         </entry>
 534                     </row>
 535                     <row>
 536                         <entry align="left">
 537                         <constant>GL_UNSIGNED_SHORT</constant>
 538                         </entry>
 539                         <entry align="center">
 540                         <inlineequation><mml:math>
 541                             <!-- eqn: 2 sup 16 - 1:-->
 542                             <mml:mrow>
 543                                 <mml:msup><mml:mn>2</mml:mn>
 544                                 <mml:mn>16</mml:mn>
 545                                 </mml:msup>
 546                                 <mml:mo>-</mml:mo>
 547                                 <mml:mn>1</mml:mn>
 548                             </mml:mrow>
 549                         </mml:math></inlineequation>
 550                         </entry>
 551                         <entry align="center">
 552                         <inlineequation><mml:math>
 553                             <!-- eqn: (2 sup 16 - 1) c:-->
 554                             <mml:mrow>
 555                                 <mml:mfenced open="(" close=")">
 556                                     <mml:mrow>
 557                                         <mml:msup><mml:mn>2</mml:mn>
 558                                         <mml:mn>16</mml:mn>
 559                                         </mml:msup>
 560                                         <mml:mo>-</mml:mo>
 561                                         <mml:mn>1</mml:mn>
 562                                     </mml:mrow>
 563                                 </mml:mfenced>
 564                                 <mml:mo>&it;</mml:mo>
 565                                 <mml:mi mathvariant="italic">c</mml:mi>
 566                             </mml:mrow>
 567                         </mml:math></inlineequation>
 568                         </entry>
 569                     </row>
 570                     <row>
 571                         <entry align="left">
 572                         <constant>GL_SHORT</constant>
 573                         </entry>
 574                         <entry align="center">
 575                         <inlineequation><mml:math>
 576                             <!-- eqn: 2 sup 15 - 1:-->
 577                             <mml:mrow>
 578                                 <mml:msup><mml:mn>2</mml:mn>
 579                                 <mml:mn>15</mml:mn>
 580                                 </mml:msup>
 581                                 <mml:mo>-</mml:mo>
 582                                 <mml:mn>1</mml:mn>
 583                             </mml:mrow>
 584                         </mml:math></inlineequation>
 585                         </entry>
 586                         <entry align="center">
 587                         <inlineequation><mml:math>
 588                             <!-- eqn: {(2 sup 16 - 1) c - 1} / 2:-->
 589                             <mml:mfrac>
 590                                 <mml:mfenced open="" close="">
 591                                     <mml:mrow>
 592                                         <mml:mfenced open="(" close=")">
 593                                             <mml:mrow>
 594                                                 <mml:msup><mml:mn>2</mml:mn>
 595                                                 <mml:mn>16</mml:mn>
 596                                                 </mml:msup>
 597                                                 <mml:mo>-</mml:mo>
 598                                                 <mml:mn>1</mml:mn>
 599                                             </mml:mrow>
 600                                         </mml:mfenced>
 601                                         <mml:mo>&it;</mml:mo>
 602                                         <mml:mi mathvariant="italic">c</mml:mi>
 603                                         <mml:mo>-</mml:mo>
 604                                         <mml:mn>1</mml:mn>
 605                                     </mml:mrow>
 606                                 </mml:mfenced>
 607                                 <mml:mn>2</mml:mn>
 608                             </mml:mfrac>
 609                         </mml:math></inlineequation>
 610                         </entry>
 611                     </row>
 612                     <row>
 613                         <entry align="left">
 614                         <constant>GL_UNSIGNED_INT</constant>
 615                         </entry>
 616                         <entry align="center">
 617                         <inlineequation><mml:math>
 618                             <!-- eqn: 2 sup 32 - 1:-->
 619                             <mml:mrow>
 620                                 <mml:msup><mml:mn>2</mml:mn>
 621                                 <mml:mn>32</mml:mn>
 622                                 </mml:msup>
 623                                 <mml:mo>-</mml:mo>
 624                                 <mml:mn>1</mml:mn>
 625                             </mml:mrow>
 626                         </mml:math></inlineequation>
 627                         </entry>
 628                         <entry align="center">
 629                         <inlineequation><mml:math>
 630                             <!-- eqn: (2 sup 32 - 1) c:-->
 631                             <mml:mrow>
 632                                 <mml:mfenced open="(" close=")">
 633                                     <mml:mrow>
 634                                         <mml:msup><mml:mn>2</mml:mn>
 635                                         <mml:mn>32</mml:mn>
 636                                         </mml:msup>
 637                                         <mml:mo>-</mml:mo>
 638                                         <mml:mn>1</mml:mn>
 639                                     </mml:mrow>
 640                                 </mml:mfenced>
 641                                 <mml:mo>&it;</mml:mo>
 642                                 <mml:mi mathvariant="italic">c</mml:mi>
 643                             </mml:mrow>
 644                         </mml:math></inlineequation>
 645                         </entry>
 646                     </row>
 647                     <row>
 648                         <entry align="left">
 649                         <constant>GL_INT</constant>
 650                         </entry>
 651                         <entry align="center">
 652                         <inlineequation><mml:math>
 653                             <!-- eqn: 2 sup 31 - 1:-->
 654                             <mml:mrow>
 655                                 <mml:msup><mml:mn>2</mml:mn>
 656                                 <mml:mn>31</mml:mn>
 657                                 </mml:msup>
 658                                 <mml:mo>-</mml:mo>
 659                                 <mml:mn>1</mml:mn>
 660                             </mml:mrow>
 661                         </mml:math></inlineequation>
 662                         </entry>
 663                         <entry align="center">
 664                         <inlineequation><mml:math>
 665                             <!-- eqn: {(2 sup 32 - 1) c - 1} / 2:-->
 666                             <mml:mfrac>
 667                                 <mml:mfenced open="" close="">
 668                                     <mml:mrow>
 669                                         <mml:mfenced open="(" close=")">
 670                                             <mml:mrow>
 671                                                 <mml:msup><mml:mn>2</mml:mn>
 672                                                 <mml:mn>32</mml:mn>
 673                                                 </mml:msup>
 674                                                 <mml:mo>-</mml:mo>
 675                                                 <mml:mn>1</mml:mn>
 676                                             </mml:mrow>
 677                                         </mml:mfenced>
 678                                         <mml:mo>&it;</mml:mo>
 679                                         <mml:mi mathvariant="italic">c</mml:mi>
 680                                         <mml:mo>-</mml:mo>
 681                                         <mml:mn>1</mml:mn>
 682                                     </mml:mrow>
 683                                 </mml:mfenced>
 684                                 <mml:mn>2</mml:mn>
 685                             </mml:mfrac>
 686                         </mml:math></inlineequation>
 687                         </entry>
 688                     </row>
 689                     <row>
 690                         <entry align="left">
 691                         <constant>GL_FLOAT</constant>
 692                         </entry>
 693                         <entry align="center">
 694                         none
 695                         </entry>
 696                         <entry align="center">
 697                         <inlineequation><mml:math><mml:mi mathvariant="italic">c</mml:mi></mml:math></inlineequation>
 698                         </entry>
 699                     </row>
 700                 </tbody>
 701             </tgroup>
 702         </informaltable>
 703         <para>
 704             Return values are placed in memory as follows.
 705             If <parameter>format</parameter> is
 706             <constant>GL_COLOR_INDEX</constant>,
 707             <constant>GL_STENCIL_INDEX</constant>,
 708             <constant>GL_DEPTH_COMPONENT</constant>,
 709             <constant>GL_RED</constant>,
 710             <constant>GL_GREEN</constant>,
 711             <constant>GL_BLUE</constant>,
 712             <constant>GL_ALPHA</constant>, or
 713             <constant>GL_LUMINANCE</constant>,
 714             a single value is returned and the data for the
 715             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 716             pixel in the
 717             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 718             row
 719             is placed in location
 720             <inlineequation><mml:math>
 721                 <!-- eqn: (j) width + i:-->
 722                 <mml:mrow>
 723                     <mml:mfenced open="(" close=")">
 724                         <mml:mi mathvariant="italic">j</mml:mi>
 725                     </mml:mfenced>
 726                     <mml:mo>&it;</mml:mo>
 727                     <mml:mi mathvariant="italic">width</mml:mi>
 728                     <mml:mo>+</mml:mo>
 729                     <mml:mi mathvariant="italic">i</mml:mi>
 730                 </mml:mrow>
 731             </mml:math></inlineequation>.
 732             <constant>GL_RGB</constant> and <constant>GL_BGR</constant> return three values,
 733             <constant>GL_RGBA</constant> and <constant>GL_BGRA</constant> return four values,
 734             and <constant>GL_LUMINANCE_ALPHA</constant> returns two values for each pixel,
 735             with all values corresponding to a single pixel occupying contiguous space
 736             in <parameter>data</parameter>.
 737             Storage parameters set by <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 738             such as <constant>GL_PACK_LSB_FIRST</constant> and <constant>GL_PACK_SWAP_BYTES</constant>,
 739             affect the way that data is written into memory.
 740             See <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> for a description.
 741         </para>
 742     </refsect1>
 743     <refsect1 id="notes"><title>Notes</title>
 744         <para>
 745             Values for pixels that lie outside the window
 746             connected to the current GL context are undefined.
 747         </para>
 748         <para>
 749             If an error is generated,
 750             no change is made to the contents of <parameter>data</parameter>.
 751         </para>
 752     </refsect1>
 753     <refsect1 id="errors"><title>Errors</title>
 754         <para>
 755             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> or <parameter>type</parameter> is not an
 756             accepted value.
 757         </para>
 758         <para>
 759             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and <parameter>format</parameter> is
 760             not <constant>GL_COLOR_INDEX</constant> or <constant>GL_STENCIL_INDEX</constant>.
 761         </para>
 762         <para>
 763             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
 764         </para>
 765         <para>
 766             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_COLOR_INDEX</constant>
 767             and the color buffers store RGBA color components.
 768         </para>
 769         <para>
 770             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_STENCIL_INDEX</constant>
 771             and there is no stencil buffer.
 772         </para>
 773         <para>
 774             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> is <constant>GL_DEPTH_COMPONENT</constant>
 775             and there is no depth buffer.
 776         </para>
 777         <para>
 778             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 779             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 780             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 781             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 782             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 783             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 784         </para>
 785         <para>
 786             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 787             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 788             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 789             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 790             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 791             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 792             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 793             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 794             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 795             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 796         </para>
 797         <para>
 798             The formats <constant>GL_BGR</constant>, and <constant>GL_BGRA</constant> and types
 799             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 800             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 801             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 802             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 803             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 804             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 805             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 806             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 807             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 808             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 809             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 810             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are available only if the GL version
 811             is 1.2 or greater.
 812         </para>
 813         <para>
 814             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 815             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 816         </para>
 817         <para>
 818             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 819             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
 820             object such that the memory writes required would exceed the data store size.
 821         </para>
 822         <para>
 823             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 824             <constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 825             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 826         </para>
 827         <para>
 828             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glReadPixels</function>
 829             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 830             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 831         </para>
 832     </refsect1>
 833     <refsect1 id="associatedgets"><title>Associated Gets</title>
 834         <para>
 835             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_INDEX_MODE</constant>
 836         </para>
 837         <para>
 838             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
 839         </para>
 840     </refsect1>
 841     <refsect1 id="seealso"><title>See Also</title>
 842         <para>
 843             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 844             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 845             <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>,
 846             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 847             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 848             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>
 849         </para>
 850     </refsect1>
 851     <refsect1 id="Copyright"><title>Copyright</title>
 852         <para>
 853             Copyright <trademark class="copyright"></trademark> 1991-2006
 854             Silicon Graphics, Inc. This document is licensed under the SGI
 855             Free Software B License. For details, see
 856             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 857         </para>
 858     </refsect1>
 859 </refentry>