Mac Developer Library Developer
Search

 

This manual page is part of Xcode Tools version 5.0

To obtain these tools:

If you are running a version of Xcode Tools other than 5.0, view the documentation locally:

  • In Xcode

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



GLDRAWPIXELS(3G)                                                                            GLDRAWPIXELS(3G)



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 written into the frame buffer.

       format        Specifies   the   format   of  the  pixel  data.   Symbolic  constants  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 position 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 control 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-precision 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, integers, or floating-point values is interpreted as one color or depth com-ponent, component,
       ponent,  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  compo-nents, components,
       nents,  specified by format, for a single pixel in a reversed order. Indices are always treated indi-vidually. individually.
       vidually.  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 pixels.  By  default,  these  pixels
       are  taken  from  adjacent  memory  locations,  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 parameters 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 values.  Signed and unsigned inte-ger integer
                 ger 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  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 inte-ger integer
                 ger 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 coordinate 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 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 values.  Signed and unsigned inte-ger integer
                 ger  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 inte-ger integer
                 ger  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 linearly to the internal floating-point floatingpoint
              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 component 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 float-ing-point floating-point
              ing-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  compo-nents. components.
              nents.  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
              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_RED Each pixel is a single red component.  This component is converted to the  internal  floating-point floatingpoint
              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 converted to the internal floating-point floatingpoint
              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 converted to the internal  floating-point floatingpoint
              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 converted to the internal floating-point floatingpoint
              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 conversion, 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 converted
              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 luminance 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 con-verted converted
              verted 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 centers are in the rectan-gle rectangle
       gle 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 format 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(3G),   glBlendFunc(3G),   glCopyPixels(3G),   glDepthFunc(3G),   glLogicOp(3G),   glPixelMap(3G),   glPixelStore(3G),
       glPixelTransfer(3G), glPixelZoom(3G), glRasterPos(3G), glReadPixels(3G), glScissor(3G), glStencilFunc(3G)




                                                                                            GLDRAWPIXELS(3G)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation to the OpenGL project.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback