gluBuild2DMipmaps - builds a two-dimensional mipmap
GLint gluBuild2DMipmaps( | GLenum | target, |
GLint | internalFormat, | |
GLsizei | width, | |
GLsizei | height, | |
GLenum | format, | |
GLenum | type, | |
const void* | data) ; |
target
Specifies the target texture. Must be GL_TEXTURE_2D
.
internalFormat
Requests the internal storage format of the texture image. The most
current version of the implementation of GLU ES does not check this
value for validity before passing it on to the underlying OpenGL ES
implementation. A value that is not accepted by the OpenGL ES
implementation will lead to an OpenGL ES error. The benefit of not
checking this value at the GLU ES level is that OpenGL ES extensions can add
new internal texture formats without requiring a revision of the GLU ES
implementation. Older implementations of GLU ES check this value and
raise a GLU ES error if it is not one of the following symbolic constants:
GL_ALPHA
,
GL_LUMINANCE
,
GL_LUMINANCE_ALPHA
,
GL_RGB
or
GL_RGBA
.
width
, height
Specifies in pixels the width and height, respectively, of the texture image.
format
Specifies the format of the pixel data.
Must be one of
GL_ALPHA
,
GL_RGB
,
GL_RGBA
,
GL_LUMINANCE
, or
GL_LUMINANCE_ALPHA
.
type
Specifies the data type for data
.
Must be one of
GL_UNSIGNED_BYTE
,
GL_UNSIGNED_SHORT_5_6_5
,
GL_UNSIGNED_SHORT_4_4_4_4
or
GL_UNSIGNED_SHORT_5_5_5_1
.
data
Specifies a pointer to the image data in memory.
gluBuild2DMipmaps
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 gluErrorString).
Initially, the width
and height
of data
are checked to see if they
are a power of 2. If not, a copy of data
(not data
), is scaled up
or down to the nearest power of 2. This copy will be used for subsequent
mipmapping operations described below. (If width
or height
is exactly
between powers of 2, then the copy of data
will scale upwards.) For
example, if width
is 57 and height
is 23, then a copy of data
will
scale up to 64 in width
and down to 16 in depth, before mipmapping takes
place.
Next, a series of mipmap levels is built by decimating a copy of data
in half along both dimensions until size 1 x 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 x 1 or 1 x N configuration. Here, two texels are averaged instead.)
glTexImage2D
is called to load each of these mipmap levels.
Level 0 is a copy of data
. The highest level is log2(max(width, height) * 2^level).
For example, if width
is 64 and height
is 16
and the implementation can store a texture of this size, the following mipmap levels are built: 64 x 16, 32 x 8, 16 x 4, 8 x 2, 4 x 1, 2 x 1, 1 x 1.
These correspond to levels 0 through 6, respectively.
See the glTexImage2D
reference page for a description of the
acceptable values for format
parameter.
Note that there is no direct way of querying the maximum level. First, query for the width and height actually used at level 0. Then the maximum level can be derived from the formula log2(max(width, height) * 2^level).
GLU_INVALID_VALUE
is returned if width
or height
is < 1.
GLU_INVALID_ENUM
is returned if internalFormat
, format
, or type
is not
legal.
GLU_INVALID_OPERATION
is returned if type
is GL_UNSIGNED_SHORT_5_6_5
and format
is not GL_RGB
.
GLU_INVALID_OPERATION
is returned if type
is GL_UNSIGNED_SHORT_4_4_4_4
and format
is not GL_RGBA
.
GLU_INVALID_OPERATION
is returned if type
is GL_UNSIGNED_SHORT_5_5_5_1
and format
is not GL_RGBA
.
Copyright c 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.