manpagez: man pages & more
man glDrawPixels(3)
Home | html | info | man
glDrawPixels(3)                                              glDrawPixels(3)




NAME

       glDrawPixels - write a block of pixels to the frame buffer



C SPECIFICATION

       void glDrawPixels( GLsizei width,
                          GLsizei height,
                          GLenum format,
                          GLenum type,
                          const GLvoid *pixels )



PARAMETERS

       width, height Specify the dimensions of the pixel rectangle to be writ-
                     ten into the frame buffer.

       format        Specifies the format of the pixel  data.   Symbolic  con-
                     stants          GL_COLOR_INDEX,         GL_STENCIL_INDEX,
                     GL_DEPTH_COMPONENT,  GL_RGB,  GL_BGR,  GL_RGBA,  GL_BGRA,
                     GL_RED,  GL_GREEN,  GL_BLUE,  GL_ALPHA, GL_LUMINANCE, and
                     GL_LUMINANCE_ALPHA are accepted.

       type          Specifies the data type for pixels.   Symbolic  constants
                     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,                           and
                     GL_UNSIGNED_INT_2_10_10_10_REV are accepted.

       pixels        Specifies a pointer to the pixel data.


DESCRIPTION

       glDrawPixels  reads pixel data from memory and writes it into the frame
       buffer
       relative to the current raster position, provided that the raster posi-
       tion is valid.  Use
       glRasterPos to set the current raster position; use glGet with argument
       GL_CURRENT_RASTER_POSITION_VALID to determine if the  specified  raster
       position  is  valid, and glGet with argument GL_CURRENT_RASTER_POSITION
       to query the raster position.

       Several parameters define the encoding of pixel data in memory and con-
       trol  the processing of the pixel data before it is placed in the frame
       buffer.  These parameters are set  with  four  commands:  glPixelStore,
       glPixelTransfer,  glPixelMap,  and  glPixelZoom.   This  reference page
       describes the effects on glDrawPixels of many,  but  not  all,  of  the
       parameters specified by these four commands.

       Data  is  read  from  pixels as a sequence of signed or unsigned bytes,
       signed or unsigned shorts, signed or unsigned integers, or  single-pre-
       cision  floating-point  values, depending on type.  When type is one of
       GL_UNSIGNED_BYTE,      GL_BYTE,      GL_UNSIGNED_SHORT,       GL_SHORT,
       GL_UNSIGNED_INT, GL_INT, or GL_FLOAT each of these bytes, shorts, inte-
       gers, or floating-point values is interpreted as  one  color  or  depth
       component,  or  one  index,  depending  on format.  When type is one of
       GL_UNSIGNED_BYTE_3_3_2,                        GL_UNSIGNED_SHORT_5_6_5,
       GL_UNSIGNED_SHORT_4_4_4_4,                   GL_UNSIGNED_SHORT_5_5_5_1,
       GL_UNSIGNED_INT_8_8_8_8,  GL_UNSIGNED_INT_10_10_10_2,   each   unsigned
       value  is  interpreted  as  containing  all the components for a single
       pixel, with the color components arranged according  to  format.   When
       type is one of GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5_REV,
       GL_UNSIGNED_SHORT_4_4_4_4_REV,           GL_UNSIGNED_SHORT_1_5_5_5_REV,
       GL_UNSIGNED_INT_8_8_8_8_REV,    GL_UNSIGNED_INT_2_10_10_10_REV,    each
       unsigned value is interpreted as containing all color components, spec-
       ified  by  format,  for a single pixel in a reversed order. Indices are
       always treated individually.  Color components are treated as groups of
       one, two, three, or four values, again based on format. Both individual
       indices and groups of components are referred to as pixels.  If type is
       GL_BITMAP,  the  data must be unsigned bytes, and format must be either
       GL_COLOR_INDEX or GL_STENCIL_INDEX.  Each unsigned byte is  treated  as
       eight 1-bit pixels, with bit ordering determined by GL_UNPACK_LSB_FIRST
       (see glPixelStore).

       width * height pixels are read from memory, starting at  location  pix-
       els.   By  default,  these  pixels are taken from adjacent memory loca-
       tions, except that after all width pixels are read, the read pointer is
       advanced  to  the next four-byte boundary.  The four-byte row alignment
       is specified by glPixelStore with argument GL_UNPACK_ALIGNMENT, and  it
       can be set to one, two, four, or eight bytes.  Other pixel store param-
       eters specify different read  pointer  advancements,  both  before  the
       first  pixel  is  read  and  after  all width pixels are read.  See the
       glPixelStore reference page for details on these options.

       The width * height pixels that are read from memory are  each  operated
       on in the same way, based on the values of several parameters specified
       by glPixelTransfer and glPixelMap.  The details of these operations, as
       well as the target buffer into which the pixels are drawn, are specific
       to the format of the pixels, as specified by format.  format can assume
       one of 13 symbolic values:

       GL_COLOR_INDEX
                 Each pixel is a single value, a color index.  It is converted
                 to fixed-point , with an unspecified number of  bits  to  the
                 right  of  the  binary  point,  regardless of the memory data
                 type.  Floating-point values convert to true fixed-point val-
                 ues.   Signed and unsigned integer data is converted with all
                 fraction bits set to 0.  Bitmap data convert to either  0  or
                 1.

                 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 the GL is in RGBA mode, the resulting index  is  converted
                 to  an  RGBA  pixel with the help of the 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  tables.   If  the  GL  is in color index
                 mode, and if GL_MAP_COLOR is true, the index is 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 (2^b) -1, where b is the number of bits in a color
                 index buffer.

                 The  GL then converts the resulting indices or RGBA colors to
                 fragments by attaching the current raster position z  coordi-
                 nate  and texture coordinates to each pixel, then assigning x
                 and y window coordinates to the nth fragment such that


                                     xn = xr + n mod width

                                       yn = yr + n/width



                 where (xr, yr) is the current raster position.   These  pixel
                 fragments  are then treated just like the fragments generated
                 by rasterizing points, lines, or polygons.  Texture  mapping,
                 fog,  and  all the fragment operations are applied before the
                 fragments are written to the frame buffer.

       GL_STENCIL_INDEX
                 Each pixel is a single value, a stencil index.   It  is  con-
                 verted to fixed-point , with an unspecified number of bits to
                 the right of the binary point, regardless of the memory  data
                 type.  Floating-point values convert to true fixed-point val-
                 ues.  Signed and unsigned integer data is converted with  all
                 fraction  bits  set to 0.  Bitmap data convert to either 0 or
                 1.

                 Each fixed-point index is then shifted left by GL_INDEX_SHIFT
                 bits,  and  added  to  GL_INDEX_OFFSET.  If GL_INDEX_SHIFT is
                 negative, 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 (2^b)-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 nth index is written to location


                                xn = xr + n mod width

                                  yn = yr + n/width


              where (xr , yr) is the current raster position.  Only the  pixel
              ownership  test,  the  scissor  test,  and the stencil writemask
              affect these write operations.

       GL_DEPTH_COMPONENT
              Each pixel is a single-depth component.  Floating-point data  is
              converted directly to an internal floating-point
               with unspecified precision.  Signed integer data is mapped lin-
              early to the internal floating-point
               such that the most positive representable integer value maps to
              1.0,  and  the  most  negative representable value maps to -1.0.
              Unsigned integer data is mapped similarly: the  largest  integer
              value  maps  to 1.0, and 0 maps to 0.0.  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].

              The GL then converts the resulting depth components to fragments
              by attaching the current raster position color  or  color  index
              and  texture  coordinates  to each pixel, then assigning x and y
              window coordinates to the nth fragment such that


                                xn = xr + n mod width

                                  yn = yr + n/width


              where (xr , yr) is the current  raster  position.   These  pixel
              fragments  are then treated just like the fragments generated by
              rasterizing points, lines, or polygons.  Texture  mapping,  fog,
              and all the fragment operations are applied before the fragments
              are written to the frame buffer.

       GL_RGBA

       GL_BGRA
              Each pixel is a four-component group: for GL_RGBA, the red  com-
              ponent  is  first, followed by green, followed by blue, followed
              by alpha; for GL_BGRA the order is blue,  green,  red  and  then
              alpha.   Floating-point  values  are  converted  directly  to an
              internal floating-point
               with unspecified precision.  Signed integer values  are  mapped
              linearly to the internal floating-point
               such that the most positive representable integer value maps to
              1.0, and the most negative representable  value  maps  to  -1.0.
              (Note  that  this  mapping does not convert 0 precisely to 0.0.)
              Unsigned integer data is mapped similarly: the  largest  integer
              value  maps  to 1.0, and 0 maps to 0.0.  The resulting floating-
              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
              respectively.

              The GL then converts the resulting RGBA colors to  fragments  by
              attaching  the  current raster position z coordinate and texture
              coordinates to each pixel, then assigning x and y window coordi-
              nates to the nth fragment such that


                                xn = xr + n mod width

                                  yn = yr + n/width


              where  (xr  ,  yr)  is the current raster position.  These pixel
              fragments are then treated just like the fragments generated  by
              rasterizing  points,  lines, or polygons.  Texture mapping, fog,
              and all the fragment operations are applied before the fragments
              are written to the frame buffer.

       GL_RED Each  pixel  is  a single red component.  This component is con-
              verted to the internal floating-point  in the same way  the  red
              component  of  an RGBA pixel is. It is then converted to an RGBA
              pixel with green and blue set to 0, and alpha set to  1.   After
              this  conversion, the pixel is treated as if it had been read as
              an RGBA pixel.

       GL_GREEN
              Each pixel is a single green component.  This component is  con-
              verted to the internal floating-point  in the same way the green
              component of an RGBA pixel is.  It is then converted to an  RGBA
              pixel  with  red  and  blue set to 0, and alpha set to 1.  After
              this conversion, the pixel is treated as if it had been read  as
              an RGBA pixel.

       GL_BLUE
              Each  pixel  is a single blue component.  This component is con-
              verted to the internal floating-point  in the same way the  blue
              component  of an RGBA pixel is.  It is then converted to an RGBA
              pixel with red and green set to 0, and alpha set  to  1.   After
              this  conversion, the pixel is treated as if it had been read as
              an RGBA pixel.

       GL_ALPHA
              Each pixel is a single alpha component.  This component is  con-
              verted to the internal floating-point  in the same way the alpha
              component of an RGBA pixel is.  It is then converted to an  RGBA
              pixel  with  red,  green, and blue set to 0.  After this conver-
              sion, the pixel is treated as if it had been  read  as  an  RGBA
              pixel.

       GL_RGB

       GL_BGR Each  pixel  is  a three-component group: red first, followed by
              green, followed by blue; for  GL_BGR,  the  first  component  is
              blue,  followed  by  green and then red.  Each component is con-
              verted to the internal floating-point  in the same way the  red,
              green,  and  blue  components  of  an RGBA pixel are.  The color
              triple is converted to an RGBA pixel with alpha set to 1.  After
              this  conversion, the pixel is treated as if it had been read as
              an RGBA pixel.

       GL_LUMINANCE
              Each pixel is a single luminance component.  This  component  is
              converted  to  the  internal floating-point  in the same way the
              red component of an RGBA pixel is.  It is then converted  to  an
              RGBA  pixel with red, green, and blue set to the converted lumi-
              nance value, and alpha set to 1.   After  this  conversion,  the
              pixel is treated as if it had been read as an RGBA pixel.

       GL_LUMINANCE_ALPHA
              Each  pixel  is a two-component group: luminance first, followed
              by alpha.  The two components  are  converted  to  the  internal
              floating-point   in  the  same  way the red component of an RGBA
              pixel is.  They are then converted to an RGBA  pixel  with  red,
              green,  and blue set to the converted luminance value, and alpha
              set to the converted alpha value.  After  this  conversion,  the
              pixel is treated as if it had been read as an RGBA pixel.

       The  following  table summarizes the meaning of the valid constants for
       the type parameter:



       Type               Corresponding Type _
        GL_UNSIGNED_BYTE  unsigned 8-bit integer
        GL_BYTE           signed 8-bit integer
        GL_BITMAP         single bits in unsigned 8-bit integers
        GL_UNSIGNED_SHORT unsigned 16-bit integer
        GL_SHORT          signed 16-bit integer
        GL_UNSIGNED_INT   unsigned 32-bit integer
        GL_INT            32-bit integer
        GL_FLOAT          single-precision floating-point
        GL_UNSIGNED_BYTE_3_3_2
                          unsigned 8-bit integer
        GL_UNSIGNED_BYTE_2_3_3_REV
                          unsigned 8-bit integer with
                          reversed component ordering
        GL_UNSIGNED_SHORT_5_6_5
                          unsigned 16-bit integer
        GL_UNSIGNED_SHORT_5_6_5_REV
                          unsigned 16-bit integer with
                          reversed component ordering
        GL_UNSIGNED_SHORT_4_4_4_4
                          unsigned 16-bit integer
        GL_UNSIGNED_SHORT_4_4_4_4_REV
                          unsigned 16-bit integer with
                          reversed component ordering
        GL_UNSIGNED_SHORT_5_5_5_1
                          unsigned 16-bit integer
        GL_UNSIGNED_SHORT_1_5_5_5_REV
                          unsigned 16-bit integer with
                          reversed component ordering
        GL_UNSIGNED_INT_8_8_8_8
                          unsigned 32-bit integer
        GL_UNSIGNED_INT_8_8_8_8_REV
                          unsigned 32-bit integer with
                          reversed component ordering
        GL_UNSIGNED_INT_10_10_10_2
                          unsigned 32-bit integer
        GL_UNSIGNED_INT_2_10_10_10_REV
                          unsigned 32-bit integer with
                          reversed component ordering



       The rasterization described so far assumes pixel zoom factors of 1.  If
       glPixelZoom  is  used  to change the x and y pixel zoom factors, pixels
       are converted to fragments as follows.  If  (xr,  yr)  is  the  current
       raster  position, and a given pixel is in the nth column and mth row of
       the pixel rectangle, then fragments are generated for pixels whose cen-
       ters are in the rectangle with corners at

                              ( xr + zoomx * n, yr + zoomy *m)

                          ( xr + zoomx * (n+1), yr + zoomy *(m+1))


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


NOTES

       GL_BGR and GL_BGRA are only valid for format if the GL version  is  1.2
       or greater.

       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, and GL_UNSIGNED_INT_2_10_10_10_REV are only
       valid for type if the GL version is 1.2 or greater.


ERRORS

       GL_INVALID_VALUE is generated if either width or height is negative.

       GL_INVALID_ENUM  is  generated  if  format  or  type  is not one of the
       accepted values.

       GL_INVALID_OPERATION  is  generated  if  format  is  GL_RED,  GL_GREEN,
       GL_BLUE,  GL_ALPHA,  GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_LUMINANCE, or
       GL_LUMINANCE_ALPHA, and the GL is in color index mode.

       GL_INVALID_ENUM is generated if type is GL_BITMAP  and  format  is  not
       either GL_COLOR_INDEX or GL_STENCIL_INDEX.

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

       GL_INVALID_OPERATION is generated if glDrawPixels is  executed  between
       the execution of glBegin and the corresponding execution of glEnd.

       GL_INVALID_OPERATION     is     generated     if    format    is    one
       GL_UNSIGNED_BYTE_3_3_2,                     GL_UNSIGNED_BYTE_2_3_3_REV,
       GL_UNSIGNED_SHORT_5_6_5,  of  GL_UNSIGNED_SHORT_5_6_5_REV and format is
       not GL_RGB.

       GL_INVALID_OPERATION   is   generated   if    format    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  for-
       mat is neither GL_RGBA nor GL_BGRA.


ASSOCIATED GETS

       glGet with argument GL_CURRENT_RASTER_POSITION
       glGet with argument GL_CURRENT_RASTER_POSITION_VALID


SEE ALSO

       glAlphaFunc(3), glBlendFunc(3), glCopyPixels(3), glDepthFunc(3),
       glLogicOp(3), glPixelMap(3), glPixelStore(3), glPixelTransfer(3),
       glPixelZoom(3), glRasterPos(3), glReadPixels(3), glScissor(3),
       glStencilFunc(3)



                                                              glDrawPixels(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:20:18 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.