- set pixel transfer modes



C SPECIFICATION


PARAMETERS

       _param1  Specifies the symbolic name of the pixel transfer
                parameter to be set.  Must be one of the  follow-
                ing:         GL_MAP_COLOR,        GL_MAP_STENCIL,
                GL_INDEX_SHIFT,  GL_INDEX_OFFSET,   GL_RED_SCALE,
                GL_RED_BIAS,    GL_GREEN_SCALE,    GL_GREEN_BIAS,
                GL_BLUE_SCALE,   GL_BLUE_BIAS,    GL_ALPHA_SCALE,
                GL_ALPHA_BIAS,  GL_DEPTH_SCALE, or GL_DEPTH_BIAS.

                Additionally, if the GL_ARB_imaging extension  is
                supported,   the  following  symbolic  names  are
                accepted:         GL_POST_COLOR_MATRIX_RED_SCALE,
                GL_POST_COLOR_MATRIX_GREEN_SCALE,
                GL_POST_COLOR_MATRIX_BLUE_SCALE,
                GL_POST_COLOR_MATRIX_ALPHA_SCALE,
                GL_POST_COLOR_MATRIX_RED_BIAS,
                GL_POST_COLOR_MATRIX_GREEN_BIAS,
                GL_POST_COLOR_MATRIX_BLUE_BIAS,
                GL_POST_COLOR_MATRIX_ALPHA_BIAS,
                GL_POST_CONVOLUTION_RED_SCALE,
                GL_POST_CONVOLUTION_GREEN_SCALE,
                GL_POST_CONVOLUTION_BLUE_SCALE,
                GL_POST_CONVOLUTION_ALPHA_SCALE,
                GL_POST_CONVOLUTION_RED_BIAS,
                GL_POST_CONVOLUTION_GREEN_BIAS,
                GL_POST_CONVOLUTION_BLUE_BIAS,                and
                GL_POST_CONVOLUTION_ALPHA_BIAS.

       _param2  Specifies the value that _param1 is set to.


DESCRIPTION

       glPixelTransfer  sets pixel transfer modes that affect the
       operation of  subsequent  glCopyPixels,  glCopyTexImage1D,
       glCopyTexImage2D,                     glCopyTexSubImage1D,
       glCopyTexSubImage2D,  glCopyTexSubImage3D,   glDrawPixels,
       glReadPixels,  glTexImage1D,  glTexImage2D,  glTexImage3D,
       glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D com-
       mands.  Additionally, if the GL_ARB_imaging subset is sup-
       ported,  the   routines   glColorTable,   glColorSubTable,
       glConvolutionFilter1D, glConvolutionFilter2D, glHistogram,
       glMinmax, and glSeparableFilter2D are also affected.   The
       algorithms  that  are  specified  by  pixel transfer modes
       operate on pixels after  they  are  read  from  the  frame
       buffer  (glCopyPixels  glCopyTexImage1D, glCopyTexImage2D,
       glCopyTexSubImage1D,                  glCopyTexSubImage2D,
       glCopyTexSubImage3D,  and  glReadPixels), or unpacked from
       client memory (glDrawPixels,  glTexImage1D,  glTexImage2D,
       glTexImage3D,    glTexSubImage1D,   glTexSubImage2D,   and
       pixels  comprise  a  single  floating-point  value,   with
       unspecified  mantissa and exponent sizes, scaled such that
       0.0 represents the minimum depth  buffer  value,  and  1.0
       represents the maximum depth buffer value.  Finally, sten-
       cil pixels  comprise  a  single  fixed-point  value,  with
       unspecified precision to the right of the binary point.

       The  pixel transfer operations performed on the four basic
       pixel types are as follows:

       Color       Each of the four color  components  is  multi-
                   plied  by a scale factor, then added to a bias
                   factor.  That is, the red component is  multi-
                   plied   by   GL_RED_SCALE,   then   added   to
                   GL_RED_BIAS; the green component is multiplied
                   by     GL_GREEN_SCALE,     then    added    to
                   GL_GREEN_BIAS; the blue  component  is  multi-
                   plied   by   GL_BLUE_SCALE,   then   added  to
                   GL_BLUE_BIAS; and the alpha component is  mul-
                   tiplied   by  GL_ALPHA_SCALE,  then  added  to
                   GL_ALPHA_BIAS.  After all  four  color  compo-
                   nents  are  scaled and biased, each is clamped
                   to the range [0,1].   All  color,  scale,  and
                   bias     values     are     specified     with
                   glPixelTransfer.

                   If GL_MAP_COLOR is true, each color  component
                   is  scaled  by  the  size of the corresponding
                   color-to-color map, then replaced by the  con-
                   tents of that map indexed by the scaled compo-
                   nent.  That is, the red component is scaled by
                   GL_PIXEL_MAP_R_TO_R_SIZE, then replaced by the
                   contents  of  GL_PIXEL_MAP_R_TO_R  indexed  by
                   itself.   The  green  component  is  scaled by
                   GL_PIXEL_MAP_G_TO_G_SIZE, then replaced by the
                   contents  of  GL_PIXEL_MAP_G_TO_G  indexed  by
                   itself.   The  blue  component  is  scaled  by
                   GL_PIXEL_MAP_B_TO_B_SIZE, then replaced by the
                   contents  of  GL_PIXEL_MAP_B_TO_B  indexed  by
                   itself.   And the alpha component is scaled by
                   GL_PIXEL_MAP_A_TO_A_SIZE, then replaced by the
                   contents  of  GL_PIXEL_MAP_A_TO_A  indexed  by
                   itself.  All components taken  from  the  maps
                   are   then   clamped   to   the  range  [0,1].
                   GL_MAP_COLOR      is      specified       with
                   glPixelTransfer.   The contents of the various
                   maps are specified with glPixelMap.

                   If the GL_ARB_imaging extension is  supported,
                   each  of  the  four  color  components  may be
                   scaled and biased after tranformation  by  the
                   color  matrix.   That is, the red component is
                   Similiarly, if the GL_ARB_imaging extension is
                   supported,  each  of the four color components
                   may be scaled and biased after  processing  by
                   the  enabled convolution filter.  That is, the
                   red     component     is     multiplied     by
                   GL_POST_CONVOLUTION_RED_SCALE,  then  added to
                   GL_POST_CONVOLUTION_RED_BIAS; the green compo-
                   nent          is         multiplied         by
                   GL_POST_CONVOLUTION_GREEN_SCALE, then added to
                   GL_POST_CONVOLUTION_GREEN_BIAS;  the blue com-
                   ponent        is         multiplied         by
                   GL_POST_CONVOLUTION_BLUE_SCALE,  then added to
                   GL_POST_CONVOLUTION_BLUE_BIAS; and  the  alpha
                   component        is        multiplied       by
                   GL_POST_CONVOLUTION_ALPHA_SCALE, then added to
                   GL_POST_CONVOLUTION_ALPHA_BIAS.    After   all
                   four color components are scaled  and  biased,
                   each is clamped to the range [0,1].

       Color index Each   color   index   is   shifted   left  by
                   GL_INDEX_SHIFT bits; any bits beyond the  num-
                   ber  of  fraction  bits  carried by the fixed-
                   point  index  are  filled  with   zeros.    If
                   GL_INDEX_SHIFT  is  negative,  the shift is to
                   the   right,   again   zero   filled.     Then
                   GL_INDEX_OFFSET   is   added   to  the  index.
                   GL_INDEX_SHIFT and GL_INDEX_OFFSET are  speci-
                   fied with
                   glPixelTransfer.

                   From  this point, operation diverges depending
                   on the required  of the resulting pixels.   If
                   the  resulting  pixels  are to be written to a
                   color index buffer, or if they are being  read
                   back  to client memory in GL_COLOR_INDEX , the
                   pixels continue to be treated as indices.   If
                   GL_MAP_COLOR  is true, each index is masked by
                   2n-1,  where  n  is  GL_PIXEL_MAP_I_TO_I_SIZE,
                   then    replaced    by    the    contents   of
                   GL_PIXEL_MAP_I_TO_I  indexed  by  the   masked
                   value.    GL_MAP_COLOR   is   specified   with
                   glPixelTransfer.  The contents  of  the  index
                   map is specified with glPixelMap.

                   If  the  resulting pixels are to be written to
                   an RGBA color buffer, or if they are read back
                   to    client   memory   in   a    other   than
                   GL_COLOR_INDEX, the pixels are converted  from
                   indices to colors by referencing the four maps
                   GL_PIXEL_MAP_I_TO_R,      GL_PIXEL_MAP_I_TO_G,
                   GL_PIXEL_MAP_I_TO_B,  and GL_PIXEL_MAP_I_TO_A.
                   Before being dereferenced, the index is masked
                   as   a   color   index   is,   then  added  to
                   GL_INDEX_OFFSET.  If GL_MAP_STENCIL  is  true,
                   each  index  is  masked  by  2n-1,  where n is
                   GL_PIXEL_MAP_S_TO_S_SIZE, then replaced by the
                   contents of GL_PIXEL_MAP_S_TO_S indexed by the
                   masked value.

       The following table gives the  type,  initial  value,  and
       range  of  valid  values  for  each  of the pixel transfer
       parameters that are set with glPixelTransfer.


-------------------------------------------------------------------------

_param1 Type Initial Value Valid Range

-------------------------------------------------------------------------

GL_MAP_COLOR boolean false true/false


GL_MAP_STENCIL boolean false true/false


GL_INDEX_SHIFT integer 0 (-oo,oo)


GL_INDEX_OFFSET integer 0 (-oo,oo)


GL_RED_SCALE float 1 (-oo,oo)


GL_GREEN_SCALE float 1 (-oo,oo)


GL_BLUE_SCALE float 1 (-oo,oo)


GL_ALPHA_SCALE float 1 (-oo,oo)


GL_DEPTH_SCALE float 1 (-oo,oo)


GL_RED_BIAS float 0 (-oo,oo)


GL_GREEN_BIAS float 0 (-oo,oo)


GL_BLUE_BIAS float 0 (-oo,oo)


GL_ALPHA_BIAS float 0 (-oo,oo)


GL_DEPTH_BIAS float 0 (-oo,oo)


GL_POST_COLOR_MATRIX_RED_SCALE float 1 (-oo,oo)


GL_POST_COLOR_MATRIX_GREEN_SCALE float 1 (-oo,oo)


GL_POST_COLOR_MATRIX_BLUE_SCALE float 1 (-oo,oo)


GL_POST_COLOR_MATRIX_ALPHA_SCALE float 1 (-oo,oo)


GL_POST_COLOR_MATRIX_RED_BIAS float 0 (-oo,oo)


GL_POST_COLOR_MATRIX_GREEN_BIAS float 0 (-oo,oo)


GL_POST_COLOR_MATRIX_BLUE_BIAS float 0 (-oo,oo)


GL_POST_COLOR_MATRIX_ALPHA_BIAS float 0 (-oo,oo)


GL_POST_CONVOLUTION_RED_SCALE float 1 (-oo,oo)


GL_POST_CONVOLUTION_GREEN_SCALE float 1 (-oo,oo)


GL_POST_CONVOLUTION_BLUE_SCALE float 1 (-oo,oo)


GL_POST_CONVOLUTION_ALPHA_SCALE float 1 (-oo,oo)


GL_POST_CONVOLUTION_RED_BIAS float 0 (-oo,oo)


GL_POST_CONVOLUTION_GREEN_BIAS float 0 (-oo,oo)


GL_POST_CONVOLUTION_BLUE_BIAS float 0 (-oo,oo)


GL_POST_CONVOLUTION_ALPHA_BIAS float 0 (-oo,oo)

-------------------------------------------------------------------------


       glPixelTransferf can be used to  set  any  pixel  transfer
       parameter.   If  the  parameter type is boolean, 0 implies
       false and any other value implies true.  If _param1 is  an
       integer parameter, _param2 is rounded to the nearest inte-
       glTexImage2D,        glTexImage3D,        glTexSubImage1D,
       glTexSubImage2D, or glTexSubImage3D.  command is placed in
       a  display  list (see glNewList and glCallList), the pixel
       transfer mode settings in effect when the display list  is
       executed  are the ones that are used.  They may be differ-
       ent from the settings when the command was  compiled  into
       the display list.


ERRORS

       GL_INVALID_ENUM is generated if _param1 is not an accepted
       value.

       GL_INVALID_OPERATION is generated  if  glPixelTransfer  is
       executed  between  the execution of glBegin and the corre-
       sponding execution of glEnd.


ASSOCIATED GETS

       glGet with argument GL_MAP_COLOR
       glGet with argument GL_MAP_STENCIL
       glGet with argument GL_INDEX_SHIFT
       glGet with argument GL_INDEX_OFFSET
       glGet with argument GL_RED_SCALE
       glGet with argument GL_RED_BIAS
       glGet with argument GL_GREEN_SCALE
       glGet with argument GL_GREEN_BIAS
       glGet with argument GL_BLUE_SCALE
       glGet with argument GL_BLUE_BIAS
       glGet with argument GL_ALPHA_SCALE
       glGet with argument GL_ALPHA_BIAS
       glGet with argument GL_DEPTH_SCALE
       glGet with argument GL_DEPTH_BIAS
       glGet with argument GL_POST_COLOR_MATRIX_RED_SCALE
       glGet with argument GL_POST_COLOR_MATRIX_RED_BIAS
       glGet with argument GL_POST_COLOR_MATRIX_GREEN_SCALE
       glGet with argument GL_POST_COLOR_MATRIX_GREEN_BIAS
       glGet with argument GL_POST_COLOR_MATRIX_BLUE_SCALE
       glGet with argument GL_POST_COLOR_MATRIX_BLUE_BIAS
       glGet with argument GL_POST_COLOR_MATRIX_ALPHA_SCALE
       glGet with argument GL_POST_COLOR_MATRIX_ALPHA_BIAS
       glGet with argument GL_POST_CONVOLUTION_RED_SCALE
       glGet with argument GL_POST_CONVOLUTION_RED_BIAS
       glGet with argument GL_POST_CONVOLUTION_GREEN_SCALE
       glGet with argument GL_POST_CONVOLUTION_GREEN_BIAS
       glGet with argument GL_POST_CONVOLUTION_BLUE_SCALE
       glGet with argument GL_POST_CONVOLUTION_BLUE_BIAS
       glGet with argument GL_POST_CONVOLUTION_ALPHA_SCALE
       glGet with argument GL_POST_CONVOLUTION_ALPHA_BIAS


SEE ALSO

       glCallList,         glColorTable,         glColorSubTable,
       glConvolutionFilter1D,              glConvolutionFilter2D,
       glCopyPixels,     glCopyTexImage1D,      glCopyTexImage2D,