- copy pixels in the frame buffer



C SPECIFICATION


PARAMETERS

       _param1, _param2 Specify  the  window  coordinates  of the
                        lower  left  corner  of  the  rectangular
                        region of pixels to be copied.

       _param3, _param4 Specify the dimensions of the rectangular
                        region of pixels to be copied.  Both must
                        be nonnegative.

       _param5          Specifies  whether  color  values,  depth
                        values,  or  stencil  values  are  to  be
                        copied.    Symbolic  constants  GL_COLOR,
                        GL_DEPTH, and GL_STENCIL are accepted.


DESCRIPTION

       glCopyPixels copies a screen-aligned rectangle  of  pixels
       from the specified frame buffer location to a region rela-
       tive to the current raster  position.   Its  operation  is
       well  defined  only  if  the entire pixel source region is
       within the exposed portion  of  the  window.   Results  of
       copies  from  outside  the  window, or from regions of the
       window that are not exposed, are  hardware  dependent  and
       undefined.

       _param1  and _param2 specify the window coordinates of the
       lower left corner of the rectangular region to be  copied.
       _param3  and _param4 specify the dimensions of the rectan-
       gular region to be copied.  Both _param3 and _param4  must
       not be negative.

       Several  parameters  control  the  processing of the pixel
       data while it is being copied.  These parameters  are  set
       with  three  commands:  glPixelTransfer,  glPixelMap,  and
       glPixelZoom.  This reference page describes the effects on
       glCopyPixels of most, but not all, of the parameters spec-
       ified by these three commands.

       glCopyPixels copies values from each pixel with the  lower
       left-hand  corner at (_param1 + i, _param2 + j) for 0 <= i
       < _param3 and 0 <= j < _param4.  This pixel is said to  be
       the  ith  pixel  in the jth row.  Pixels are copied in row
       order from the lowest to the highest row, left to right in
       each row.

       _param5 specifies whether color, depth, or stencil data is
       to be copied.  The details of the transfer for  each  data
       type are as follows:

                      replaced  with the value that it references
                      in   lookup   table    GL_PIXEL_MAP_I_TO_I.
                      Whether the lookup replacement of the index
                      is done or not, the  integer  part  of  the
                      index  is  then ANDed with 2b-1, where b is
                      the number of bits in a color index buffer.

                      If  the GL is in RGBA mode, the red, green,
                      blue, and alpha components  of  each  pixel
                      that  is  read are converted to an internal
                      floating-point  with unspecified precision.
                      The  conversion  maps  the  largest  repre-
                      sentable component value to 1.0, and compo-
                      nent  value 0 to 0.0.  The resulting float-
                      ing-point color values are then  multiplied
                      by GL_c_SCALE and added to GL_c_BIAS, where
                      c is RED, GREEN, BLUE, and  ALPHA  for  the
                      respective  color  components.  The results
                      are  clamped  to  the  range   [0,1].    If
                      GL_MAP_COLOR  is true, each color component
                      is scaled  by  the  size  of  lookup  table
                      GL_PIXEL_MAP_c_TO_c,  then  replaced by the
                      value that it references in that table.   c
                      is R, G, B, or A.

                      If  the  GL_ARB_imaging  extension  is sup-
                      ported, the color values may  be  addition-
                      ally   processed  by  color-table  lookups,
                      color-matrix transformations, and  convolu-
                      tion filters.

                      The  GL then converts the resulting indices
                      or RGBA colors to  fragments  by  attaching
                      the  current  raster  position z coordinate
                      and texture coordinates to each pixel, then
                      assigning  window  coordinates (xr+i,yr+j),
                      where (xr,yr) is the current  raster  posi-
                      tion,  and  the  pixel was the ith pixel in
                      the jth row.   These  pixel  fragments  are
                      then treated just like the fragments gener-
                      ated by rasterizing points, lines, or poly-
                      gons.   Texture  mapping,  fog, and all the
                      fragment operations are applied before  the
                      fragments  are written to the frame buffer.

       GL_DEPTH       Depth values are read from the depth buffer
                      and   converted  directly  to  an  internal
                      floating-point with unspecified  precision.
                      The resulting floating-point depth value is
                      then multiplied by GL_DEPTH_SCALE and added
                      to GL_DEPTH_BIAS.  The result is clamped to
                      the range [0,1].
                      frame buffer.

       GL_STENCIL     Stencil  indices  are read from the stencil
                      buffer and converted to an internal  fixed-
                      point with an unspecified number of bits to
                      the right of the binary point.  Each fixed-
                      point   index   is  then  shifted  left  by
                      GL_INDEX_SHIFT   bits,   and    added    to
                      GL_INDEX_OFFSET.  If GL_INDEX_SHIFT is neg-
                      ative, the  shift  is  to  the  right.   In
                      either   case,  zero  bits  fill  otherwise
                      unspecified bit locations  in  the  result.
                      If  GL_MAP_STENCIL  is  true,  the index is
                      replaced with the value that it  references
                      in    lookup   table   GL_PIXEL_MAP_S_TO_S.
                      Whether the lookup replacement of the index
                      is  done  or  not,  the integer part of the
                      index is then ANDed with 2b-1, where  b  is
                      the  number  of bits in the stencil buffer.
                      The  resulting  stencil  indices  are  then
                      written to the stencil buffer such that the
                      index read from the ith location of the jth
                      row  is  written  to  location (xr+i,yr+j),
                      where (xr,yr) is the current  raster  posi-
                      tion.   Only  the pixel ownership test, the
                      scissor test,  and  the  stencil  writemask
                      affect these write operations.

       The  rasterization  described  thus far assumes pixel zoom
       factors of 1.0.  If
       glPixelZoom is used to change the x and y pixel zoom  fac-
       tors,  pixels  are  converted to fragments as follows.  If
       (xr, yr) is the current raster position, and a given pixel
       is  in the ith location in the jth row of the source pixel
       rectangle, then fragments are generated for  pixels  whose
       centers are in the rectangle with corners at

                         (xr+zoomxi, yr+zoomyj)
                                   and
                     (xr+zoomx(i+1), yr+zoomy(j+1))

       where  zoomx  is  the  value of GL_ZOOM_X and zoomy is the
       value of GL_ZOOM_Y.


EXAMPLES

       To copy the color pixel in the lower left  corner  of  the
       window to the current raster position, use glCopyPixels(0,
       0, 1, 1, GL_COLOR);


NOTES

       Modes specified by glPixelStore  have  no  effect  on  the
       operation of glCopyPixels.
       GL_INVALID_OPERATION  is generated if glCopyPixels is exe-
       cuted between the execution of glBegin and the correspond-
       ing execution of glEnd.


ASSOCIATED GETS

       glGet with argument GL_CURRENT_RASTER_POSITION
       glGet with argument GL_CURRENT_RASTER_POSITION_VALID


SEE ALSO

       glColorTable,                       glConvolutionFilter1D,
       glConvolutionFilter2D,     glDepthFunc,      glDrawBuffer,
       glDrawPixels,  glMatrixMode,  glPixelMap, glPixelTransfer,
       glPixelZoom,  glRasterPos,   glReadBuffer,   glReadPixels,
       glSeparableFilter2D, glStencilFunc



                                                                1