NAME

gluBuild1DMipmaps - builds a one-dimensional mipmap

C SPECIFICATION

GLint gglluuBBuuiilldd11DDMMiippmmaappss( 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,
                         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__11DD.
_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
Specifies the width, in pixels, 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, 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

gglluuBBuuiilldd11DDMMiippmmaappss builds a series of prefiltered one-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 of _d_a_t_a is checked to see if it is a power of 2. If not, a copy of _d_a_t_a is scaled up or down to the nearest power of 2. (If _w_i_d_t_h is exactly between powers of 2, then the copy of _d_a_t_a will scale upwards.) This copy will be used for subsequent mipmapping operations described below. For example, if _w_i_d_t_h is 57 then a copy of _d_a_t_a will scale up to 64 before mipmapping takes place.

Then, proxy textures (see ggllTTeexxIImmaaggee11DD) are used to determine if the implementation can fit the requested texture. If not, _w_i_d_t_h is continually halved until it fits.

Next, a series of mipmap levels is built by decimating a copy of _d_a_t_a in half until size $1 ~times~ 1$ is reached. At each level, each texel in the halved mipmap level is an average of the corresponding two texels in the larger mipmap level.

ggllTTeexxIImmaaggee11DD 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}(_w_i_d_t_h)$. For example, if _w_i_d_t_h is 64 and the implementation can store a texture of this size, the following mipmap levels are built: $64 ~times~ 1$, $32 ~times~ 1$, $16 ~times~ 1$, $8 ~times~ 1$, $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 the _t_y_p_e parameter. See the ggllDDrraawwPPiixxeellss reference page for a description of the acceptable values for the _d_a_t_a 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 actually used at level 0. (The width may not be equal to _w_i_d_t_h since proxy textures might have scaled it to fit the implementation.) Then the maximum level can be derived from the formula ${log sub 2}(_w_i_d_t_h)$.

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 is < 1.

GGLLUU__IINNVVAALLIIDD__EENNUUMM is returned if _f_o_r_m_a_t or _t_y_p_e are 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)), gglluuBBuuiilldd22DDMMiippmmaappss((33GG)), gglluuBBuuiilldd33DDMMiippmmaappss((33GG)), gglluuEErrrroorrSSttrriinngg((33GG)), ggllGGeettTTeexxIImmaaggee((33GG)), ggllGGeettTTeexxLLeevveellPPaarraammeetteerr((33GG)), gglluuBBuuiilldd11DDMMiippmmaappLLeevveellss((33GG)), gglluuBBuuiilldd22DDMMiippmmaappLLeevveellss((33GG)), gglluuBBuuiilldd33DDMMiippmmaappLLeevveellss((33GG))