glReadPixels(3G) OpenGL Reference 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 format of the pixel data. The following symbolic
values are accepted: GLCOLORINDEX, GLSTENCILINDEX,
GLDEPTHCOMPONENT, GLRED, GLGREEN, GLBLUE, GLALPHA, GLRGB,
GLRGBA, GLABGREXT, GLLUMINANCE, GLLUMINANCEALPHA, and
GLYCRCB422SGIX.
type Specifies the data type of the pixel data. Must be one of
GLUNSIGNEDBYTE, GLBYTE, GLBITMAP, GLUNSIGNEDSHORT, GLSHORT,
GLUNSIGNEDINT, GLINT, GLFLOAT, GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, or GLUNSIGNEDINT1010102EXT.
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 the commands glPixelStore, glPixelTransfer, and
glPixelMap. The state for the EXTconvolution, SGIcolormatrix,
EXThistogram, and SGIcolortable extensions (see the reference pages
for glPixelTransfer, glConvolutionFilter2DEXT, glColorTableSGI,
glHistogramEXT, and glMinmaxEXT) also affect the results of glReadPixels.
This reference page describes the effects on glReadPixels of some, but
not all of the parameters specified by these commands.
Page 1
glReadPixels(3G) OpenGL Reference glReadPixels(3G)
glReadPixels returns values from each pixel with lower left-hand 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 format for the returned pixel values. Accepted
values for format are as follows:
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 GLINDEXOFFSET. If GLMAPCOLOR
is GLTRUE, indices are replaced by their mappings 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
GLINDEXOFFSET. 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.0 and the maximum value maps to 1.0. Each component
is then multiplied by GLDEPTHSCALE, added to GLDEPTHBIAS,
and finally clamped to the range [0,1].
GLRED
GLGREEN
GLBLUE
GLALPHA
GLRGB
GLRGBA
GLABGREXT
GLLUMINANCE
GLLUMINANCEALPHA
GLYCRCB422SGIX
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
Page 2
glReadPixels(3G) OpenGL Reference glReadPixels(3G)
glReadBuffer. Each index is converted to fixed point, shifted
left or right depending on the value and sign of
GLINDEXSHIFT, and added to GLINDEXOFFSET. Indices are then
replaced by the red, green, blue, and alpha values obtained by
indexing the GLPIXELMAPITOR, GLPIXELMAPITOG,
GLPIXELMAPITOB, and GLPIXELMAPITOA tables. Each of
n
these tables must be of size 2 , but n may be different for
different tables. Before an index is used to look up a value in
n n
a table of size 2 it must be masked against 2 -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, GREEN, 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 discards
the green, blue, and alpha components, while GLRGB discards
only the alpha component. GLLUMINANCE computes a single
component value as the sum of the red, green, and blue
components, and GLLUMINANCEALPHA does the same, while keeping
alpha as a second value. The final values are clamped to the
range [0,1].
GLYCRCB422SGIX uses the red, green, and blue components to
compute the Cb chroma component, the Cr chroma component, and
two luminance values for each pixel pair. The chroma component
of each even-count group in a row represents the Cb chroma
value for a pixel pair. The chroma component of each odd-count
group in a row represents the Cr chroma value for a pixel pair.
Rows of odd length will produce undefined values for the final
pixel in a row.
The shift, scale, bias, and lookup factors described above are all
specified by glPixelTransfer. The lookup table contents themselves are
specified by glPixelMap.
The final step involves converting the indices or components to the
proper format, 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.
type index mask
______________________________
8
GLUNSIGNEDBYTE 2 -1
Page 3
glReadPixels(3G) OpenGL Reference glReadPixels(3G)
7
GLBYTE 2 -1
GLBITMAP 1
16
GLUNSIGNEDSHORT 2 -1
15
GLSHORT 2 -1
32
GLUNSIGNEDINT 2 -1
31
GLINT 2 -1
If type is GLFLOAT, then each integer index is converted to single-
precision floating-point format.
If format is GLRED, GLGREEN, GLBLUE, GLALPHA, GLRGB, GLRGBA,
GLABGREXT, GLLUMINANCE, or GLLUMINANCEALPHA each component is first
clamped to [0,1]. If type is not GLFLOAT, each component is then
multiplied by the multiplier shown in the following table. Equations
with N as the exponent are performed for each bitfield of the packed data
type, with N set to the number of bits in the bitfield.
type component conversion
_____________________________________________________
8
GLUNSIGNEDBYTE (2 -1)*c
8
GLBYTE [(2 -1)*c-1]/2
GLBITMAP 1
16
GLUNSIGNEDSHORT (2 -1)*c
16
GLSHORT [(2 -1)*c-1]/2
32
GLUNSIGNEDINT (2 -1)*c
32
GLINT [(2 -1)*c-1]/2
N
GLUNSIGNEDBYTE332EXT (2 -1)*c
N
GLUNSIGNEDSHORT4444EXT (2 -1)*c
N
GLUNSIGNEDSHORT5551EXT (2 -1)*c
N
GLUNSIGNEDINT8888EXT (2 -1)*c
N
GLUNSIGNEDINT1010102EXT (2 -1)*c
GLFLOAT c
Page 4
glReadPixels(3G) OpenGL Reference glReadPixels(3G)
If type is GLFLOAT, then each component is passed as is (or converted to
the client's single-precision floating-point format if it is different
from the one used by the GL).
Return values are placed in memory as follows. If format is
GLCOLORINDEX, GLSTENCILINDEX, GLDEPTHCOMPONENT, GLRED, GLGREEN,
GLBLUE, GLALPHA, or GLLUMINANCE, a single value is returned and the
data for the ith pixel in the jth row is placed in location j*width + i.
GLRGB returns three values, GLRGBA and GLABGREXT return four values,
and GLLUMINANCEALPHA returns two values for each pixel, with all values
corresponding to a single pixel occupying contiguous space in pixels.
GLYCRCB422SGIX returns four values for each pixel pair. (If type is a
packed data format then all the elements of each group are stored in a a
single unsigned byte, unsigned short, or unsigned int.) Storage
parameters set by glPixelStore, such as GLPACKSWAPBYTES and
GLPACKLSBFIRST, 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.
If type is set to GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, or GLUNSIGNEDINT1010102EXT and the
EXTpackedpixels extension is not supported then a GLINVALIDENUM error
is generated.
ERRORS
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.
Page 5
glReadPixels(3G) OpenGL Reference glReadPixels(3G)
ASSOCIATED GETS
glGet with argument GLINDEXMODE
MACHINE DEPENDENCIES
RealityEngine, RealityEngine2, and VTX systems do not support convolving
images as they are read from the framebuffer.
The SGIXycrcb extension is supported only on O2 systems. When using
GLYCRCB422SGIX with glReadPixels on O2 systems, an odd integer value
for GLPACKSKIPPIXELS will be set to the next highest even integer
value to preserve color alignment.
On RealityEngine, RealityEngine2, and VTX systems, histogramming and
minmax never sink pixel data that is being read from the framebuffer.
The EXTpackedpixels extension is not supported on RealityEngine,
RealityEngine2, and VTX systems.
The following problems are known to exist on RealityEngine,
RealityEngine2, and VTX systems:
1. It is not possible to read the depth or stencil buffers of
multisample-capable Visuals.
2. Reading the depth-buffer is much slower than reading a color-
buffer.
3. Reading RGBA format data from a color-index window does not work
correctly.
SEE ALSO
glCopyPixels, glDrawPixels, glPixelMap, glPixelStore, glPixelTransfer,
glReadBuffer
Page 6