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, heightSpecifies 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.
levelSpecifies 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.
dataSpecifies 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/.