'\"! eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 6 March 1997
.ds Re Release 1.2.0
.ds Dp Mar 17 18:18
.ds Dm  Mar  7 03:1
.ds Xs 25518 9 build1dmipmaps.gl
.TH GLUBUILD1DMIPMAPS
.SH NAME
.B "gluBuild1DMipmaps
\- builds a 1-D mipmap

.SH C SPECIFICATION
GLint \f3gluBuild1DMipmaps\fP(
GLenum \fItarget\fP,
.nf
.ta \w'\f3GLint \fPgluBuild1DMipmaps( 'u
	GLint \fIinternalFormat\fP,
	GLsizei \fIwidth\fP,
	GLenum \fIformat\fP,
	GLenum \fItype\fP,
	const void \fI*data\fP )
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIinternalFormat\fP\ \ 'u 
\f2target\fP
Specifies the target texture. Must be \f3GL_TEXTURE_1D\fP.
.TP
\f2internalFormat\fP
Requests the internal storage format of the texture image.
Must be 1, 2, 3, or 4 or one of the following symbolic constants:
\f3GL_ALPHA\fP,
\f3GL_ALPHA4\fP,
\f3GL_ALPHA8\fP,
\f3GL_ALPHA12\fP,
\f3GL_ALPHA16\fP,
\f3GL_LUMINANCE\fP,
\f3GL_LUMINANCE4\fP,
\f3GL_LUMINANCE8\fP,
\f3GL_LUMINANCE12\fP,
\f3GL_LUMINANCE16\fP,
\f3GL_LUMINANCE_ALPHA\fP,
\f3GL_LUMINANCE4_ALPHA4\fP,
\f3GL_LUMINANCE6_ALPHA2\fP,
\f3GL_LUMINANCE8_ALPHA8\fP,
\f3GL_LUMINANCE12_ALPHA4\fP,
\f3GL_LUMINANCE12_ALPHA12\fP,
\f3GL_LUMINANCE16_ALPHA16\fP,
\f3GL_INTENSITY\fP,
\f3GL_INTENSITY4\fP,
\f3GL_INTENSITY8\fP,
\f3GL_INTENSITY12\fP,
\f3GL_INTENSITY16\fP,
\f3GL_RGB\fP,
\f3GL_R3_G3_B2\fP,
\f3GL_RGB4\fP,
\f3GL_RGB5\fP,
\f3GL_RGB8\fP,
\f3GL_RGB10\fP,
\f3GL_RGB12\fP,
\f3GL_RGB16\fP,
\f3GL_RGBA\fP,
\f3GL_RGBA2\fP,
\f3GL_RGBA4\fP,
\f3GL_RGB5_A1\fP,
\f3GL_RGBA8\fP,
\f3GL_RGB10_A2\fP,
\f3GL_RGBA12\fP or
\f3GL_RGBA16\fP.
.TP
\f2width\fP
Specifies the width, in pixels, of the texture image. 
.TP
\f2format\fP
Specifies the format of the pixel data.
Must be one of
\f3GL_COLOR_INDEX\fP,
\f3GL_RED\fP,
\f3GL_GREEN\fP,
\f3GL_BLUE\fP,
\f3GL_ALPHA\fP,
\f3GL_RGB\fP,
\f3GL_RGBA\fP,
\f3GL_LUMINANCE\fP, and
\f3GL_LUMINANCE_ALPHA\fP.
.TP
\f2type\fP
Specifies the data type for \f2data\fP.
Must be one of \f3GL_UNSIGNED_BYTE\fP,
\f3GL_BYTE\fP,
\f3GL_BITMAP\fP,
\f3GL_UNSIGNED_SHORT\fP,
\f3GL_SHORT\fP,
\f3GL_UNSIGNED_INT\fP,
\f3GL_INT\fP, or
\f3GL_FLOAT\fP.
.TP
\f2data\fP
Specifies a pointer to the image data in memory.
.SH DESCRIPTION
\f3gluBuild1DMipmaps\fP builds a series of prefiltered 1-D texture maps of decreasing
resolutions called a mipmap. This is used for the antialiasing of
texture mapped primitives.
.P
A return value of 0 indicates success, otherwise a GLU error code is
returned (see \f3gluErrorString\fP).
.P
Initially, the \f2width\fP of \f2data\fP is checked to see if it is
a power of two. If not, a copy of \f2data\fP (not \f2data\fP) is scaled up or down to the
nearest power of two. This copy will be used for
subsequent mipmapping operations described below. (If \f2width\fP 
is exactly between powers of 2, then the copy of \f2data\fP will scale upwards.)
For example, if \f2width\fP is 57 then a copy of \f2data\fP
will scale up to 64 before mipmapping
takes place.
.P
Then, proxy textures (see \f3glTexImage1D\fP) are used to determine if
the implementation can fit the requested texture. If not, \f2width\fP is
continually halved until it fits.
.P
Next, a series of mipmap levels is built by decimating a copy of \f2data\fP in half
until size 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.
.P
\f3glTexImage1D\fP is called to load each of these mipmap levels.
Level 0 is a copy of \f2data\fP. 
The highest level is log2(width).
For example, if width is 64 and the implementation can store a texture of
this size, the following mipmap levels are
built: 64x1, 32x1, 16x1, 8x1, 4x1, 2x1 and 1x1. These correspond to 
levels 0 through 6, respectively.
.P
See the \f3glTexImage1D\fP reference page for a description of the
acceptable values for \f2type\fP. See the \f3glDrawPixels\fP 
reference page for a description of the acceptable values 
for \f2data\fP.
.SH NOTES
Note that there is no direct way of querying the maximum level. This can
be derived indirectly via \f3glGetTexLevelParameter\fP. First, query
for the
width actually used at level 0. 
(The width may not be equal to \f2width\fP since
proxy textures might have scaled it to fit the implementation.)
Then the maximum
level can be derived from the formula log2(width).
.SH ERRORS
\f3GLU_INVALID_VALUE\fP is returned if \f2width\fP is < 1.
.P
\f3GLU_INVALID_ENUM\fP is returned if \f2internalFormat\fP, \f2format\fP or \f2type\fP are not legal.
.SH SEE ALSO
\f3glDrawPixels\fP, \f3glTexImage1D\fP, \f3glTexImage2D\fP, 
\f3gluBuild2DMipmaps\fP, 
.br
\f3gluErrorString\fP, \f3gluScaleImage\fP