GLREADPIXELS(3G) GLREADPIXELS(3G)
NAME
glReadPixels - read a block of pixels from the frame buffer
C SPECIFICATION
void glReadPixels( GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
GLvoid *pixels )
PARAMETERS
x, y Specify the window coordinates of the first pixel that is read
from the frame buffer. This location is the lower left corner of
a rectangular block of pixels.
width, height
Specify the dimensions of the pixel rectangle. width and height
of one correspond to a single pixel.
format
Specifies the of the pixel data. The following symbolic values
are accepted: GLCOLORINDEX, GLSTENCILINDEX,
GLDEPTHCOMPONENT, GLRED, GLGREN, GLBLUE, GLALPHA, GLRGB,
GLBGR, GLRGBA, GLBGRA, GLUMINANCE, and GLUMINANCEALPHA.
type Specifies the data type of the pixel data. Must be one of
GLUNSIGNEDBYTE, GLBYTE, GLBITMAP, GLUNSIGNEDSHORT, GLSHORT,
GLUNSIGNEDINT, GLINT, GLFLOAT, GLUNSIGNEDBYTE332,
GLUNSIGNEDBYTE233REV, GLUNSIGNEDSHORT565,
GLUNSIGNEDSHORT565REV, GLUNSIGNEDSHORT4444,
GLUNSIGNEDSHORT4444REV, GLUNSIGNEDSHORT5551,
GLUNSIGNEDSHORT1555REV, GLUNSIGNEDINT8888,
GLUNSIGNEDINT8888REV, GLUNSIGNEDINT1001001002, or
GLUNSIGNEDINT2100100100REV.
pixels
Returns the pixel data.
DESCRIPTION
glReadPixels returns pixel data from the frame buffer, starting with
the pixel whose lower left corner is at location (x, y), into client
memory starting at location pixels. Several parameters control the
processing of the pixel data before it is placed into client memory.
These parameters are set with three commands: glPixelStore,
glPixelTransfer, and glPixelap. This reference page describes the
effects on glReadPixels of most, but not all of the parameters speci-
fied by these three commands.
When the GLARBimaging extension is supported, the pixel data may be
processed by additional operations including color table lookup, color
matrix tranformations, convolutions, histograms and minimum and maximun
pixel value computations.
glReadPixels returns values from each pixel with lower left corner at
(x ] i, y ] j) for 0 <= i < width and 0 <= j < height. This pixel is
said to be the ith pixel in the jth row. Pixels are returned in row
order from the lowest to the highest row, left to right in each row.
format specifies the for the returned pixel values; accepted values
are:
GLCOLORINDEX
Color indices are read from the color buffer selected by
glReadBuffer. Each index is converted to fixed point,
shifted left or right depending on the value and sign of
GLINDEXSHIFT, and added to GLINDEXOFSET. If
GLMAPCOLOR is GLTRUE, indices are replaced by their map-
pings in the table GLPIXELMAPITOI.
GLSTENCILINDEX
Stencil values are read from the stencil buffer. Each index
is converted to fixed point, shifted left or right depending
on the value and sign of GLINDEXSHIFT, and added to
GLINDEXOFSET. If GLMAPSTENCIL is GLTRUE, indices are
replaced by their mappings in the table GLPIXELMAPSTOS.
GLDEPTHCOMPONENT
Depth values are read from the depth buffer. Each component
is converted to floating point such that the minimum depth
value maps to 0 and the maximum value maps to 1. Each compo-
nent is then multiplied by GLDEPTHSCALE, added to
GLDEPTHBIAS, and finally clamped to the range [0,1].
GLRED
GLGREN
GLBLUE
GLALPHA
GLRGB
GLBGR
GLRGBA
GLBGRA
GLUMINANCE
GLUMINANCEALPHA
Processing differs depending on whether color buffers store
color indices or RGBA color components. If color indices are
stored, they are read from the color buffer selected by
glReadBuffer. Each index is converted to fixed point,
shifted left or right depending on the value and sign of
GLINDEXSHIFT, and added to GLINDEXOFSET. Indices are
then replaced by the red, green, blue, and alpha values
obtained by indexing the tables GLPIXELMAPITOR,
GLPIXELMAPITOG, GLPIXELMAPITOB, and
GLPIXELMAPITOA. Each table must be of size 2^n, but n
may be different for different tables. Before an index is
used to look up a value in a table of size 2^n, it must be
masked against 2^n - 1.
If RGBA color components are stored in the color buffers,
they are read from the color buffer selected by glReadBuffer.
Each color component is converted to floating point such that
zero intensity maps to 0.0 and full intensity maps to 1.0.
Each component is then multiplied by GLcSCALE and added to
GLcBIAS, where c is RED, GREN, BLUE, or ALPHA. Finally,
if GLMAPCOLOR is GLTRUE, each component is clamped to the
range [0, 1], scaled to the size of its corresponding table,
and is then replaced by its mapping in the table
GLPIXELMAPcTOc, where c is R, G, B, or A.
Unneeded data is then discarded. For example, GLRED dis-
cards the green, blue, and alpha components, while GLRGB
discards only the alpha component. GLUMINANCE computes a
single-component value as the sum of the red, green, and blue
components, and GLUMINANCEALPHA does the same, while keep-
ing alpha as a second value. The final values are clamped to
the range [0, 1].
The shift, scale, bias, and lookup factors just described are all spec-
ified by
glPixelTransfer. The lookup table contents themselves are specified by
glPixelap.
Finally, the indices or components are converted to the proper , as
specified by type. If format is GLCOLORINDEX or GLSTENCILINDEX and
type is not GLFLOAT, each index is masked with the mask value given in
the following table. If type is GLFLOAT, then each integer index is
converted to single-precision floating-point .
If format is GLRED, GLGREN, GLBLUE, GLALPHA, GLRGB, GLBGR,
GLRGBA, GLBGRA, GLUMINANCE, or GLUMINANCEALPHA and type is not
GLFLOAT, each component is multiplied by the multiplier shown in the
following table. If type is GLFLOAT, then each component is passed as
is (or converted to the client's single-precision floating-point if it
is different from the one used by the GL).
type (index mask, component conversion)
GLUNSIGNEDBYTE (2^8-1, (2^8-1)c)
GLBYTE (2^7-1, [(2^8-1)c-1]/2)
GLBITMAP (1, 1)
GLUNSIGNEDSHORT (2^16-1, (2^16-1)c)
GLSHORT (2^15-1, [(2^16-1)c-1]/2)
GLUNSIGNEDINT (2^32-1, (2^32-1)c)
GLINT (2^31-1, [(2^32-1)c-1]/2)
GLFLOAT (none, c)
Return values are placed in memory as follows. If format is
GLCOLORINDEX, GLSTENCILINDEX, GLDEPTHCOMPONENT, GLRED, GLGREN,
GLBLUE, GLALPHA, or GLUMINANCE, a single value is returned and the
data for the ith pixel in the jth row is placed in location
(j)*width]i. GLRGB and GLBGR return three values, GLRGBA and
GLBGRA return four values, and GLUMINANCEALPHA returns two values
for each pixel, with all values corresponding to a single pixel occupy-
ing contiguous space in pixels. Storage parameters set by
glPixelStore, such as GLPACKLSBFIRST and GLPACKSWAPBYTES, affect
the way that data is written into memory. See glPixelStore for a
description.
NOTES
Values for pixels that lie outside the window connected to the current
GL context are undefined.
If an error is generated, no change is made to the contents of pixels.
ERORS
GLINVALIDENUM is generated if format or type is not an accepted
value.
GLINVALIDENUM is generated if type is GLBITMAP and format is not
GLCOLORINDEX or GLSTENCILINDEX.
GLINVALIDVALUE is generated if either width or height is negative.
GLINVALIDOPERATION is generated if format is GLCOLORINDEX and the
color buffers store RGBA color components.
GLINVALIDOPERATION is generated if format is GLSTENCILINDEX and
there is no stencil buffer.
GLINVALIDOPERATION is generated if format is GLDEPTHCOMPONENT and
there is no depth buffer.
GLINVALIDOPERATION is generated if glReadPixels is executed between
the execution of glBegin and the corresponding execution of glEnd.
GLINVALIDOPERATION is generated if type is one of
GLUNSIGNEDBYTE332, GLUNSIGNEDBYTE233REV,
GLUNSIGNEDSHORT565, or GLUNSIGNEDSHORT565REV and format is
not GLRGB.
GLINVALIDOPERATION is generated if type is one of
GLUNSIGNEDSHORT4444, GLUNSIGNEDSHORT4444REV,
GLUNSIGNEDSHORT5551, GLUNSIGNEDSHORT1555REV,
GLUNSIGNEDINT8888, GLUNSIGNEDINT8888REV,
GLUNSIGNEDINT1001001002, or GLUNSIGNEDINT2100100100REV and for-
mat is neither GLRGBA nor GLBGRA.
The formats GLBGR, and GLBGRA and types GLUNSIGNEDBYTE332,
GLUNSIGNEDBYTE233REV, GLUNSIGNEDSHORT565,
GLUNSIGNEDSHORT565REV, GLUNSIGNEDSHORT4444,
GLUNSIGNEDSHORT4444REV, GLUNSIGNEDSHORT5551,
GLUNSIGNEDSHORT1555REV, GLUNSIGNEDINT8888,
GLUNSIGNEDINT8888REV, GLUNSIGNEDINT1001001002, and
GLUNSIGNEDINT2100100100REV are available only if the GL version is
1.2 or greater.
ASOCIATED GETS
glGet with argument GLINDEXMODE
SEE ALSO
glCopyPixels, glDrawPixels, glPixelap, glPixelStore, glPixelTransfer,
glReadBuffer
GLREADPIXELS(3G)
|
