NAME

gluBuild2DMipmaps - builds a two-dimensional mipmap

C SPECIFICATION

GLint gglluuBBuuiilldd22DDMMiippmmaappss( GLenum _t_a_r_g_e_t,
                         GLint _i_n_t_e_r_n_a_l_F_o_r_m_a_t,
                         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,
                         const void _*_d_a_t_a )

delim $$

PARAMETERS

_t_a_r_g_e_t
Specifies the target texture. Must be GGLL__TTEEXXTTUURREE__22DD.
_i_n_t_e_r_n_a_l_F_o_r_m_a_t
Requests the internal storage of the texture image. The most current version of the SGI implementation of GLU does not check this value for validity before passing it on to the underlying OpenGL implementation. A value that is not accepted by the OpenGL implementation will lead to an OpenGL error. The benefit of not checking this value at the GLU level is that OpenGL extensions can add new internal texture formats without requiring a revision of the GLU implementation. Older implementations of GLU check this value and raise a GLU error if it is not 1, 2, 3, or 4 or one of the following symbolic constants: GGLL__AALLPPHHAA, GGLL__AALLPPHHAA44, GGLL__AALLPPHHAA88, GGLL__AALLPPHHAA1122, GGLL__AALLPPHHAA1166, GGLL__LLUUMMIINNAANNCCEE, GGLL__LLUUMMIINNAANNCCEE44, GGLL__LLUUMMIINNAANNCCEE88, GGLL__LLUUMMIINNAANNCCEE1122, GGLL__LLUUMMIINNAANNCCEE1166, GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA, GGLL__LLUUMMIINNAANNCCEE44__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE66__AALLPPHHAA22, GGLL__LLUUMMIINNAANNCCEE88__AALLPPHHAA88, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA1122, GGLL__LLUUMMIINNAANNCCEE1166__AALLPPHHAA1166, GGLL__IINNTTEENNSSIITTYY, GGLL__IINNTTEENNSSIITTYY44, GGLL__IINNTTEENNSSIITTYY88, GGLL__IINNTTEENNSSIITTYY1122, GGLL__IINNTTEENNSSIITTYY1166, GGLL__RRGGBB, GGLL__RR33__GG33__BB22, GGLL__RRGGBB44, GGLL__RRGGBB55, GGLL__RRGGBB88, GGLL__RRGGBB1100, GGLL__RRGGBB1122, GGLL__RRGGBB1166, GGLL__RRGGBBAA, GGLL__RRGGBBAA22, GGLL__RRGGBBAA44, GGLL__RRGGBB55__AA11, GGLL__RRGGBBAA88, GGLL__RRGGBB1100__AA22, GGLL__RRGGBBAA1122 or GGLL__RRGGBBAA1166.
_w_i_d_t_h, _h_e_i_g_h_t
Specifies in pixels the width and height, respectively, of the texture image.
_f_o_r_m_a_t
Specifies the of the pixel data. Must be one of GGLL__CCOOLLOORR__IINNDDEEXX, GGLL__DDEEPPTTHH__CCOOMMPPOONNEENNTT, GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, GGLL__RRGGBB, GGLL__RRGGBBAA, GGLL__BBGGRR, GGLL__BBGGRRAA, GGLL__LLUUMMIINNAANNCCEE, or GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA.
_t_y_p_e
Specifies the data type for _d_a_t_a. 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.
_d_a_t_a
Specifies a pointer to the image data in memory.

DESCRIPTION

gglluuBBuuiilldd22DDMMiippmmaappss builds a series of prefiltered two-dimensional texture maps of decreasing resolutions called a mipmap. This is used for the antialiasing of texture-mapped primitives.

A return value of zero indicates success, otherwise a GLU error code is returned (see gglluuEErrrroorrSSttrriinngg).

Initially, the _w_i_d_t_h and _h_e_i_g_h_t of _d_a_t_a are checked to see if they are a power of 2. If not, a copy of _d_a_t_a (not _d_a_t_a), is scaled up or down to the nearest power of 2. This copy will be used for subsequent mipmapping operations described below. (If _w_i_d_t_h or _h_e_i_g_h_t is exactly between powers of 2, then the copy of _d_a_t_a will scale upwards.) For example, if _w_i_d_t_h is 57 and _h_e_i_g_h_t is 23 then a copy of _d_a_t_a will scale up to 64 in _w_i_d_t_h and down to 16 in depth, before mipmapping takes place.

Then, proxy textures (see ggllTTeexxIImmaaggee22DD) are used to determine if the implementation can fit the requested texture. If not, both dimensions are continually halved until it fits. (If the OpenGL version is <= 1.0, both maximum texture dimensions are clamped to the value returned by ggllGGeettIInntteeggeerrvv with the argument GGLL__MMAAXX__TTEEXXTTUURREE__SSIIZZEE.)

Next, a series of mipmap levels is built by decimating a copy of _d_a_t_a in half along both dimensions until size $1 ~times~ 1$ is reached. At each level, each texel in the halved mipmap level is an average of the corresponding four texels in the larger mipmap level. (In the case of rectangular images, the decimation will ultimately reach an $N ~times~ 1$ or $1 ~times~ N$ configuration. Here, two texels are averaged instead.)

ggllTTeexxIImmaaggee22DD is called to load each of these mipmap levels. Level 0 is a copy of _d_a_t_a. The highest level is ${log sub 2} ( max ("width","height"))$. For example, if _w_i_d_t_h is 64 and _h_e_i_g_h_t is 16 and the implementation can store a texture of this size, the following mipmap levels are built: $64 ~times~ 16$, $32 ~times~ 8$, $16 ~times~ 4$, $8 ~times~ 2$, $4 ~times~ 1$, $2 ~times~ 1$ and $1 ~times~ 1$. These correspond to levels 0 through 6, respectively.

See the ggllTTeexxIImmaaggee11DD reference page for a description of the acceptable values for _f_o_r_m_a_t parameter. See the ggllDDrraawwPPiixxeellss reference page for a description of the acceptable values for _t_y_p_e parameter.

NOTES

Note that there is no direct way of querying the maximum level. This can be derived indirectly via ggllGGeettTTeexxLLeevveellPPaarraammeetteerr. First, query for the width and height actually used at level 0. (The width and height may not be equal to _w_i_d_t_h and _h_e_i_g_h_t respectively since proxy textures might have scaled them to fit the implementation.) Then the maximum level can be derived from the formula ${log sub 2}( max (_w_i_d_t_h,_h_e_i_g_h_t))$.

NOTES

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 only available if the GL version is 1.2 or greater and if the GLU version is 1.3 or greater.

ERRORS

GGLLUU__IINNVVAALLIIDD__VVAALLUUEE is returned if _w_i_d_t_h, or _h_e_i_g_h_t is < 1.

GGLLUU__IINNVVAALLIIDD__EENNUUMM is returned if _i_n_t_e_r_n_a_l_F_o_r_m_a_t, _f_o_r_m_a_t, or _t_y_p_e is not legal.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22 or GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV and _f_o_r_m_a_t is not GGLL__RRGGBB.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is 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.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44 or GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV and _f_o_r_m_a_t is neither GGLL__RRGGBBAA nor GGLL__BBGGRRAA.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11 or GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV and _f_o_r_m_a_t is neither GGLL__RRGGBBAA nor GGLL__BBGGRRAA.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88 or GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV and _f_o_r_m_a_t is neither GGLL__RRGGBBAA nor GGLL__BBGGRRAA.

GGLLUU__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is returned if _t_y_p_e is 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.

SEE ALSO

ggllDDrraawwPPiixxeellss((33GG)), ggllTTeexxIImmaaggee11DD((33GG)), ggllTTeexxIImmaaggee22DD((33GG)), ggllTTeexxIImmaaggee33DD((33GG)), gglluuBBuuiilldd11DDMMiippmmaappss((33GG)), gglluuBBuuiilldd33DDMMiippmmaappss((33GG)), gglluuEErrrroorrSSttrriinngg((33GG)), ggllGGeettTTeexxIImmaaggee((33GG)), ggllGGeettTTeexxLLeevveellPPaarraammeetteerr((33GG)), gglluuBBuuiilldd11DDMMiippmmaappLLeevveellss((33GG)), gglluuBBuuiilldd22DDMMiippmmaappLLeevveellss((33GG)), gglluuBBuuiilldd33DDMMiippmmaappLLeevveellss((33GG))