gluBuild2DMipmaps

gluBuild2DMipmaps: create 2D mipmaps.

C Specification

GLint gluBuild2DMipmaps(
    GLenum	target,
    GLint	component,
    GLsizei	width,
    GLsizei	height,
    GLenum	format,
    GLenum	type,
    const void	*data)

Parameters

target: Specifies the target texture. Must be GL_TEXTURE_2D.
component: Specifies the number of color components in the texture. Must be 1, 2, 3, or 4.
width, height: Specifies the width and height, respectively, of the texture image.
format: Specifies the format of the pixel data. Must be one of: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
type: Specifies the data type for data. Must be one of: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.
data: Specifies a pointer to the image data in memory.

Description

gluBuild2DMipmaps builds a series of prefiltered 2D texture maps of decreasing resolution. Mipmaps can be used so that textures don't appear aliased.

A return value of 0 indicates success. Otherwise a GLU error code is returned (see gluErrorString).

gluBuild2DMipmaps first check whether width and height of data are both powers of 2. If not, gluBuild2DMipmaps scales a copy of data up or down to the nearest power of 2. This copy is then used as the base for subsequent mipmapping operations. For example, if width is 57 and height is 23, then a copy of data scales up to 64 and down to 16, respectively, before mipmapping takes place. (If width or height is exactly between powers of 2, the copy of data is scaled upward.)

If the GL version is 1.1 or greater, gluBuild2DMipmaps then uses proxy textures (see glTexImage1D) to determine whether there's enough room for the requested texture in the implementation. If not, width is halved (and halved again) until it fits.

gluBuild2DMipmaps then uses proxy textures (see glTexImage2D) to determine if the implementation can store the requested texture in texture memory. If not, both dimensions are continually halved until it fits.

Next, gluBuild2DMipmaps builds a series of images; it halves a copy of type (or a scaled version of type, if necessary) along both dimensions until size 11 is reached. At each level, each texel in the halved mipmap is an average of the corresponding four texels in the larger mipmap. (In the case of rectangular images, halving the images repeatedly eventually results in an n1 or 1n configuration. Here, two texels are averaged instead.)

glTexImage2D is called to load each of these images by level. If width and height are both powers of 2 which fit in the implementation, level 0 is a copy of data, and the highest level is log₂(max(width, height)). For example, if width is 64 and height is 16, the following mipmaps are built: 6416, 328, 164, 82, 41, 21 and 11. These correspond to levels 0 through 6, respectively.

See the glTexImage1D reference page for a description of the acceptable values for format. See the glDrawPixels reference page for a description of the acceptable values for type.

Notes

While you can't query the maximum level directly, you can derive it indirectly by calling glGetTexLevelParameter. First, query for the width and height actually used at level 0. (The width and height may be unequal to width and height since proxy textures might have shrunk or expanded them if width or height are not powers of 2 or if the implemetation only supports smaller textures.) The maximum level can then be derived using the formula log₂(max(width, height)).

Errors