GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
glDrawPixels - write a block of pixels to the frame buffer
void glDrawPixels( GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid *pixels )
width, height Specify the dimensions of the pixel rectangle
to be written into the frame buffer.
format Specifies the 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.
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.
MirOS BSD #10-current Printed 20.2.2012 1
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
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, depend-
ing 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
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 com-
ponents 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, specified 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 x 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 pix-
els 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 advance-
ments, 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 x 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
MirOS BSD #10-current Printed 20.2.2012 2
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
details of these operations, as well as the target buffer
into which the pixels are drawn, are specific to the 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 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 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 replace-
ment of the index is done or not, the integer part
of the index is then ANDed with 2b-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 ras-
ter position z coordinate and texture coordinates
to each pixel, then assigning x and y window coor-
dinates 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
MirOS BSD #10-current Printed 20.2.2012 3
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
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 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 replace-
ment of the index is done or not, the integer part
of the index is then ANDed with 2b-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
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
MirOS BSD #10-current Printed 20.2.2012 4
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
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 frag-
ments 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 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 frag-
ments by attaching the current raster position z coor-
dinate and texture coordinates to each pixel, then
assigning x and y window coordinates to the nth frag-
ment such that
xn = xr + n mod width
yn = yr + | n/width |
where (xr,yr) is the current raster position. These
MirOS BSD #10-current Printed 20.2.2012 5
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
pixel fragments are then treated just like the frag-
ments 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 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 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 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 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, fol-
lowed by green, followed by blue; for GL_BGR, the first
component is blue, followed by green and then red. Each
component is converted 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.
MirOS BSD #10-current Printed 20.2.2012 6
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
GL_LUMINANCE
Each pixel is a single luminance component. This com-
ponent 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
converted luminance value, and alpha set to the con-
verted 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 con-
stants for the type parameter:
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 fac-
tors of 1. If
glPixelZoom is used to change the x and y pixel zoom
MirOS BSD #10-current Printed 20.2.2012 7
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
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 rectangle with corners at
(xr + zoomxn, yr + zoomym)
(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.
GL_BGR and GL_BGRA are only valid for format if the GL ver-
sion 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.
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 exe-
cuted 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
MirOS BSD #10-current Printed 20.2.2012 8
GLDRAWPIXELS(3G) UNIX Programmer's Manual GLDRAWPIXELS(3G)
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.
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
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)
MirOS BSD #10-current Printed 20.2.2012 9
Generated on 2012-02-20 02:47:02 by $MirOS: src/scripts/roff2htm,v 1.70 2011/12/03 18:21:12 tg Exp $
These manual pages and other documentation are copyrighted by their respective writers;
their source is available at our CVSweb,
AnonCVS, and other mirrors. The rest is Copyright © 2002‒2011 The MirOS Project, Germany.
This product includes material
provided by Thorsten Glaser.
This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.