gluBuild1DMipmaps

gluBuild1DMipmaps: create 1D mipmaps.

C Specification

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

Parameters

target: Specifies the target texture. Must be GL_TEXTURE_1D.
component: Specifies the number of color components in the texture. Must be 1, 2, 3, or 4.
width: Specifies the width 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

gluBuild1DMipmaps builds a series of prefiltered 1D 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).

gluBuild1DMipmaps first checks whether the width of data is a power of 2. If not, it scales a copy of data (up or down) to the nearest power of two. This copy is used as the base for subsequent mipmapping operations. For example, if width is 57, a copy of data scales up to 64 before mipmapping takes place. (If width is exactly between powers of 2, the copy of data is scaled upward.)

If the GL version is 1.1 or greater, gluBuild1DMipmaps uses proxy textures (see glTexImage1D) to determine if the implementation can store the requested texture in texture memory. If there isn't enough room, width is halved (and halved again) until it fits.

Next, gluBuild1DMipmaps builds a series of mipmap levels; it halves a copy of data (or a scaled version of data, if necessary) until size 1 is reached. At each level, each texel in the halved image is an average of the corresponding two texels in the larger image.

glTexImage1D is called to load each of these images by level. If width is a power of 2 which fits in the implementation, level 0 is a copy of data, and the highest level is log₂ width. For example, if width is 64 the following images are built: 641, 321, 161, 81, 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 actually used at level 0. (The width may be unequal to width since gluBuild1DMipmaps might have shrunk or expanded width if width isn't a power of 2 or if the implementation only supports smaller textures. The maximum level can then be derived using the formula log₂ width.

Errors

GLU_INVALID_VALUE is returned if width is negative.
GLU_INVALID_ENUM is returned if format or type is not one of the accepted values.

Bugs

Passing GL_STENCIL_INDEX or GL_DEPTH_COMPONENT as format will incorrectly return 0 and set the error code to GL_INVALID_ENUM. It should return GLU_INVALID_ENUM and not set an error code.