[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]
OpenGL 1.2 for AIX: Reference Manual
glReadPixels Subroutine
Purpose
Reads a block of pixels from the frame buffer.
Library
OpenGL C bindings library:
libGL.a
C Syntax
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 1
(one) correspond to a single pixel. |
Format |
Specifies the format of the pixel data. Symbolic constants
GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT,
GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB,
GL_RGBA, GL_BGR, GL_BGRA, GL_ABGR_EXT,
GL_LUMINANCE, GL_LUMINANCE_ALPHA are accepted. |
Type |
Specifies the data type for Pixels. Sybolic 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,
GL_UNSIGNED_INT_2_10_10_10_REV are accepted. |
Pixels |
Returns the pixel data. |
Description
The glReadPixels subroutine returns pixel
data from the frame buffer, starting with the pixel whose lower left corner is
at location (X, Y), and puts it into client memory starting at the
location specified by the Pixels parameter. Several parameters control
the processing of the pixel data before it is placed into client memory. These
parameters are set with three subroutines: glPixelStore,
glPixelTransfer, and glPixelMap. The effects on
glReadPixels of most, but not all, of the parameters specified by these
three subroutines are described here.
The glReadPixels subroutine returns values
from each pixel with the 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.
The Format parameter specifies the format
for the returned pixel values. Accepted values for Format are as
follows:
GL_COLOR_INDEX |
Color indexes are read from the color buffer selected by the
glReadBuffer subroutine. Each index is converted to fixed-point format,
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,
indexes 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 format, 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, indexes 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 format such that the minimum depth value maps to 0.0 and the
maximum value maps to 1.0. Each component is then multiplied by
GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and finally clamped to the
range [0,1]. |
GL_ABGR_EXT |
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 blue component is first, followed by green, followed by
red, followed by alpha;
for GL_ABGR_EXT the order is alpha, blue, green, and then red.
Floating-point values are converted directly to an internal floatingpoint format
with unspecified precision. Signed integer values are mapped linearly to the
internal floating-point format 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 zero 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]. |
GL_RED |
Each pixel is a single red component. This component is converted to the
internal floating-point format in the same way as the red component of an RGBA
pixel is, then it is converted to an RGBA pixel with green and blue set to 0.0,
and alpha set to 1.0. After this conversion, the pixel is treated just 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 format in the same way as the green component of an RGBA
pixel is, then it is converted to an RGBA pixel with red and blue set to 0.0,
and alpha set to 1.0. After this conversion, the pixel is treated just 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 format in the same way as the blue component of an RGBA
pixel is, then it is converted to an RGBA pixel with red and green set to 0.0,
and alpha set to 1.0. After this conversion, the pixel is treated just 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 format in the same way as the alpha component of an RGBA
pixel is, then it is converted to an RGBA pixel with red, green, and blue set to
0.0. After this conversion, the pixel is treated just as if it had been read as
an RGBA pixel. |
GL_RGB |
Each pixel is a three-component group, red first, followed by green,
followed by blue. Each component is converted to the internal floating-point
format in the same way as 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.0. After
this conversion, the pixel is treated just as if it had been read as an RGBA
pixel. |
GL_RGBA |
Each pixel is a four-component group, red first, followed by green, followed
by blue, followed by alpha. Floating-point values are converted directly to an
internal floating-point format with unspecified precision. Signed integer values
are mapped linearly to the internal floating-point format 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 are 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 the 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 resulting RGBA colors are then converted to
fragments by attaching the current raster position z coordinate and
texture coordinates to each pixel, then assigning x and y window
coordinates to the nth fragment such that xn = xr +
n mod Width and 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_BGR |
Each pixel is a three-component group, blue first, followed by green,
followed by red. Each component is converted to the internal floating-point
format in the same way as the blue, green, and red components of an BGRA pixel
are. The color triple is converted to an BGRA pixel with alpha set to 1.0. After
this conversion, the pixel is treated just as if it had been read as an BGRA
pixel. |
GL_BGRA |
Each pixel is a four-component group, blue first, followed by green,
followed by red, followed by alpha. Floating-point values are converted directly
to an internal floating-point format with unspecified precision. Signed integer
values are mapped linearly to the internal floating-point format 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 are 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 BLUE, GREEN, RED, 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 the lookup table
GL_PIXEL_MAP_c_TO_c, then replaced by the value that
it references in that table. c is B, G, R, or
A, respectively.
The resulting BGRA colors are then converted to
fragments by attaching the current raster position z coordinate and
texture coordinates to each pixel, then assigning x and y window
coordinates to the nth fragment such that xn = xr +
n mod Width and 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_LUMINANCE |
Each pixel is a single luminance component. This component is converted to
the internal floating-point format in the same way as the red component of an
RGBA pixel is, then it is converted to an RGBA pixel with red, green, and blue
set to the converted luminance value, and alpha set to 1.0. After this
conversion, the pixel is treated just as if it had been read as an RGBA pixel. |
GL_LUMINANCE_ALPHA |
Processing differs depending on whether color buffers store color indexes
or red, green, blue, alpha (RGBA) color components. If color indexes are stored,
they are read from the color buffer selected by glReadBuffer. Each index
is converted to fixed-point format, shifted left or right depending on the value
and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. Indexes
are then replaced by the RGBA values obtained by indexing 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 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 format 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
GL_RED, GL_GREEN, GL_BLUE, and GL_ALPHA. Each
component is clamped to the range [0,1]. Finally, if GL_MAP_COLOR is
GL_TRUE, each color component c is replaced by its mapping in the
table GL_PIXEL_MAP_c_TO_c, where c again is GL_RED,
GL_GREEN, GL_BLUE, and GL_ALPHA. Each component is scaled
to the size its corresponding table before the lookup is performed.
Finally, unneeded data is 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 shift, scale, bias, and lookup factors
described in the preceding section are all specified by glPixelTransfer.
The lookup table contents themselves are specified by the glPixelMap
subroutine.
The final step involves converting the indexes or
components to the proper format, as specified by the Type parameter. If
the Format parameter 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 the Type parameter is GL_FLOAT,
each integer index is converted to single-precision floating-point format.
If the Format parameter is GL_RED,
GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA,
GL_BGR, GL_BGRA,
GL_ABGR_EXT, GL_LUMINANCE, or GL_LUMINANCE_ALPHA and the
Type parameter is not GL_FLOAT, each component is multiplied by
the multiplier shown in the following table. If Type is GL_FLOAT,
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).
Type |
Index Mask |
Component Conversion |
GL_UNSIGNED_BYTE |
28
-1 |
(28
-1)c |
GL_BYTE |
27
-1 |
[(27
-1)c-1]/2 |
GL_BITMAP |
1 |
1 |
GL_UNSIGNED_SHORT |
216
-1 |
(216
-1)c |
GL_SHORT |
215
-1 |
[(215
-1)c-1]/2 |
GL_UNSIGNED_INT |
232
-1 |
(232
-1)c |
GL_INT |
231
-1 |
[(231
-1)c-1]/2 |
GL_FLOAT |
none |
c |
GL_UNSIGNED_BYTE_3_3_2 |
28
-1 |
(2N
-1)c |
GL_UNSIGNED_BYTE_2_3_3_REV |
28
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_5_6_5 |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_5_6_5_REV |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_4_4_4_4 |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_4_4_4_4_REV |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_5_5_5_1 |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_SHORT_1_5_5_5_REV |
216
-1 |
(2N
-1)c |
GL_UNSIGNED_INT_8_8_8_8 |
232
-1 |
(2N
-1)c |
GL_UNSIGNED_INT_8_8_8_8_REV |
232
-1 |
(2N
-1)c |
GL_UNSIGNED_INT_10_10_10_2 |
232
-1 |
(2N
-1)c |
GL_UNSIGNED_INT_2_10_10_10_REV |
232
-1 |
(2N
-1)c |
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.
Return values are placed in memory as follows. If
the Format parameter 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 (j)
Width + i. GL_RGB
and GL_BGR
return three values, GL_RGBA,
GL_BGRA,
and GL_ABGR_EXT 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 Pixels. Storage parameters set by
glPixelStore, such as GL_PACK_SWAP_BYTES and
GL_PACK_LSB_FIRST, affect the way that data is written into memory. See
the glPixelStore
subroutine
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.
Format of GL_ABGR_EXT is part of the
_extname (EXT_abgr) extension, not part of the core GL command set.
Packed pixel types and BGR/BGRA formats are only supported in OpenGL 1.2 and later.
Error Codes
GL_INVALID_ENUM |
Format or Type is not an accepted value. |
GL_INVALID_VALUE |
Width or Height is negative. |
GL_INVALID_OPERATION |
Format is GL_COLOR_INDEX and the color buffers store RGBA
color components. |
GL_INVALID_OPERATION |
Format is GL_STENCIL_INDEX and there is no stencil
buffer. |
GL_INVALID_OPERATION |
Format is GL_DEPTH_COMPONENT and there is no depth
buffer. |
GL_INVALID_OPERATION |
The glReadPixels subroutine is called between a call to
glBegin and the corresponding call to glEnd. |
Associated Gets
Associated gets for the glReadPixels
subroutine are as follows. (See the
glGet subroutine
for more information.)
glGet with argument
GL_INDEX_MODE.
Files
/usr/include/GL/gl.h |
Contains C language constants, variable type definitions, and ANSI
function prototypes for OpenGL. |
Related Information
The
glBegin or glEnd
subroutine, glCopyPixels
subroutine, glDrawPixels
subroutine, glPixelMap
subroutine, glPixelStore
subroutine,
glPixelTransfer
subroutine, glReadBuffer
subroutine.
OpenGL Overview.
[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]