upstream-man-pages/man2/glCopyPixels.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="glCopyPixels">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCopyPixels</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCopyPixels</refname>
  17         <refpurpose>copy pixels in the frame buffer</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCopyPixels</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>type</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <!-- eqn: ignoring delim $$ -->
  32     <refsect1 id="parameters"><title>Parameters</title>
  33         <variablelist>
  34         <varlistentry>
  35             <term><parameter>x</parameter></term>
  36             <term><parameter>y</parameter></term>
  37             <listitem>
  38                 <para>
  39                     Specify the window coordinates of the lower left corner
  40                     of the rectangular region of pixels to be copied.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>width</parameter></term>
  46             <term><parameter>height</parameter></term>
  47             <listitem>
  48                 <para>
  49                     Specify the dimensions of the rectangular region of pixels to be copied.
  50                     Both must be nonnegative.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         <varlistentry>
  55             <term><parameter>type</parameter></term>
  56             <listitem>
  57                 <para>
  58                     Specifies whether color values,
  59                     depth values,
  60                     or stencil values are to be copied.
  61                     Symbolic constants
  62                     <constant>GL_COLOR</constant>,
  63                     <constant>GL_DEPTH</constant>,
  64                     and <constant>GL_STENCIL</constant> are accepted.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         </variablelist>
  69     </refsect1>
  70     <refsect1 id="description"><title>Description</title>
  71         <para>
  72             <function>glCopyPixels</function> copies a screen-aligned rectangle of pixels
  73             from the specified frame buffer location to a region relative to the
  74             current raster position.
  75             Its operation is well defined only if the entire pixel source region
  76             is within the exposed portion of the window.
  77             Results of copies from outside the window,
  78             or from regions of the window that are not exposed,
  79             are hardware dependent and undefined.
  80         </para>
  81         <para>
  82             <parameter>x</parameter> and <parameter>y</parameter> specify the window coordinates of
  83             the lower left corner of the rectangular region to be copied.
  84             <parameter>width</parameter> and <parameter>height</parameter> specify the dimensions of the
  85             rectangular region to be copied.
  86             Both <parameter>width</parameter> and <parameter>height</parameter> must not be negative.
  87         </para>
  88         <para>
  89             Several parameters control the processing of the pixel data
  90             while it is being copied.
  91             These parameters are set with three commands:
  92             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
  93             <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>, and
  94             <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>.
  95             This reference page describes the effects on <function>glCopyPixels</function> of most,
  96             but not all, of the parameters specified by these three commands.
  97         </para>
  98         <para>
  99             <function>glCopyPixels</function> copies values from each pixel with the lower left-hand corner at
 100             <inlineequation><mml:math>
 101                 <!-- eqn: (x + i, y + j):-->
 102                 <mml:mfenced open="(" close=")">
 103                     <mml:mrow>
 104                         <mml:mi mathvariant="italic">x</mml:mi>
 105                         <mml:mo>+</mml:mo>
 106                         <mml:mi mathvariant="italic">i</mml:mi>
 107                     </mml:mrow>
 108                     <mml:mrow>
 109                         <mml:mi mathvariant="italic">y</mml:mi>
 110                         <mml:mo>+</mml:mo>
 111                         <mml:mi mathvariant="italic">j</mml:mi>
 112                     </mml:mrow>
 113                 </mml:mfenced>
 114             </mml:math></inlineequation>
 115             for
 116             <inlineequation><mml:math>
 117                 <!-- eqn: 0 <= i < width:-->
 118                 <mml:mrow>
 119                     <mml:mn>0</mml:mn>
 120                     <mml:mo>&lt;=</mml:mo>
 121                     <mml:mi mathvariant="italic">i</mml:mi>
 122                     <mml:mo>&lt;</mml:mo>
 123                     <mml:mi mathvariant="italic">width</mml:mi>
 124                 </mml:mrow>
 125             </mml:math></inlineequation>
 126             and
 127             <inlineequation><mml:math>
 128                 <!-- eqn: 0 <= j < height:-->
 129                 <mml:mrow>
 130                     <mml:mn>0</mml:mn>
 131                     <mml:mo>&lt;=</mml:mo>
 132                     <mml:mi mathvariant="italic">j</mml:mi>
 133                     <mml:mo>&lt;</mml:mo>
 134                     <mml:mi mathvariant="italic">height</mml:mi>
 135                 </mml:mrow>
 136             </mml:math></inlineequation>.
 137             This pixel is said to be the
 138             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 139             pixel in the
 140             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 141             row.
 142             Pixels are copied in row order from the lowest to the highest row,
 143             left to right in each row.
 144         </para>
 145         <para>
 146             <parameter>type</parameter> specifies whether color, depth, or stencil data is to be copied.
 147             The details of the transfer for each data type are as follows:
 148         </para>
 149         <variablelist>
 150             <varlistentry>
 151                 <term><constant>GL_COLOR</constant></term>
 152                 <listitem>
 153                     <para>
 154                         Indices or RGBA colors are read from the buffer currently specified as the
 155                         read source buffer (see <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>).
 156                         If the GL is in color index mode,
 157                         each index that is read from this buffer is converted
 158                         to a fixed-point format with an unspecified
 159                         number of bits to the right of the binary point.
 160                         Each index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits,
 161                         and added to <constant>GL_INDEX_OFFSET</constant>.
 162                         If <constant>GL_INDEX_SHIFT</constant> is negative,
 163                         the shift is to the right.
 164                         In either case, zero bits fill otherwise unspecified bit locations in the
 165                         result.
 166                         If <constant>GL_MAP_COLOR</constant> is true,
 167                         the index is replaced with the value that it references in lookup table
 168                         <constant>GL_PIXEL_MAP_I_TO_I</constant>.
 169                         Whether the lookup replacement of the index is done or not,
 170                         the integer part of the index is then ANDed with
 171                         <inlineequation><mml:math>
 172                             <!-- eqn: 2 sup b -1:-->
 173                             <mml:mrow>
 174                                 <mml:msup><mml:mn>2</mml:mn>
 175                                 <mml:mi mathvariant="italic">b</mml:mi>
 176                                 </mml:msup>
 177                                 <mml:mo>-</mml:mo>
 178                                 <mml:mn>1</mml:mn>
 179                             </mml:mrow>
 180                         </mml:math></inlineequation>,
 181                         where
 182                         <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 183                         is the number of bits in a color index buffer.
 184                     </para>
 185                     <para>
 186                         If the GL is in RGBA mode,
 187                         the red, green, blue, and alpha components of each pixel that is read
 188                         are converted to an internal floating-point format with unspecified
 189                         precision.
 190                         The conversion maps the largest representable component value to 1.0,
 191                         and component value 0 to 0.0.
 192                         The resulting floating-point color values are then multiplied
 193                         by <constant>GL_c_SCALE</constant> and added to <constant>GL_c_BIAS</constant>,
 194                         where <emphasis>c</emphasis> is RED, GREEN, BLUE, and ALPHA
 195                         for the respective color components.
 196                         The results are clamped to the range [0,1].
 197                         If <constant>GL_MAP_COLOR</constant> is true,
 198                         each color component is scaled by the size of lookup table
 199                         <constant>GL_PIXEL_MAP_c_TO_c</constant>,
 200                         then replaced by the value that it references in that table.
 201                         <emphasis>c</emphasis> is R, G, B, or A.
 202                     </para>
 203                     <para>
 204                         If the <code>ARB_imaging</code> extension is supported, the color values may
 205                         be
 206                         additionally processed by color-table lookups, color-matrix
 207                         transformations, and convolution filters.
 208                     </para>
 209                     <para>
 210                         The GL then converts the resulting indices or RGBA colors to fragments
 211                         by attaching the current raster position <emphasis>z</emphasis> coordinate and
 212                         texture coordinates to each pixel,
 213                         then assigning window coordinates
 214                         <inlineequation><mml:math>
 215                             <!-- eqn: (x sub r  +  i , y sub r  +  j):-->
 216                             <mml:mfenced open="(" close=")">
 217                                 <mml:mrow>
 218                                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 219                                     <mml:mi mathvariant="italic">r</mml:mi>
 220                                     </mml:msub>
 221                                     <mml:mo>+</mml:mo>
 222                                     <mml:mi mathvariant="italic">i</mml:mi>
 223                                 </mml:mrow>
 224                                 <mml:mrow>
 225                                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 226                                     <mml:mi mathvariant="italic">r</mml:mi>
 227                                     </mml:msub>
 228                                     <mml:mo>+</mml:mo>
 229                                     <mml:mi mathvariant="italic">j</mml:mi>
 230                                 </mml:mrow>
 231                             </mml:mfenced>
 232                         </mml:math></inlineequation>,
 233                         where
 234                         <inlineequation><mml:math>
 235                             <!-- eqn: (x sub r , y sub r):-->
 236                             <mml:mfenced open="(" close=")">
 237                                 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 238                                 <mml:mi mathvariant="italic">r</mml:mi>
 239                                 </mml:msub>
 240                                 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 241                                 <mml:mi mathvariant="italic">r</mml:mi>
 242                                 </mml:msub>
 243                             </mml:mfenced>
 244                         </mml:math></inlineequation>
 245                         is the current raster position,
 246                         and the pixel was the
 247                         <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 248                         pixel in the
 249                         <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 250                         row.
 251                         These pixel fragments are then treated just like the fragments generated by
 252                         rasterizing points, lines, or polygons.
 253                         Texture mapping,
 254                         fog,
 255                         and all the fragment operations are applied before the fragments are written
 256                         to the frame buffer.
 257                     </para>
 258                 </listitem>
 259             </varlistentry>
 260             <varlistentry>
 261                 <term><constant>GL_DEPTH</constant></term>
 262                 <listitem>
 263                     <para>
 264                         Depth values are read from the depth buffer and
 265                         converted directly to an internal floating-point format
 266                         with unspecified precision.
 267                         The resulting floating-point depth value is then multiplied
 268                         by <constant>GL_DEPTH_SCALE</constant> and added to <constant>GL_DEPTH_BIAS</constant>.
 269                         The result is clamped to the range [0,1].
 270                     </para>
 271                     <para>
 272                         The GL then converts the resulting depth components to fragments
 273                         by attaching the current raster position color or color index and
 274                         texture coordinates to each pixel,
 275                         then assigning window coordinates
 276                         <inlineequation><mml:math>
 277                             <!-- eqn: (x sub r  +  i , y sub r  +  j):-->
 278                             <mml:mfenced open="(" close=")">
 279                                 <mml:mrow>
 280                                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 281                                     <mml:mi mathvariant="italic">r</mml:mi>
 282                                     </mml:msub>
 283                                     <mml:mo>+</mml:mo>
 284                                     <mml:mi mathvariant="italic">i</mml:mi>
 285                                 </mml:mrow>
 286                                 <mml:mrow>
 287                                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 288                                     <mml:mi mathvariant="italic">r</mml:mi>
 289                                     </mml:msub>
 290                                     <mml:mo>+</mml:mo>
 291                                     <mml:mi mathvariant="italic">j</mml:mi>
 292                                 </mml:mrow>
 293                             </mml:mfenced>
 294                         </mml:math></inlineequation>,
 295                         where
 296                         <inlineequation><mml:math>
 297                             <!-- eqn: (x sub r , y sub r):-->
 298                             <mml:mfenced open="(" close=")">
 299                                 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 300                                 <mml:mi mathvariant="italic">r</mml:mi>
 301                                 </mml:msub>
 302                                 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 303                                 <mml:mi mathvariant="italic">r</mml:mi>
 304                                 </mml:msub>
 305                             </mml:mfenced>
 306                         </mml:math></inlineequation>
 307                         is the current raster position,
 308                         and the pixel was the
 309                         <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 310                         pixel in the
 311                         <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 312                         row.
 313                         These pixel fragments are then treated just like the fragments generated by
 314                         rasterizing points, lines, or polygons.
 315                         Texture mapping,
 316                         fog,
 317                         and all the fragment operations are applied before the fragments are written
 318                         to the frame buffer.
 319                     </para>
 320                 </listitem>
 321             </varlistentry>
 322             <varlistentry>
 323                 <term><constant>GL_STENCIL</constant></term>
 324                 <listitem>
 325                     <para>
 326                         Stencil indices are read from the stencil buffer and
 327                         converted to an internal fixed-point format
 328                         with an unspecified number of bits to the right of the binary point.
 329                         Each fixed-point index is then shifted left by <constant>GL_INDEX_SHIFT</constant> bits,
 330                         and added to <constant>GL_INDEX_OFFSET</constant>.
 331                         If <constant>GL_INDEX_SHIFT</constant> is negative,
 332                         the shift is to the right.
 333                         In either case, zero bits fill otherwise unspecified bit locations in the
 334                         result.
 335                         If <constant>GL_MAP_STENCIL</constant> is true,
 336                         the index is replaced with the value that it references in lookup table
 337                         <constant>GL_PIXEL_MAP_S_TO_S</constant>.
 338                         Whether the lookup replacement of the index is done or not,
 339                         the integer part of the index is then ANDed with
 340                         <inlineequation><mml:math>
 341                             <!-- eqn: 2 sup b -1:-->
 342                             <mml:mrow>
 343                                 <mml:msup><mml:mn>2</mml:mn>
 344                                 <mml:mi mathvariant="italic">b</mml:mi>
 345                                 </mml:msup>
 346                                 <mml:mo>-</mml:mo>
 347                                 <mml:mn>1</mml:mn>
 348                             </mml:mrow>
 349                         </mml:math></inlineequation>,
 350                         where
 351                         <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 352                         is the number of bits in the stencil buffer.
 353                         The resulting stencil indices are then written to the stencil buffer
 354                         such that the index read from the
 355                         <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 356                         location of the
 357                         <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 358                         row
 359                         is written to location
 360                         <inlineequation><mml:math>
 361                             <!-- eqn: (x sub r  +  i , y sub r  +  j):-->
 362                             <mml:mfenced open="(" close=")">
 363                                 <mml:mrow>
 364                                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 365                                     <mml:mi mathvariant="italic">r</mml:mi>
 366                                     </mml:msub>
 367                                     <mml:mo>+</mml:mo>
 368                                     <mml:mi mathvariant="italic">i</mml:mi>
 369                                 </mml:mrow>
 370                                 <mml:mrow>
 371                                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 372                                     <mml:mi mathvariant="italic">r</mml:mi>
 373                                     </mml:msub>
 374                                     <mml:mo>+</mml:mo>
 375                                     <mml:mi mathvariant="italic">j</mml:mi>
 376                                 </mml:mrow>
 377                             </mml:mfenced>
 378                         </mml:math></inlineequation>,
 379                         where
 380                         <inlineequation><mml:math>
 381                             <!-- eqn: (x sub r , y sub r):-->
 382                             <mml:mfenced open="(" close=")">
 383                                 <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 384                                 <mml:mi mathvariant="italic">r</mml:mi>
 385                                 </mml:msub>
 386                                 <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 387                                 <mml:mi mathvariant="italic">r</mml:mi>
 388                                 </mml:msub>
 389                             </mml:mfenced>
 390                         </mml:math></inlineequation>
 391                         is the current raster position.
 392                         Only the pixel ownership test,
 393                         the scissor test,
 394                         and the stencil writemask affect these write operations.
 395                     </para>
 396                 </listitem>
 397             </varlistentry>
 398         </variablelist>
 399         <para>
 400             The rasterization described thus far assumes pixel zoom factors of 1.0.
 401             If
 402             <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry> is used to change the
 403             <inlineequation><mml:math><mml:mi mathvariant="italic">x</mml:mi></mml:math></inlineequation>
 404             and
 405             <inlineequation><mml:math><mml:mi mathvariant="italic">y</mml:mi></mml:math></inlineequation>
 406             pixel zoom factors,
 407             pixels are converted to fragments as follows.
 408             If
 409             <inlineequation><mml:math>
 410                 <!-- eqn: (x sub r, y sub r):-->
 411                 <mml:mfenced open="(" close=")">
 412                     <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 413                     <mml:mi mathvariant="italic">r</mml:mi>
 414                     </mml:msub>
 415                     <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 416                     <mml:mi mathvariant="italic">r</mml:mi>
 417                     </mml:msub>
 418                 </mml:mfenced>
 419             </mml:math></inlineequation>
 420             is the current raster position,
 421             and a given pixel is in the
 422             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>th
 423             location in the
 424             <inlineequation><mml:math><mml:mi mathvariant="italic">j</mml:mi></mml:math></inlineequation>th
 425             row of the source
 426             pixel rectangle,
 427             then fragments are generated for pixels whose centers are in the rectangle
 428             with corners at
 429         </para>
 430         <para>
 431             <inlineequation><mml:math>
 432                 <!-- eqn: (x sub r  +  {zoom sub x} i, y sub r  +  {zoom sub y} j):-->
 433                 <mml:mfenced open="(" close=")">
 434                     <mml:mrow>
 435                         <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 436                         <mml:mi mathvariant="italic">r</mml:mi>
 437                         </mml:msub>
 438                         <mml:mo>+</mml:mo>
 439                         <mml:mfenced open="" close="">
 440                             <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 441                             <mml:mi mathvariant="italic">x</mml:mi>
 442                             </mml:msub>
 443                         </mml:mfenced>
 444                         <mml:mo>&it;</mml:mo>
 445                         <mml:mi mathvariant="italic">i</mml:mi>
 446                     </mml:mrow>
 447                     <mml:mrow>
 448                         <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 449                         <mml:mi mathvariant="italic">r</mml:mi>
 450                         </mml:msub>
 451                         <mml:mo>+</mml:mo>
 452                         <mml:mfenced open="" close="">
 453                             <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 454                             <mml:mi mathvariant="italic">y</mml:mi>
 455                             </mml:msub>
 456                         </mml:mfenced>
 457                         <mml:mo>&it;</mml:mo>
 458                         <mml:mi mathvariant="italic">j</mml:mi>
 459                     </mml:mrow>
 460                 </mml:mfenced>
 461             </mml:math></inlineequation>
 462         </para>
 463         <para>
 464              and
 465         </para>
 466         <para>
 467             <inlineequation><mml:math>
 468                 <!-- eqn: (x sub r  +  {zoom sub x} (i  +  1), y sub r  +  {zoom sub y} ( j  +  1 )):-->
 469                 <mml:mfenced open="(" close=")">
 470                     <mml:mrow>
 471                         <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
 472                         <mml:mi mathvariant="italic">r</mml:mi>
 473                         </mml:msub>
 474                         <mml:mo>+</mml:mo>
 475                         <mml:mrow>
 476                             <mml:mfenced open="" close="">
 477                                 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 478                                 <mml:mi mathvariant="italic">x</mml:mi>
 479                                 </mml:msub>
 480                             </mml:mfenced>
 481                             <mml:mo>&af;</mml:mo>
 482                             <mml:mfenced open="(" close=")">
 483                                 <mml:mrow>
 484                                     <mml:mi mathvariant="italic">i</mml:mi>
 485                                     <mml:mo>+</mml:mo>
 486                                     <mml:mn>1</mml:mn>
 487                                 </mml:mrow>
 488                             </mml:mfenced>
 489                         </mml:mrow>
 490                     </mml:mrow>
 491                     <mml:mrow>
 492                         <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
 493                         <mml:mi mathvariant="italic">r</mml:mi>
 494                         </mml:msub>
 495                         <mml:mo>+</mml:mo>
 496                         <mml:mrow>
 497                             <mml:mfenced open="" close="">
 498                                 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 499                                 <mml:mi mathvariant="italic">y</mml:mi>
 500                                 </mml:msub>
 501                             </mml:mfenced>
 502                             <mml:mo>&af;</mml:mo>
 503                             <mml:mfenced open="(" close=")">
 504                                 <mml:mrow>
 505                                     <mml:mi mathvariant="italic">j</mml:mi>
 506                                     <mml:mo>+</mml:mo>
 507                                     <mml:mn>1</mml:mn>
 508                                 </mml:mrow>
 509                             </mml:mfenced>
 510                         </mml:mrow>
 511                     </mml:mrow>
 512                 </mml:mfenced>
 513             </mml:math></inlineequation>
 514         </para>
 515         <para>
 516             where
 517             <inlineequation><mml:math>
 518                 <!-- eqn: zoom sub x:-->
 519                 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 520                 <mml:mi mathvariant="italic">x</mml:mi>
 521                 </mml:msub>
 522             </mml:math></inlineequation>
 523             is the value of <constant>GL_ZOOM_X</constant> and
 524             <inlineequation><mml:math>
 525                 <!-- eqn: zoom sub y:-->
 526                 <mml:msub><mml:mi mathvariant="italic">zoom</mml:mi>
 527                 <mml:mi mathvariant="italic">y</mml:mi>
 528                 </mml:msub>
 529             </mml:math></inlineequation>
 530             is the value of <constant>GL_ZOOM_Y</constant>.
 531         </para>
 532     </refsect1>
 533     <refsect1 id="examples"><title>Examples</title>
 534         <para>
 535             To copy the color pixel in the lower left corner of the window to the current raster position,
 536             use
 537         </para>
 538         <para>
 539             <programlisting>
 540 glCopyPixels(0, 0, 1, 1, <constant>GL_COLOR</constant>);
 541             </programlisting>
 542         </para>
 543         <para>
 544         </para>
 545     </refsect1>
 546     <refsect1 id="notes"><title>Notes</title>
 547         <para>
 548             Modes specified by <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> have no effect on the operation
 549             of <function>glCopyPixels</function>.
 550         </para>
 551     </refsect1>
 552     <refsect1 id="errors"><title>Errors</title>
 553         <para>
 554             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not an accepted value.
 555         </para>
 556         <para>
 557             <constant>GL_INVALID_VALUE</constant> is generated if either <parameter>width</parameter> or <parameter>height</parameter> is negative.
 558         </para>
 559         <para>
 560             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is <constant>GL_DEPTH</constant>
 561             and there is no depth buffer.
 562         </para>
 563         <para>
 564             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is <constant>GL_STENCIL</constant>
 565             and there is no stencil buffer.
 566         </para>
 567         <para>
 568             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyPixels</function>
 569             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 570             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 571         </para>
 572     </refsect1>
 573     <refsect1 id="associatedgets"><title>Associated Gets</title>
 574         <para>
 575             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION</constant>
 576         </para>
 577         <para>
 578             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_RASTER_POSITION_VALID</constant>
 579         </para>
 580     </refsect1>
 581     <refsect1 id="seealso"><title>See Also</title>
 582         <para>
 583             <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
 584             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
 585             <citerefentry><refentrytitle>glConvolutionFilter2D</refentrytitle></citerefentry>,
 586             <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
 587             <citerefentry><refentrytitle>glDrawBuffer</refentrytitle></citerefentry>,
 588             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 589             <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
 590             <citerefentry><refentrytitle>glPixelMap</refentrytitle></citerefentry>,
 591             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 592             <citerefentry><refentrytitle>glPixelZoom</refentrytitle></citerefentry>,
 593             <citerefentry><refentrytitle>glRasterPos</refentrytitle></citerefentry>,
 594             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 595             <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
 596             <citerefentry><refentrytitle>glSeparableFilter2D</refentrytitle></citerefentry>,
 597             <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>,
 598             <citerefentry><refentrytitle>glWindowPos</refentrytitle></citerefentry>
 599         </para>
 600     </refsect1>
 601     <refsect1 id="Copyright"><title>Copyright</title>
 602         <para>
 603             Copyright <trademark class="copyright"></trademark> 1991-2006
 604             Silicon Graphics, Inc. This document is licensed under the SGI
 605             Free Software B License. For details, see
 606             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 607         </para>
 608     </refsect1>
 609 </refentry>