239 lines
8.4 KiB
Plaintext
239 lines
8.4 KiB
Plaintext
|
'\" e
|
||
|
|
'\"! eqn | mmdoc
|
||
|
|
'\"macro stdmacro
|
||
|
|
.ds Vn Version 1.2
|
||
|
|
.ds Dt 6 March 1997
|
||
|
|
.ds Re Release 1.2.0
|
||
|
|
.ds Dp May 02 11:53
|
||
|
|
.ds Dm 37 build3dmi
|
||
|
|
.ds Xs 62292 10 build3dmipmaps.gl
|
||
|
|
.TH GLUBUILD3DMIPMAPS 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "gluBuild3DMipmaps
|
||
|
|
\- builds a three-dimensional mipmap
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
GLint \f3gluBuild3DMipmaps\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3GLint \fPgluBuild3DMipmaps( 'u
|
||
|
|
GLint \fIinternalFormat\fP,
|
||
|
|
GLsizei \fIwidth\fP,
|
||
|
|
GLsizei \fIheight\fP,
|
||
|
|
GLsizei \fIdepth\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_3D\fP.
|
||
|
|
.TP
|
||
|
|
\f2internalFormat\fP
|
||
|
|
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:
|
||
|
|
\%\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, \f2height\fP, \f2depth\fP
|
||
|
|
Specifies in pixels the width, height and depth respectively, in pixels
|
||
|
|
of the texture image.
|
||
|
|
.TP
|
||
|
|
\f2format\fP
|
||
|
|
Specifies the of the pixel data.
|
||
|
|
Must be one of
|
||
|
|
\%\f3GL_COLOR_INDEX\fP,
|
||
|
|
\%\f3GL_DEPTH_COMPONENT\fP,
|
||
|
|
\%\f3GL_RED\fP,
|
||
|
|
\%\f3GL_GREEN\fP,
|
||
|
|
\%\f3GL_BLUE\fP,
|
||
|
|
\%\f3GL_ALPHA\fP,
|
||
|
|
\%\f3GL_RGB\fP,
|
||
|
|
\%\f3GL_RGBA\fP,
|
||
|
|
\%\f3GL_BGR\fP,
|
||
|
|
\%\f3GL_BGRA\fP,
|
||
|
|
\%\f3GL_LUMINANCE\fP, or
|
||
|
|
\%\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,
|
||
|
|
\%\f3GL_FLOAT\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, or
|
||
|
|
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP.
|
||
|
|
.TP
|
||
|
|
\f2data\fP
|
||
|
|
Specifies a pointer to the image data in memory.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
\%\f3gluBuild3DMipmaps\fP builds a series of prefiltered three-dimensional texture maps of
|
||
|
|
decreasing resolutions called a mipmap. This is used for the antialiasing of
|
||
|
|
texture-mapped primitives.
|
||
|
|
.P
|
||
|
|
A return value of zero indicates success, otherwise a GLU error code is
|
||
|
|
returned (see \%\f3gluErrorString\fP).
|
||
|
|
.P
|
||
|
|
Initially, the \f2width\fP, \f2height\fP and \f2depth\fP of \f2data\fP are checked to
|
||
|
|
see if they are a power of 2. If not, a copy of \f2data\fP (not \f2data\fP),
|
||
|
|
is scaled up or down to the nearest power of 2. (If \f2width\fP, \f2height\fP or
|
||
|
|
\f2depth\fP is exactly between powers of 2, then the copy of \f2data\fP will
|
||
|
|
scale upwards.) This copy will be used for subsequent mipmapping
|
||
|
|
operations described below. For example, if \f2width\fP is 57, \f2height\fP is
|
||
|
|
23 and \f2depth\fP is 24 then a copy of \f2data\fP will scale up to 64 in
|
||
|
|
width, down to 16 in height and up to 32 in depth, before mipmapping
|
||
|
|
takes place.
|
||
|
|
.P
|
||
|
|
Then, proxy textures (see \f3glTexImage3D\fP) are used to determine if
|
||
|
|
the implementation can fit the requested texture. If not, all three dimensions
|
||
|
|
are continually halved until it fits.
|
||
|
|
.P
|
||
|
|
Next, a series of mipmap levels is built by decimating a copy of \f2data\fP
|
||
|
|
in half along all three dimensions until size $1 ~times~ 1 ~times~ 1$ is
|
||
|
|
reached. At each level, each texel in the halved mipmap level is an
|
||
|
|
average of the corresponding eight texels in the larger mipmap
|
||
|
|
level. (If exactly one of the dimensions is 1, four texels are averaged.
|
||
|
|
If exactly two of the dimensions are 1, two texels are averaged.)
|
||
|
|
.P
|
||
|
|
\f3glTexImage3D\fP is called to load each of these mipmap levels.
|
||
|
|
Level 0 is a copy of \f2data\fP. The highest level is
|
||
|
|
${log sub 2} ( max ("width","height","depth"))$.
|
||
|
|
For example, if \f2width\fP is 64, \f2height\fP is
|
||
|
|
16 and \f2depth\fP is 32, and the implementation can store a texture of this
|
||
|
|
size, the following mipmap levels are built: $64 ~times~ 16 ~times~ 32$,
|
||
|
|
$32 ~times~ 8 ~times~ 16$, $16 ~times~ 4 ~times~ 8$,
|
||
|
|
$8 ~times~ 2 ~times~ 4$, $4 ~times~ 1 ~times~ 2$,
|
||
|
|
$2 ~times~ 1 ~times~ 1$
|
||
|
|
and $1 ~times~ 1 ~times~ 1$. These correspond
|
||
|
|
to levels 0 through 6, respectively.
|
||
|
|
.P
|
||
|
|
See the \f3glTexImage1D\fP reference page for a description of the
|
||
|
|
acceptable values for \f2format\fP parameter. See the \f3glDrawPixels\fP
|
||
|
|
reference page for a description of the acceptable values
|
||
|
|
for \f2type\fP parameter.
|
||
|
|
.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, height and depth actually used at level 0. (The width,
|
||
|
|
height and depth may not be equal to \f2width\fP, \f2height\fP and \f2depth\fP
|
||
|
|
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 ("width","height","depth"))$.
|
||
|
|
.P
|
||
|
|
\%\f3gluBuild3DMipmaps\fP is only available if the GLU version is 1.3 or greater.
|
||
|
|
.P
|
||
|
|
Formats \%\f3GL_BGR\fP, and \%\f3GL_BGRA\fP, and types
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
|
||
|
|
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP are only available if the GL version
|
||
|
|
is 1.2 or greater.
|
||
|
|
.SH ERRORS
|
||
|
|
\%\f3GLU_INVALID_VALUE\fP is returned if \f2width\fP, \f2height\fP, or \f2depth\fP is < 1.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_ENUM\fP is returned if \f2internalFormat\fP, \f2format\fP, or \f2type\fP is not
|
||
|
|
legal.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_BYTE_3_3_2\fP or \%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP
|
||
|
|
and \f2format\fP is not \%\f3GL_RGB\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_6_5\fP or \%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP
|
||
|
|
and \f2format\fP is not \%\f3GL_RGB\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP or \%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP
|
||
|
|
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP or \%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP
|
||
|
|
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_8_8_8_8\fP or \%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP
|
||
|
|
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_10_10_10_2\fP or \%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP
|
||
|
|
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
|
||
|
|
.SH SEE ALSO
|
||
|
|
\f3glDrawPixels(3G)\fP,
|
||
|
|
\f3glTexImage1D(3G)\fP,
|
||
|
|
\f3glTexImage2D(3G)\fP,
|
||
|
|
\f3glTexImage3D(3G)\fP,
|
||
|
|
\%\f3gluBuild1DMipmaps(3G)\fP,
|
||
|
|
\%\f3gluBuild3DMipmaps(3G)\fP,
|
||
|
|
\%\f3gluErrorString(3G)\fP,
|
||
|
|
\f3glGetTexImage(3G)\fP,
|
||
|
|
\f3glGetTexLevelParameter(3G)\fP,
|
||
|
|
\%\f3gluBuild1DMipmapLevels(3G)\fP,
|
||
|
|
\%\f3gluBuild2DMipmapLevels(3G)\fP,
|
||
|
|
\%\f3gluBuild3DMipmapLevels(3G)\fP
|