gluBuild2DMipmapLevels - builds a subset of two-dimensional mipmap levels
GLint gluBuild2DMipmapLevels( | GLenum | target, |
GLint | internalFormat, | |
GLsizei | width, | |
GLsizei | height, | |
GLenum | format, | |
GLenum | type, | |
GLint | level, | |
GLint | base, | |
GLint | max, | |
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 level is that OpenGL ES extensions can add
new internal texture formats without requiring a revision of the GLU
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 the width and height, respectively, in pixels of the texture image. These should be a power of 2.
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
.
level
Specifies the mipmap level of the image data.
base
Specifies the minimum mipmap level to pass to glTexImage2D
.
max
Specifies the maximum mipmap level to pass to glTexImage2D
.
data
Specifies a pointer to the image data in memory.
gluBuild2DMipmapLevels
builds a subset 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).
A series of mipmap levels from base
to max
is built by decimating
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 these mipmap levels from base
to max
. If max
is larger than the highest mipmap level for the
texture of the specified size, then a GLU error code is returned (see
gluErrorString) and nothing is loaded.
For example, if level
is 2 and width
is 16 and height
is 8, the
following levels are possible: 16 x 8, 8 x 4, 4 x 2, 2 x 1, 1 x 1.
These correspond to levels 2 through 6
respectively. If base
is 3 and max
is 5, then only mipmap levels
8 x 4, 4 x 2, and 2 x 1 are loaded. However, if max
is 7, then an error is returned and nothing is loaded since max
is
larger than the highest mipmap level which is, in this case, 6.
The highest mipmap level can be derived from the formula log2(max(width, height) * 2^level).
GLU_INVALID_VALUE
is returned if level
> base
, base
< 0,
max
< base
, or max
is > the highest mipmap level for data
.
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/.