void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, GLvoid *pixels)
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 | The format of the returned pixel data. The allowable values are GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_ARGB_I3D, GL_422_EXT, GL_422_REV_EXT, GL_422_AVERAGE_EXT, and GL_422_REV_AVERAGE_EXT. |
type | Specifies the data type for pixel data. The allowable values are GL_BITMAP, GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2_EXT, GL_UNSIGNED_BYTE_2_3_3_REV_EXT, GL_UNSIGNED_SHORT_5_6_5_EXT, GL_UNSIGNED_SHORT_5_6_5_REV_EXT, GL_UNSIGNED_SHORT_4_4_4_4_EXT, GL_UNSIGNED_SHORT_4_4_4_4_REV_EXT, GL_UNSIGNED_SHORT_5_5_5_1_EXT, GL_UNSIGNED_SHORT_1_5_5_5_REV_EXT, GL_UNSIGNED_INT_8_8_8_8_EXT, GL_UNSIGNED_INT_8_8_8_8_REV_EXT, GL_UNSIGNED_INT_10_10_10_2_EXT, and GL_UNSIGNED_INT_2_10_10_10_REV_EXT. |
pixels | Returns the pixel data. |
glReadPixels returns values from each pixel with lower left
corner at
If GL_INTERLACE_READ_I3D is enabled, every other row is read. The
jth row is read from the window coordinate
The format parameter specifies the format for the returned pixel values; accepted values are:
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.
If GL_MAP_COLOR is true, each color component is
clamped to the range
If GL_COLOR_TABLE_EXT is true, each color component is
clamped to the range
If GL_CONVOLUTION_2D_EXT or GL_SEPARABLE_2D_EXT is true, two-dimensional convolution will be performed on each color component according to the format of the convolution filter (see glConvolutionFilter2DEXT and glSeparableFilter2DEXT).
If GL_POST_CONVOLUTION_COLOR_TABLE_EXT is true, each color component is
clamped to the range
Each color is then transformed by the color matrix (see glMatrixMode).
If GL_POST_COLOR_MATRIX_COLOR_TABLE_EXT is true, each color component is
clamped to the range
Each color is then clamped to the color clamp values (see glPixelTransfer).
Unneeded data is then discarded. For example,
GL_RED discards the green, blue, and alpha
components, while GL_RGB discards only the alpha
component. GL_LUMINANCE computes a single-
component 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
Finally, the indices or components are converted to the proper format, as specified by type. If format is GL_COLOR_INDEX or GL_STENCIL_INDEX and type is not GL_FLOAT, each index is masked with the mask value given in the following table. If type is GL_FLOAT, then each integer index is converted to single-precision floating-point format.
If format is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_ARGB_I3D, GL_422_EXT, GL_422_REV_EXT, GL_422_AVERAGE_EXT, or GL_422_REV_AVERAGE_EXT, and type is not GL_FLOAT, each component is multiplied by the multiplier shown in the following table. If type is GL_FLOAT, 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). For the packed pixel formats, N is the number of bits in each component.
type | Index Mask | Component Conversion |
---|---|---|
GL_UNSIGNED_BYTE | 28 - 1 | (28 - 1) c |
GL_BYTE | 27 - 1 | [(28 - 1) c - 1] / 2 |
GL_BITMAP | 1 | 1 |
GL_UNSIGNED_SHORT | 216 - 1 | (216 - 1) c |
GL_SHORT | 215 - 1 | [(216 - 1) c - 1] / 2 |
GL_UNSIGNED_INT | 232 - 1 | (232 - 1) c |
GL_INT | 231 - 1 | [(232 - 1) c - 1] / 2 |
GL_FLOAT | none | c |
GL_UNSIGNED_BYTE_3_3_2_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_BYTE_2_3_3_REV_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_5_6_5_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_5_6_5_REV_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_4_4_4_4_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_4_4_4_4_REV_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_5_5_5_1_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_SHORT_1_5_5_5_REV_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_INT_8_8_8_8_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_INT_8_8_8_8_REV_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_INT_10_10_10_2_EXT | 2N - 1 | (2N - 1) c |
GL_UNSIGNED_INT_2_10_10_10_REV_EXT | 2N - 1 | (2N - 1) c |
Return values are placed in memory as follows. If format is
GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT,
GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, or GL_LUMINANCE, a
single value is returned and the data for the ith pixel in
the jth row is placed in location
If format is GL_422_EXT, GL_422_REV_EXT, GL_422_AVERAGE_EXT, or GL_422_REV_AVERAGE_EXT, the RGBA components are converted to a 422 format and stored as two values for each pixel. For GL_422_EXT and GL_422_REV_EXT, the red component is assigned to luminance for each pixel, and the green and blue components alternate as chrominance. For GL_422_AVERAGE_EXT and GL_422_AVERAGE_REV_EXT, the red component is assigned to luminance for the even and odd pixels, the chrominance for even pixel is the average of the even pixel's green component and the odd pixel's green component, and the chrominance for the odd pixel is the average of the even pixel's blue component and the odd pixel's blue component.
All values corresponding to a single pixel occupy contiguous space in pixels. Storage parameters set by glPixelStore, such as GL_PACK_LSB_FIRST and GL_PACK_SWAP_BYTES, affect the way that data is written into memory. See glPixelStore for a description.
If an error is generated, no change is made to the contents of pixels.
GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX or GL_STENCIL_INDEX.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if format is GL_COLOR_INDEX and the color buffers store RGBA color components.
GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and there is no stencil buffer.
GL_INVALID_OPERATION is generated if format is GL_DEPTH_COMPONENT and there is no depth buffer.
GL_INVALID_OPERATION is generated if glReadPixels is executed between the execution of glBegin and the corresponding execution of glEnd.