- set pixel storage modes



C SPECIFICATION


PARAMETERS

       _param1  Specifies  the  symbolic name of the parameter to
                be set.  Six values affect the packing  of  pixel
                data     into     memory:     GL_PACK_SWAP_BYTES,
                GL_PACK_LSB_FIRST,            GL_PACK_ROW_LENGTH,
                GL_PACK_IMAGE_HEIGHT,        GL_PACK_SKIP_PIXELS,
                GL_PACK_SKIP_ROWS,    GL_PACK_SKIP_IMAGES,    and
                GL_PACK_ALIGNMENT.  Six more affect the unpacking
                of pixel data from memory:  GL_UNPACK_SWAP_BYTES,
                GL_UNPACK_LSB_FIRST,        GL_UNPACK_ROW_LENGTH,
                GL_UNPACK_IMAGE_HEIGHT,    GL_UNPACK_SKIP_PIXELS,
                GL_UNPACK_SKIP_ROWS,  GL_UNPACK_SKIP_IMAGES,  and
                GL_UNPACK_ALIGNMENT.

       _param2  Specifies the value that _param1 is set to.


DESCRIPTION

       glPixelStore sets pixel  storage  modes  that  affect  the
       operation  of  subsequent glDrawPixels and glReadPixels as
       well as the unpacking of  polygon  stipple  patterns  (see
       glPolygonStipple),  bitmaps  (see  glBitmap), texture pat-
       terns  (see  glTexImage1D,   glTexImage2D,   glTexImage3D,
       glTexSubImage1D, glTexSubImage2D, glTexSubImage3D).  Addi-
       tionally, if the GL_ARB_imaging  extension  is  supported,
       pixle   storage   modes  affect  convlution  filters  (see
       glConvolutionFilter1D,     glConvolutionFilter2D,      and
       glSeparableFilter2D,  color  table  (see glColorTable, and
       glColorSubTable,    and    unpacking    histogram     (See
       glHistogram), and minmax (See glMinmax) data.

       _param1 is a symbolic constant indicating the parameter to
       be set, and _param2 is the new value.  Six of  the  twelve
       storage  parameters  affect  how pixel data is returned to
       client memory.  They are as follows:

       GL_PACK_SWAP_BYTES
                 If true, byte ordering for multibyte color  com-
                 ponents,  depth  components,  color  indices, or
                 stencil indices is  reversed.   That  is,  if  a
                 four-byte  component  consists  of bytes b0, b1,
                 b2, b3, it is stored in memory as b3, b2, b1, b0
                 if       GL_PACK_SWAP_BYTES       is       true.
                 GL_PACK_SWAP_BYTES has no effect on  the  memory
                 order  of components within a pixel, only on the
                 order of bytes  within  components  or  indices.
                 For  example,  the  three components of a GL_RGB
                 pixel are always stored with  red  first,  green
                 second,  and blue third, regardless of the value
                 next row is obtained by skipping
                                     nl    s>=a









                                  k={









                                     a<I>s_|s_n<I>a_l_|s<a

                 components or indices, where n is the number  of
                 components  or indices in a pixel, l is the num-
                 ber of pixels in a row (GL_PACK_ROW_LENGTH if it
                 is  greater  than  0,  the width argument to the
                 pixel routine otherwise),  a  is  the  value  of
                 GL_PACK_ALIGNMENT,  and s is the size, in bytes,
                 of a single component (if a<s, then it is as  if
                 a=s).  In the case of 1-bit values, the location
                 of the next row is obtained by skipping

                                     k=8a|n_l<I>a_|

                 components or indices.

                 The word component in this description refers to
                 the nonindex values red, green, blue, alpha, and
                 depth.  Storage  GL_RGB, for example, has  three
                 components per pixel: first red, then green, and
                 finally blue.

       GL_PACK_IMAGE_HEIGHT
                 If greater than 0, GL_PACK_IMAGE_HEIGHT  defines
                 the  number  of  pixels in an image three-dimen-
                 sional  texture  volume.   Where  ``image''   is
                 defined  by  all  pixels  sharing the same third
                 dimension index.  If the first pixel of a row is
                 placed  at  location p in memory, then the loca-
                 tion of the first  pixel  of  the  next  row  is
                 obtained by skipping






                                     a<I>s_|s_n_l<I>a_h_|s<a

                 components  or indices, where n is the number of
                 components or indices in a pixel, l is the  num-
                 ber of pixels in a row (GL_PACK_ROW_LENGTH if it
                 is  greater  than  0,   the  width  argument  to
                 glTexImage3d otherwise), h is the number of rows
                 in a pixel image (GL_PACK_IMAGE_HEIGHT if it  is
                 greater  than  0,  the  height  arguemnt  to the
                 glTexImage3D routine otherwise), a is the  value
                 of  GL_PACK_ALIGNMENT,  and  s  is  the size, in
                 bytes, of a single component (if a<s, then it is
                 as if a=s).

                 The word component in this description refers to
                 the nonindex values red, green, blue, alpha, and
                 depth.   Storage  GL_RGB, for example, has three
                 components per pixel: first red, then green, and
                 finally blue.

       GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, and
       GL_PACK_SKIP_IMAGES
                 These values are provided as  a  convenience  to
                 the  programmer;  they  provide no functionality
                 that cannot be duplicated simply by incrementing
                 the  pointer  passed  to  glReadPixels.  Setting
                 GL_PACK_SKIP_PIXELS to i is equivalent to incre-
                 menting the pointer by in components or indices,
                 where n is the number of components  or  indices
                 in  each  pixel.  Setting GL_PACK_SKIP_ROWS to j
                 is equivalent to incrementing the pointer by  jm
                 components  or indices, where m is the number of
                 components or indices per row, as just  computed
                 in   the  GL_PACK_ROW_LENGTH  section.   Setting
                 GL_PACK_SKIP_IMAGES to k is equivalent to incre-
                 menting the pointer by kp, where p is the number
                 of components or indices per image, as  computed
                 in the GL_PACK_IMAGE_HEIGHT section.

       GL_PACK_ALIGNMENT
                 Specifies  the  alignment  requirements  for the
                 start of each pixel row in memory.   The  allow-
                 able  values  are  1  (byte-alignment),  2 (rows
                 aligned to even-numbered bytes), 4  (word-align-
                 ment),  and  8 (rows start on double-word bound-
                 aries).

              nents, depth components, color indices, or  stencil
              indices  is reversed.  That is, if a four-byte com-
              ponent consists of bytes b0,  b1,  b2,  b3,  it  is
              taken   from   memory   as   b3,   b2,  b1,  b0  if
              GL_UNPACK_SWAP_BYTES is true.  GL_UNPACK_SWAP_BYTES
              has  no  effect  on  the memory order of components
              within a pixel, only on the order of  bytes  within
              components or indices.  For example, the three com-
              ponents of a GL_RGB  pixel are always  stored  with
              red first, green second, and blue third, regardless
              of the value of GL_UNPACK_SWAP_BYTES.

       GL_UNPACK_LSB_FIRST
              If true, bits are ordered within a byte from  least
              significant  to  most  significant;  otherwise, the
              first bit in each byte is the most significant one.
              This is relevant only for bitmap data.

       GL_UNPACK_ROW_LENGTH
              If greater than 0, GL_UNPACK_ROW_LENGTH defines the
              number of pixels in a row.  If the first pixel of a
              row  is  placed  at  location p in memory, then the
              location of the first pixel  of  the  next  row  is
              obtained by skipping
                                    nl    s>=a









                                 k={









                                    a<I>s_|s_n<I>a_l_|s<a

              components  or  indices,  where  n is the number of
              components or indices in a pixel, l is  the  number
              of  pixels  in a row (GL_UNPACK_ROW_LENGTH if it is
              greater than 0, the width  argument  to  the  pixel
              routine    otherwise),    a   is   the   value   of
              GL_UNPACK_ALIGNMENT, and s is the size,  in  bytes,

       GL_UNPACK_IMAGE_HEIGHT
              If  greater  than 0, GL_UNPACK_IMAGE_HEIGHT defines
              the number of pixels in an image of a  three-dimen-
              sional  texture volume.  Where ``image'' is defined
              by all  pixel  sharing  the  same  third  dimension
              index.   If  the  first pixel of a row is placed at
              location p in memory,  then  the  location  of  the
              first pixel of the next row is obtained by skipping
                                   nlh    s>=a









                                k={









                                   a<I>s_|s_n_l<I>a_h_|s<a

              components or indices, where n  is  the  number  of
              components  or  indices in a pixel, l is the number
              of pixels in a row (GL_UNPACK_ROW_LENGTH if  it  is
              greater  than 0, the width argument to glTexImage3D
              otherwise), h is the number of rows in an image  (-
              GL_UNPACK_IMAGE_HEIGHT if it is greater than 0, the
              height argument to glTexImage3D  otherwise),  a  is
              the  value  of  GL_UNPACK_ALIGNMENT,  and  s is the
              size, in bytes, of a single component (if a<s, then
              it is as if a=s).

              The  word  component  in this description refers to
              the nonindex values red, green,  blue,  alpha,  and
              depth.   Storage   GL_RGB,  for  example, has three
              components per pixel: first red,  then  green,  and
              finally blue.

       GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS
              These  values  are provided as a convenience to the
              programmer; they provide no functionality that can-
              not  be  duplicated  by  incrementing  the  pointer
              passed to glDrawPixels, glTexImage1D, glTexImage2D,
              are 1 (byte-alignment), 2 (rows  aligned  to  even-
              numbered  bytes),  4  (word-alignment), and 8 (rows
              start on double-word boundaries).

       The following table gives the  type,  initial  value,  and
       range  of valid values for each storage parameter that can
       be set with glPixelStore.


    -----------------------------------------------------------------
    _param1                   Type     Initial Value    Valid Range
    -----------------------------------------------------------------
    GL_PACK_SWAP_BYTES       boolean       false       true or false
    GL_PACK_LSB_FIRST        boolean       false       true or false
    GL_PACK_ROW_LENGTH       integer         0            [0,oo)
    GL_PACK_IMAGE_HEIGHT     integer         0            [0, oo)
    GL_PACK_SKIP_ROWS        integer         0            [0,oo)
    GL_PACK_SKIP_PIXELS      integer         0            [0,oo)
    GL_PACK_SKIP_IMAGES      integer         0            [0,oo)
    GL_PACK_ALIGNMENT        integer         4         1, 2, 4, or 8
    -----------------------------------------------------------------
    GL_UNPACK_SWAP_BYTES     boolean       false       true or false
    GL_UNPACK_LSB_FIRST      boolean       false       true or false
    GL_UNPACK_ROW_LENGTH     integer         0            [0,oo)
    GL_UNPACK_IMAGE_HEIGHT   integer         0            [0,oo)
    GL_UNPACK_SKIP_ROWS      integer         0            [0,oo)
    GL_UNPACK_SKIP_PIXELS    integer         0            [0,oo)
    GL_UNPACK_SKIP_IMAGES    integer         0            [0,oo)
    GL_UNPACK_ALIGNMENT      integer         4         1, 2, 4, or 8
    -----------------------------------------------------------------


       glPixelStoref can be used to set any pixel  store  parame-
       ter.  If the parameter type is boolean, then if _param2 is
       0, the parameter is false; otherwise it is  set  to  true.
       If _param1 is a integer type parameter, _param2 is rounded
       to the nearest integer.

       Likewise, glPixelStorei can also be used to set any of the
       pixel  store  parameters.   Boolean  parameters are set to
       false if _param2 is 0 and true otherwise.


NOTES

       The pixel  storage  modes  in  effect  when  glDrawPixels,
       glReadPixels,  glTexImage1D,  glTexImage2D,  glTexImage3D,
       glTexSubImage1D,     glTexSubImage2D,     glTexSubImage3D,
       glBitmap,  or glPolygonStipple is placed in a display list
       control the interpretation of memory data.   Likewise,  if
       the GL_ARB_imaging extension is supported, the pixel stor-
       age modes in effect  when  glColorTable,  glColorSubTable,
       glConvolutionFilter1D,      glConvolutionFilter2D,      of
       glSeparableFilter2D is placed in a  display  list  control
       ment is specified as other than 1, 2, 4, or 8.

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



ASSOCIATED GETS

       glGet with argument GL_PACK_SWAP_BYTES
       glGet with argument GL_PACK_LSB_FIRST
       glGet with argument GL_PACK_ROW_LENGTH
       glGet with argument GL_PACK_IMAGE_HEIGHT
       glGet with argument GL_PACK_SKIP_ROWS
       glGet with argument GL_PACK_SKIP_PIXELS
       glGet with argument GL_PACK_SKIP_IMAGES
       glGet with argument GL_PACK_ALIGNMENT
       glGet with argument GL_UNPACK_SWAP_BYTES
       glGet with argument GL_UNPACK_LSB_FIRST
       glGet with argument GL_UNPACK_ROW_LENGTH
       glGet with argument GL_UNPACK_IMAGE_HEIGHT
       glGet with argument GL_UNPACK_SKIP_ROWS
       glGet with argument GL_UNPACK_SKIP_PIXELS
       glGet with argument GL_UNPACK_SKIP_IMAGES
       glGet with argument GL_UNPACK_ALIGNMENT


SEE ALSO

       glBitmap,          glColorTable,          glColorSubTable,
       glConvolutionFilter1D,              glConvolutionFilter2D,
       glSeparableFilter2D,  glDrawPixels, glHistogram, glMinmax,
       glPixelMap,         glPixelTransfer,          glPixelZoom,
       glPolygonStipple,     glPushClientAttrib,    glReadPixels,
       glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D,
       glTexSubImage2D, glTexSubImage3D



                                                                1