gluBuild2DMipmaps - builds a two-dimensional mipmap



C SPECIFICATION

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



PARAMETERS

       target          Specifies  the  target  texture.   Must be
                       GL_TEXTURE_2D.

       internalFormat  Requests the internal  storage  format  of
                       the texture image.  Must be 1, 2, 3, 4, or
                       one of the following  symbolic  constants:
                       GL_ALPHA,       GL_ALPHA4,      GL_ALPHA8,
                       GL_ALPHA12,   GL_ALPHA16,    GL_LUMINANCE,
                       GL_LUMINANCE4,              GL_LUMINANCE8,
                       GL_LUMINANCE12,            GL_LUMINANCE16,
                       GL_LUMINANCE_ALPHA,  GL_LUMINANCE4_ALPHA4,
                       GL_LUMINANCE6_ALPHA2,
                       GL_LUMINANCE8_ALPHA8,
                       GL_LUMINANCE12_ALPHA4,
                       GL_LUMINANCE12_ALPHA12,
                       GL_LUMINANCE16_ALPHA16,      GL_INTENSITY,
                       GL_INTENSITY4,              GL_INTENSITY8,
                       GL_INTENSITY12,  GL_INTENSITY16,   GL_RGB,
                       GL_R3_G3_B2,  GL_RGB4,  GL_RGB5,  GL_RGB8,
                       GL_RGB10,  GL_RGB12,  GL_RGB16,   GL_RGBA,
                       GL_RGBA2,  GL_RGBA4, GL_RGB5_A1, GL_RGBA8,
                       GL_RGB10_A2, GL_RGBA12 or GL_RGBA16.

       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_COLOR_INDEX,
                       GL_DEPTH_COMPONENT,    GL_RED,   GL_GREEN,
                       GL_BLUE,   GL_ALPHA,   GL_RGB,    GL_RGBA,
                       GL_BGR,    GL_BGRA,    GL_LUMINANCE,    or
                       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,     GL_FLOAT,
                       GL_UNSIGNED_BYTE_3_3_2,




DESCRIPTION

       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 opera-
       tions 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.

       Then, proxy textures (see glTexImage2D) are used to deter-
       mine  if the implementation can fit the requested texture.
       If not, both dimensions are continually  halved  until  it
       fits.  (If the OpenGL version is <= 1.0, both maximum tex-
       ture dimensions are  clamped  to  the  value  returned  by
       glGetIntegerv with the argument GL_MAX_TEXTURE_SIZE.)

       Next,  a  series of mipmap levels is built by decimating a
       copy of data in half along both dimensions until size  1x1
       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 Nx1 or 1xN
       configuration. Here, two texels are averaged instead.)

       glTexImage2D  is  called to load each of these mipmap lev-
       els.  Level 0 is a copy of data.   The  highest  level  is
       log2(max(width,height)).   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: 64x16,
       32x8, 16x4, 8x2, 4x1, 2x1 and  1x1.  These  correspond  to
       levels 0 through 6, respectively.

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


NOTES

       Note that there is no direct way of querying  the  maximum
       GL_UNSIGNED_INT_8_8_8_8,      GL_UNSIGNED_INT_8_8_8_8_REV,
       GL_UNSIGNED_INT_10_10_10_2,                            and
       GL_UNSIGNED_INT_2_10_10_10_REV are only available  if  the
       GL version is 1.2 or greater and if the GLU version is 1.3
       or greater.


ERRORS

       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_BYTE_3_3_2  or  GL_UNSIGNED_BYTE_2_3_3_REV and
       format is not GL_RGB.

       GLU_INVALID_OPERATION   is    returned    if    type    is
       GL_UNSIGNED_SHORT_5_6_5 or GL_UNSIGNED_SHORT_5_6_5_REV and
       format is not GL_RGB.

       GLU_INVALID_OPERATION   is    returned    if    type    is
       GL_UNSIGNED_SHORT_4_4_4_4 or GL_UNSIGNED_SHORT_4_4_4_4_REV
       and format is neither GL_RGBA nor GL_BGRA.

       GLU_INVALID_OPERATION   is    returned    if    type    is
       GL_UNSIGNED_SHORT_5_5_5_1 or GL_UNSIGNED_SHORT_1_5_5_5_REV
       and format is neither GL_RGBA nor GL_BGRA.

       GLU_INVALID_OPERATION   is    returned    if    type    is
       GL_UNSIGNED_INT_8_8_8_8 or GL_UNSIGNED_INT_8_8_8_8_REV and
       format is neither GL_RGBA nor GL_BGRA.

       GLU_INVALID_OPERATION   is    returned    if    type    is
       GL_UNSIGNED_INT_10_10_10_2                              or
       GL_UNSIGNED_INT_2_10_10_10_REV  and  format   is   neither
       GL_RGBA nor GL_BGRA.


SEE ALSO

       glDrawPixels,  glTexImage1D,  glTexImage2D,  glTexImage3D,
       gluBuild1DMipmaps,   gluBuild3DMipmaps,    gluErrorString,
       glGetTexImage,                     glGetTexLevelParameter,
       gluBuild1DMipmapLevels,            gluBuild2DMipmapLevels,
       gluBuild3DMipmapLevels



                                                                1