NAME

glReadPixels - read a block of pixels from the frame buffer

C SPECIFICATION

void ggllRReeaaddPPiixxeellss( GLint _x,
                   GLint _y,
                   GLsizei _w_i_d_t_h,
                   GLsizei _h_e_i_g_h_t,
                   GLenum _f_o_r_m_a_t,
                   GLenum _t_y_p_e,
                   GLvoid _*_p_i_x_e_l_s )

delim $$

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.
_w_i_d_t_h, _h_e_i_g_h_t
Specify the dimensions of the pixel rectangle. _w_i_d_t_h and _h_e_i_g_h_t of one correspond to a single pixel.
_f_o_r_m_a_t
Specifies the of the pixel data. The following symbolic values are accepted: GGLL__CCOOLLOORR__IINNDDEEXX, GGLL__SSTTEENNCCIILL__IINNDDEEXX, GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT, GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, GGLL__RRGGBB, GGLL__BBGGRR, GGLL__RRGGBBAA, GGLL__BBGGRRAA, GGLL__LLUUMMIINNAANNCCEE, and GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA.
_t_y_p_e
Specifies the data type of the pixel data. Must be one of GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE, GGLL__BBYYTTEE, GGLL__BBIITTMMAAPP, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT, GGLL__SSHHOORRTT, GGLL__UUNNSSIIGGNNEEDD__IINNTT, GGLL__IINNTT, GGLL__FFLLOOAATT, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, or GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV.
_p_i_x_e_l_s
Returns the pixel data.

DESCRIPTION

ggllRReeaaddPPiixxeellss 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 _p_i_x_e_l_s. Several parameters control the processing of the pixel data before it is placed into client memory. These parameters are set with three commands: ggllPPiixxeellSSttoorree, ggllPPiixxeellTTrraannssffeerr, and ggllPPiixxeellMMaapp. This reference page describes the effects on ggllRReeaaddPPiixxeellss of most, but not all of the parameters specified by these three commands.

When the GGLL__AARRBB__iimmaaggiinngg extension is supported, the pixel data may be processed by additional operations including color table lookup, color matrix transformations, convolutions, histograms and minimum and maximun pixel value computations.

ggllRReeaaddPPiixxeellss returns values from each pixel with lower left corner at (_x + $i$, _y + $j$) for 0 <= $i$ < _w_i_d_t_h and 0 <= $j$ < _h_e_i_g_h_t. This pixel is said to be the $i$th pixel in the $j$th row. Pixels are returned in row order from the lowest to the highest row, left to right in each row.

_f_o_r_m_a_t specifies the for the returned pixel values; accepted values are:

GGLL__CCOOLLOORR__IINNDDEEXX
Color indices are read from the color buffer selected by ggllRReeaaddBBuuffffeerr. Each index is converted to fixed point, shifted left or right depending on the value and sign of GGLL__IINNDDEEXX__SSHHIIFFTT, and added to GGLL__IINNDDEEXX__OOFFFFSSEETT. If GGLL__MMAAPP__CCOOLLOORR is GGLL__TTRRUUEE, indices are replaced by their mappings in the table GGLL__PPIIXXEELL__MMAAPP__II__TTOO__II.
GGLL__SSTTEENNCCIILL__IINNDDEEXX
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 GGLL__IINNDDEEXX__SSHHIIFFTT, and added to GGLL__IINNDDEEXX__OOFFFFSSEETT. If GGLL__MMAAPP__SSTTEENNCCIILL is GGLL__TTRRUUEE, indices are replaced by their mappings in the table GGLL__PPIIXXEELL__MMAAPP__SS__TTOO__SS.
GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT
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 GGLL__DDEEPPTTHH__SSCCAALLEE, added to GGLL__DDEEPPTTHH__BBIIAASS, and finally clamped to the range [0,1].
GGLL__RREEDD
GGLL__GGRREEEENN
GGLL__BBLLUUEE
GGLL__AALLPPHHAA
GGLL__RRGGBB
GGLL__BBGGRR
GGLL__RRGGBBAA
GGLL__BBGGRRAA
GGLL__LLUUMMIINNAANNCCEE
GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA
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 ggllRReeaaddBBuuffffeerr. Each index is converted to fixed point, shifted left or right depending on the value and sign of GGLL__IINNDDEEXX__SSHHIIFFTT, and added to GGLL__IINNDDEEXX__OOFFFFSSEETT. Indices are then replaced by the red, green, blue, and alpha values obtained by indexing the tables GGLL__PPIIXXEELL__MMAAPP__II__TTOO__RR, GGLL__PPIIXXEELL__MMAAPP__II__TTOO__GG, GGLL__PPIIXXEELL__MMAAPP__II__TTOO__BB, and GGLL__PPIIXXEELL__MMAAPP__II__TTOO__AA. Each table must be of size $2 sup 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 sup n$, it must be masked against $2 sup n - 1$.
If RGBA color components are stored in the color buffers,
they are read from the color buffer selected by ggllRReeaaddBBuuffffeerr. 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 GGLL__cc__SSCCAALLEE and added to GGLL__cc__BBIIAASS, where _c is RED, GREEN, BLUE, or ALPHA. Finally, if GGLL__MMAAPP__CCOOLLOORR is GGLL__TTRRUUEE, 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 GGLL__PPIIXXEELL__MMAAPP__cc__TTOO__cc, where _c is R, G, B, or A.
Unneeded data is then discarded.
For example, GGLL__RREEDD discards the green, blue, and alpha components, while GGLL__RRGGBB discards only the alpha component. GGLL__LLUUMMIINNAANNCCEE computes a single-component value as the sum of the red, green, and blue components, and GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA 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
ggllPPiixxeellTTrraannssffeerr. The lookup table contents themselves are specified by ggllPPiixxeellMMaapp.

Finally, the indices or components are converted to the proper , as specified by _t_y_p_e. If _f_o_r_m_a_t is GGLL__CCOOLLOORR__IINNDDEEXX or GGLL__SSTTEENNCCIILL__IINNDDEEXX and _t_y_p_e is not GGLL__FFLLOOAATT, each index is masked with the mask value given in the following table. If _t_y_p_e is GGLL__FFLLOOAATT, then each integer index is converted to single-precision floating-point .

If _f_o_r_m_a_t is GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, GGLL__RRGGBB, GGLL__BBGGRR, GGLL__RRGGBBAA, GGLL__BBGGRRAA, GGLL__LLUUMMIINNAANNCCEE, or GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA and _t_y_p_e is not GGLL__FFLLOOAATT, each component is multiplied by the multiplier shown in the following table. If type is GGLL__FFLLOOAATT, 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).

center tab(:);
l cb cb
l c c.
_
_t_y_p_e:index mask:component conversion
_


GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE:$2"^"8 - 1$:$(2"^"8 - 1) c$ GGLL__BBYYTTEE:$2"^"7 - 1$:$[(2"^"8 - 1) c - 1] / 2$ GGLL__BBIITTMMAAPP:$1$:$1$ GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT:$2"^"16 - 1$:$(2"^"16 - 1) c$ GGLL__SSHHOORRTT:$2"^"15 - 1$:$[(2"^"16 - 1) c - 1] / 2$ GGLL__UUNNSSIIGGNNEEDD__IINNTT:$2"^"32 - 1$:$(2"^"32 - 1) c$ GGLL__IINNTT:$2"^"31 - 1$:$[(2"^"32 - 1) c - 1] / 2$ GGLL__FFLLOOAATT:none:$c$ _

Return values are placed in memory as follows. If _f_o_r_m_a_t is GGLL__CCOOLLOORR__IINNDDEEXX, GGLL__SSTTEENNCCIILL__IINNDDEEXX, GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT, GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, or GGLL__LLUUMMIINNAANNCCEE, a single value is returned and the data for the $i$th pixel in the $j$th row is placed in location $(j)~"width"~+~i$. GGLL__RRGGBB and GGLL__BBGGRR return three values, GGLL__RRGGBBAA and GGLL__BBGGRRAA return four values, and GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA returns two values for each pixel, with all values corresponding to a single pixel occupying contiguous space in _p_i_x_e_l_s. Storage parameters set by ggllPPiixxeellSSttoorree, such as GGLL__PPAACCKK__LLSSBB__FFIIRRSSTT and GGLL__PPAACCKK__SSWWAAPP__BBYYTTEESS, affect the way that data is written into memory. See ggllPPiixxeellSSttoorree 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 _p_i_x_e_l_s.

ERRORS

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _f_o_r_m_a_t or _t_y_p_e is not an accepted value.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_y_p_e is GGLL__BBIITTMMAAPP and _f_o_r_m_a_t is not GGLL__CCOOLLOORR__IINNDDEEXX or GGLL__SSTTEENNCCIILL__IINNDDEEXX.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if either _w_i_d_t_h or _h_e_i_g_h_t is negative.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _f_o_r_m_a_t is GGLL__CCOOLLOORR__IINNDDEEXX and the color buffers store RGBA color components.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _f_o_r_m_a_t is GGLL__SSTTEENNCCIILL__IINNDDEEXX and there is no stencil buffer.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _f_o_r_m_a_t is GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT and there is no depth buffer.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllRReeaaddPPiixxeellss is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _t_y_p_e is one of GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, or GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV and _f_o_r_m_a_t is not GGLL__RRGGBB.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _t_y_p_e is one of GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, or GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV and _f_o_r_m_a_t is neither GGLL__RRGGBBAA nor GGLL__BBGGRRAA.

The formats GGLL__BBGGRR, and GGLL__BBGGRRAA and types GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, and GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV are available only if the GL version is 1.2 or greater.

ASSOCIATED GETS

ggllGGeett with argument GGLL__IINNDDEEXX__MMOODDEE

SEE ALSO

ggllCCooppyyPPiixxeellss((33GG)), ggllDDrraawwPPiixxeellss((33GG)), ggllPPiixxeellMMaapp((33GG)), ggllPPiixxeellSSttoorree((33GG)), ggllPPiixxeellTTrraannssffeerr((33GG)),
ggllRReeaaddBBuuffffeerr((33GG))