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