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))