- read a block of pixels from the frame buffer



C SPECIFICATION


PARAMETERS

       _param1, _param2 Specify  the  window  coordinates  of the
                        first pixel that is read from  the  frame
                        buffer.   This location is the lower left
                        corner of a rectangular block of  pixels.

       _param3, _param4 Specify the dimensions of the pixel rect-
                        angle.  _param3 and _param4 of one corre-
                        spond to a single pixel.

       _param5          Specifies  the   of  the pixel data.  The
                        following symbolic values  are  accepted:
                        GL_COLOR_INDEX,         GL_STENCIL_INDEX,
                        GL_DEPTH_COMPONENT,   GL_RED,   GL_GREEN,
                        GL_BLUE,    GL_ALPHA,   GL_RGB,   GL_BGR,
                        GL_RGBA,   GL_BGRA,   GL_LUMINANCE,   and
                        GL_LUMINANCE_ALPHA.

       _param6          Specifies  the  data  type  of  the pixel
                        data.  Must be one  of  GL_UNSIGNED_BYTE,
                        GL_BYTE,   GL_BITMAP,  GL_UNSIGNED_SHORT,
                        GL_SHORT,    GL_UNSIGNED_INT,     GL_INT,
                        GL_FLOAT,         GL_UNSIGNED_BYTE_3_3_2,
                        GL_UNSIGNED_BYTE_2_3_3_REV,
                        GL_UNSIGNED_SHORT_5_6_5,
                        GL_UNSIGNED_SHORT_5_6_5_REV,
                        GL_UNSIGNED_SHORT_4_4_4_4,
                        GL_UNSIGNED_SHORT_4_4_4_4_REV,
                        GL_UNSIGNED_SHORT_5_5_5_1,
                        GL_UNSIGNED_SHORT_1_5_5_5_REV,
                        GL_UNSIGNED_INT_8_8_8_8,
                        GL_UNSIGNED_INT_8_8_8_8_REV,
                        GL_UNSIGNED_INT_10_10_10_2,            or
                        GL_UNSIGNED_INT_2_10_10_10_REV.

       _param7          Returns the pixel data.


DESCRIPTION

       glReadPixels returns pixel data  from  the  frame  buffer,
       starting  with  the  pixel  whose  lower left corner is at
       location (_param1, _param2), into client  memory  starting
       at  location _param7.  Several parameters control the pro-
       cessing of the pixel data before it is placed into  client
       memory.   These  parameters  are  set with three commands:
       glPixelStore, glPixelTransfer, and glPixelMap.  This  ref-
       erence page describes the effects on glReadPixels of most,
       but not all of the parameters  specified  by  these  three
       commands.
       _param5 specifies the   for  the  returned  pixel  values;
       accepted values are:

       GL_COLOR_INDEX
                 Color  indices  are  read  from the color buffer
                 selected by glReadBuffer.  Each  index  is  con-
                 verted  to  fixed  point,  shifted left or right
                 depending   on   the   value   and    sign    of
                 GL_INDEX_SHIFT,  and  added  to GL_INDEX_OFFSET.
                 If GL_MAP_COLOR is GL_TRUE, indices are replaced
                 by     their     mappings     in    the    table
                 GL_PIXEL_MAP_I_TO_I.

       GL_STENCIL_INDEX
                 Stencil values are read from the stencil buffer.
                 Each  index is converted to fixed point, shifted
                 left or right depending on the value and sign of
                 GL_INDEX_SHIFT,  and  added  to GL_INDEX_OFFSET.
                 If  GL_MAP_STENCIL  is  GL_TRUE,   indices   are
                 replaced   by   their   mappings  in  the  table
                 GL_PIXEL_MAP_S_TO_S.

       GL_DEPTH_COMPONENT
                 Depth values are read  from  the  depth  buffer.
                 Each  component  is  converted to floating point
                 such that the minimum depth value maps to 0  and
                 the  maximum value maps to 1.  Each component is
                 then  multiplied  by  GL_DEPTH_SCALE,  added  to
                 GL_DEPTH_BIAS,  and finally clamped to the range
                 [0,1].

       GL_RED

       GL_GREEN

       GL_BLUE

       GL_ALPHA

       GL_RGB

       GL_BGR

       GL_RGBA

       GL_BGRA

       GL_LUMINANCE

       GL_LUMINANCE_ALPHA
                 Processing differs depending  on  whether  color
                 buffers store color indices or RGBA color compo-

                 If RGBA color components are stored in the color
                 buffers, they are read  from  the  color  buffer
                 selected  by glReadBuffer.  Each color component
                 is converted to floating point  such  that  zero
                 intensity maps to 0.0 and full intensity maps to
                 1.0.   Each  component  is  then  multiplied  by
                 GL_c_SCALE  and  added  to GL_c_BIAS, where c is
                 RED,  GREEN,  BLUE,  or  ALPHA.    Finally,   if
                 GL_MAP_COLOR   is  GL_TRUE,  each  component  is
                 clamped to the range [0, 1], scaled to the  size
                 of its corresponding table, and is then replaced
                 by its mapping in the table GL_PIXEL_MAP_c_TO_c,
                 where c is R, G, B, or A.

                 Unneeded  data  is then discarded.  For example,
                 GL_RED discards the green, blue, and alpha  com-
                 ponents,  while  GL_RGB  discards only the alpha
                 component.  GL_LUMINANCE computes a  single-com-
                 ponent  value  as the sum of the red, green, and
                 blue components, and GL_LUMINANCE_ALPHA does the
                 same,  while  keeping  alpha  as a second value.
                 The  final  values  are  clamped  to  the  range
                 [0, 1].

       The  shift, scale, bias, and lookup factors just described
       are all specified by
       glPixelTransfer.  The lookup table contents themselves are
       specified by glPixelMap.

       Finally,  the  indices  or components are converted to the
       proper  ,  as  specified  by  _param6.   If   _param5   is
       GL_COLOR_INDEX  or  GL_STENCIL_INDEX  and  _param6  is not
       GL_FLOAT, each index is masked with the mask  value  given
       in the following table.  If _param6 is GL_FLOAT, then each
       integer index is converted to  single-precision  floating-
       point .

       If _param5 is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
       GL_BGR,     GL_RGBA,     GL_BGRA,     GL_LUMINANCE,     or
       GL_LUMINANCE_ALPHA  and _param6 is not GL_FLOAT, each com-
       ponent is multiplied by the multiplier shown in  the  fol-
       lowing table.  If type is GL_FLOAT, then each component is
       passed as is (or converted to the  client's  single-preci-
       sion  floating-point  if it is different from the one used
       by the GL).

         ------------------------------------------------------
         _param6             index mask   component conversion
         ------------------------------------------------------
         GL_UNSIGNED_BYTE      2^8-1            (2^8-1)c
         GL_BYTE               2^7-1         [(2^8-1)c-1]/2

       the jth row is placed in location (j)_eqnparam3+i.  GL_RGB
       and GL_BGR return three values, GL_RGBA and GL_BGRA return
       four values, and GL_LUMINANCE_ALPHA returns two values for
       each  pixel,  with  all  values  corresponding to a single
       pixel occupying  contiguous  space  in  _param7.   Storage
       parameters  set by glPixelStore, such as GL_PACK_LSB_FIRST
       and GL_PACK_SWAP_BYTES, affect the way that data is  writ-
       ten into memory.  See glPixelStore for a description.


NOTES

       Values for pixels that lie outside the window connected to
       the current GL context are undefined.

       If an error is generated, no change is made  to  the  con-
       tents of _param7.


ERRORS

       GL_INVALID_ENUM  is generated if _param5 or _param6 is not
       an accepted value.

       GL_INVALID_ENUM is generated if _param6 is  GL_BITMAP  and
       _param5 is not GL_COLOR_INDEX or GL_STENCIL_INDEX.

       GL_INVALID_VALUE is generated if either _param3 or _param4
       is negative.

       GL_INVALID_OPERATION   is   generated   if   _param5    is
       GL_COLOR_INDEX and the color buffers store RGBA color com-
       ponents.

       GL_INVALID_OPERATION   is   generated   if   _param5    is
       GL_STENCIL_INDEX and there is no stencil buffer.

       GL_INVALID_OPERATION    is   generated   if   _param5   is
       GL_DEPTH_COMPONENT and there is no depth buffer.

       GL_INVALID_OPERATION is generated if glReadPixels is  exe-
       cuted between the execution of glBegin and the correspond-
       ing execution of glEnd.

       GL_INVALID_OPERATION is generated if  _param6  is  one  of
       GL_UNSIGNED_BYTE_3_3_2,        GL_UNSIGNED_BYTE_2_3_3_REV,
       GL_UNSIGNED_SHORT_5_6_5,  or   GL_UNSIGNED_SHORT_5_6_5_REV
       and _param5 is not GL_RGB.

       GL_INVALID_OPERATION  is  generated  if  _param6 is one of
       GL_UNSIGNED_SHORT_4_4_4_4,  GL_UNSIGNED_SHORT_4_4_4_4_REV,
       GL_UNSIGNED_SHORT_5_5_5_1,  GL_UNSIGNED_SHORT_1_5_5_5_REV,
       GL_UNSIGNED_INT_8_8_8_8,      GL_UNSIGNED_INT_8_8_8_8_REV,
       GL_UNSIGNED_INT_10_10_10_2,                             or
       GL_UNSIGNED_INT_2_10_10_10_REV  and  _param5  is   neither
       GL_RGBA nor GL_BGRA.


SEE ALSO

       glCopyPixels,   glDrawPixels,   glPixelMap,  glPixelStore,
       glPixelTransfer,
       glReadBuffer



                                                                1