NAME

glGetTexImage - return a texture image

C SPECIFICATION

void ggllGGeettTTeexxIImmaaggee( GLenum _t_a_r_g_e_t,
                    GLint _l_e_v_e_l,
                    GLenum _f_o_r_m_a_t,
                    GLenum _t_y_p_e,
                    GLvoid _*_p_i_x_e_l_s )

delim $$

PARAMETERS

_t_a_r_g_e_t
Specifies which texture is to be obtained. GGLL__TTEEXXTTUURREE__11DD, GGLL__TTEEXXTTUURREE__22DD, and GGLL__TTEEXXTTUURREE__33DD are accepted.
_l_e_v_e_l
Specifies the level-of-detail number of the desired image. Level 0 is the base image level. Level $n$ is the $n$th mipmap reduction image.
_f_o_r_m_a_t
Specifies a pixel for the returned data. The supported formats are 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 a pixel type for the returned data. The supported types are GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE, GGLL__BBYYTTEE, 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, and GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV.
_p_i_x_e_l_s
Returns the texture image. Should be a pointer to an array of the type specified by _t_y_p_e.

DESCRIPTION

ggllGGeettTTeexxIImmaaggee returns a texture image into _p_i_x_e_l_s. _t_a_r_g_e_t specifies whether the desired texture image is one specified by ggllTTeexxIImmaaggee11DD (GGLL__TTEEXXTTUURREE__11DD), ggllTTeexxIImmaaggee22DD (GGLL__TTEEXXTTUURREE__22DD), or ggllTTeexxIImmaaggee33DD (GGLL__TTEEXXTTUURREE__33DD). _l_e_v_e_l specifies the level-of-detail number of the desired image. _f_o_r_m_a_t and _t_y_p_e specify the and type of the desired image array. See the reference pages ggllTTeexxIImmaaggee11DD and ggllDDrraawwPPiixxeellss for a description of the acceptable values for the _f_o_r_m_a_t and _t_y_p_e parameters, respectively.

To understand the operation of ggllGGeettTTeexxIImmaaggee, consider the selected internal four-component texture image to be an RGBA color buffer the size of the image. The semantics of ggllGGeettTTeexxIImmaaggee are then identical to those of ggllRReeaaddPPiixxeellss, with the exception that no pixel transfer operations are performed, when called with the same _f_o_r_m_a_t and _t_y_p_e, with _x and _y set to 0, _w_i_d_t_h set to the width of the texture image (including border if one was specified), and _h_e_i_g_h_t set to 1 for 1D images, or to the height of the texture image (including border if one was specified) for 2D images. Because the internal texture image is an RGBA image, pixel formats GGLL__CCOOLLOORR__IINNDDEEXX, GGLL__SSTTEENNCCIILL__IINNDDEEXX, and GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT are not accepted, and pixel type GGLL__BBIITTMMAAPP is not accepted.

If the selected texture image does not contain four components, the following mappings are applied. Single-component textures are treated as RGBA buffers with red set to the single-component value, green set to 0, blue set to 0, and alpha set to 1. Two-component textures are treated as RGBA buffers with red set to the value of component zero, alpha set to the value of component one, and green and blue set to 0. Finally, three-component textures are treated as RGBA buffers with red set to component zero, green set to component one, blue set to component two, and alpha set to 1.

To determine the required size of _p_i_x_e_l_s, use ggllGGeettTTeexxLLeevveellPPaarraammeetteerr to determine the dimensions of the internal texture image, then scale the required number of pixels by the storage required for each pixel, based on _f_o_r_m_a_t and _t_y_p_e. Be sure to take the pixel storage parameters into account, especially GGLL__PPAACCKK__AALLIIGGNNMMEENNTT.

NOTES

If an error is generated, no change is made to the contents of _p_i_x_e_l_s.

When the GGLL__AARRBB__mmuullttiitteexxttuurree extension is supported, ggllGGeettTTeexxIImmaaggee returns the texture image for the active texture unit.

The 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, GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV, and the formats GGLL__BBGGRR, and GGLL__BBGGRRAA are available only if the GL version is 1.2 or greater.

ERRORS

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

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _l_e_v_e_l is less than 0.

GGLL__IINNVVAALLIIDD__VVAALLUUEE may be generated if _l_e_v_e_l is greater than $log sub 2 max$, where $max$ is the returned value of GGLL__MMAAXX__TTEEXXTTUURREE__SSIIZZEE.

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

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned 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 returned 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 or GGLL__BBGGRRAA.

ASSOCIATED GETS

ggllGGeettTTeexxLLeevveellPPaarraammeetteerr with argument GGLL__TTEEXXTTUURREE__WWIIDDTTHH
ggllGGeettTTeexxLLeevveellPPaarraammeetteerr with argument GGLL__TTEEXXTTUURREE__HHEEIIGGHHTT
ggllGGeettTTeexxLLeevveellPPaarraammeetteerr with argument GGLL__TTEEXXTTUURREE__BBOORRDDEERR
ggllGGeettTTeexxLLeevveellPPaarraammeetteerr with argument GGLL__TTEEXXTTUURREE__IINNTTEERRNNAALLFFOORRMMAATT
ggllGGeett with arguments GGLL__PPAACCKK__AALLIIGGNNMMEENNTT and others

SEE ALSO

ggllAAccttiivveeTTeexxttuurreeAARRBB((33GG)), ggllDDrraawwPPiixxeellss((33GG)), ggllRReeaaddPPiixxeellss((33GG)), ggllTTeexxEEnnvv((33GG)), ggllTTeexxGGeenn((33GG)), ggllTTeexxIImmaaggee11DD((33GG)), ggllTTeexxIImmaaggee22DD((33GG)), ggllTTeexxIImmaaggee33DD((33GG)), ggllTTeexxSSuubbIImmaaggee11DD((33GG)), ggllTTeexxSSuubbIImmaaggee22DD((33GG)), ggllTTeexxSSuubbIImmaaggee33DD((33GG)), ggllTTeexxPPaarraammeetteerr((33GG))