- read a block of pixels from the frame buffer
C SPECIFICATION
PARAMETERS
_param1, _param2 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.
_param3, _param4 Specify the dimensions of the pixel rect-
angle. _param3 and _param4 of one corre-
spond to a single pixel.
_param5 Specifies the of the pixel data. The
following symbolic values are accepted:
GL_COLOR_INDEX, GL_STENCIL_INDEX,
GL_DEPTH_COMPONENT, GL_RED, GL_GREEN,
GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR,
GL_RGBA, GL_BGRA, GL_LUMINANCE, and
GL_LUMINANCE_ALPHA.
_param6 Specifies the data type of the pixel
data. Must be one of 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, or
GL_UNSIGNED_INT_2_10_10_10_REV.
_param7 Returns the pixel data.
DESCRIPTION
glReadPixels returns pixel data from the frame buffer,
starting with the pixel whose lower left corner is at
location (_param1, _param2), into client memory starting
at location _param7. Several parameters control the pro-
cessing of the pixel data before it is placed into client
memory. These parameters are set with three commands:
glPixelStore, glPixelTransfer, and glPixelMap. This ref-
erence page describes the effects on glReadPixels of most,
but not all of the parameters specified by these three
commands.
_param5 specifies the for the returned pixel values;
accepted values are:
GL_COLOR_INDEX
Color indices are read from the color buffer
selected by glReadBuffer. Each index is con-
verted to fixed point, shifted left or right
depending on the value and sign of
GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET.
If GL_MAP_COLOR is GL_TRUE, indices are replaced
by their mappings in the table
GL_PIXEL_MAP_I_TO_I.
GL_STENCIL_INDEX
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
GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET.
If GL_MAP_STENCIL is GL_TRUE, indices are
replaced by their mappings in the table
GL_PIXEL_MAP_S_TO_S.
GL_DEPTH_COMPONENT
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 component is
then multiplied by GL_DEPTH_SCALE, added to
GL_DEPTH_BIAS, and finally clamped to the range
[0,1].
GL_RED
GL_GREEN
GL_BLUE
GL_ALPHA
GL_RGB
GL_BGR
GL_RGBA
GL_BGRA
GL_LUMINANCE
GL_LUMINANCE_ALPHA
Processing differs depending on whether color
buffers store color indices or RGBA color compo-
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
GL_c_SCALE and added to GL_c_BIAS, where c is
RED, GREEN, BLUE, or ALPHA. Finally, if
GL_MAP_COLOR is GL_TRUE, 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 GL_PIXEL_MAP_c_TO_c,
where c is R, G, B, or A.
Unneeded data is then discarded. For example,
GL_RED discards the green, blue, and alpha com-
ponents, while GL_RGB discards only the alpha
component. GL_LUMINANCE computes a single-com-
ponent value as the sum of the red, green, and
blue components, and GL_LUMINANCE_ALPHA does the
same, while keeping 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 specified by
glPixelTransfer. The lookup table contents themselves are
specified by glPixelMap.
Finally, the indices or components are converted to the
proper , as specified by _param6. If _param5 is
GL_COLOR_INDEX or GL_STENCIL_INDEX and _param6 is not
GL_FLOAT, each index is masked with the mask value given
in the following table. If _param6 is GL_FLOAT, then each
integer index is converted to single-precision floating-
point .
If _param5 is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, or
GL_LUMINANCE_ALPHA and _param6 is not GL_FLOAT, each com-
ponent is multiplied by the multiplier shown in the fol-
lowing table. If type is GL_FLOAT, then each component is
passed as is (or converted to the client's single-preci-
sion floating-point if it is different from the one used
by the GL).
------------------------------------------------------
_param6 index mask component conversion
------------------------------------------------------
GL_UNSIGNED_BYTE 2^8-1 (2^8-1)c
GL_BYTE 2^7-1 [(2^8-1)c-1]/2
the jth row is placed in location (j)_eqnparam3+i. GL_RGB
and GL_BGR return three values, GL_RGBA and GL_BGRA return
four values, and GL_LUMINANCE_ALPHA returns two values for
each pixel, with all values corresponding to a single
pixel occupying contiguous space in _param7. Storage
parameters set by glPixelStore, such as GL_PACK_LSB_FIRST
and GL_PACK_SWAP_BYTES, affect the way that data is writ-
ten 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 con-
tents of _param7.
ERRORS
GL_INVALID_ENUM is generated if _param5 or _param6 is not
an accepted value.
GL_INVALID_ENUM is generated if _param6 is GL_BITMAP and
_param5 is not GL_COLOR_INDEX or GL_STENCIL_INDEX.
GL_INVALID_VALUE is generated if either _param3 or _param4
is negative.
GL_INVALID_OPERATION is generated if _param5 is
GL_COLOR_INDEX and the color buffers store RGBA color com-
ponents.
GL_INVALID_OPERATION is generated if _param5 is
GL_STENCIL_INDEX and there is no stencil buffer.
GL_INVALID_OPERATION is generated if _param5 is
GL_DEPTH_COMPONENT and there is no depth buffer.
GL_INVALID_OPERATION is generated if glReadPixels is exe-
cuted between the execution of glBegin and the correspond-
ing execution of glEnd.
GL_INVALID_OPERATION is generated if _param6 is one of
GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV
and _param5 is not GL_RGB.
GL_INVALID_OPERATION is generated if _param6 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 _param5 is neither
GL_RGBA nor GL_BGRA.
SEE ALSO
glCopyPixels, glDrawPixels, glPixelMap, glPixelStore,
glPixelTransfer,
glReadBuffer
1