Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

GLUBUILD2DMIPMAPS(3G)                                                                  GLUBUILD2DMIPMAPS(3G)



NAME
       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.  The most current version
                       of the SGI implementation of GLU does not check this value for validity before  pass-ing passing
                       ing  it  on to the underlying OpenGL implementation.  A value that is not accepted by
                       the OpenGL implementation will lead to an OpenGL error.  The benefit of not  checking
                       this  value  at  the GLU level is that OpenGL extensions can add new internal texture
                       formats without requiring a revision of the GLU  implementation.   Older  implementa-tions implementations
                       tions of GLU check this value and raise a GLU error if it is not 1, 2, 3, or 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,      GL_UNSIGNED_BYTE_2_3_3_REV,     GL_UNSIGNED_SHORT_5_6_5,
                       GL_UNSIGNED_SHORT_5_6_5_REV,                               GL_UNSIGNED_SHORT_4_4_4_4,
                       GL_UNSIGNED_SHORT_4_4_4_4_REV,                             GL_UNSIGNED_SHORT_5_5_5_1,
                       GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,  GL_UNSIGNED_INT_8_8_8_8_REV,
                       GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV.

       data            Specifies a pointer to the image data in memory.



DESCRIPTION
       gluBuild2DMipmaps  builds  a series of prefiltered two-dimensional texture maps of decreasing resolu-tions resolutions
       tions 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 subse-quent subsequent
       quent mipmapping operations 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 determine if the implementation can fit the
       requested texture. If not, both dimensions are continually halved until it fits. (If the OpenGL  ver-sion version
       sion  is  <=  1.0, both maximum texture 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 decima-
       tion will ultimately reach an Nx1 or 1xN configuration. Here, two texels are averaged instead.)

       glTexImage2D  is called to load each of these mipmap levels.  Level 0 is a copy of data.  The highest
       level is {log sub 2} ( 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 level. This can be derived indirectly via
       glGetTexLevelParameter. First, query for the width and height actually used at level 0.   (The  width
       and  height  may not be equal to width and height respectively since proxy textures might have scaled
       them to fit the implementation.)  Then the maximum level can be derived from the  formula  log2(  max
       (width,height)).

NOTES
       Formats   GL_BGR,   and   GL_BGRA,   and  types  GL_UNSIGNED_BYTE_3_3_2,  GL_UNSIGNED_BYTE_2_3_3_REV,
       GL_UNSIGNED_SHORT_5_6_5,           GL_UNSIGNED_SHORT_5_6_5_REV,            GL_UNSIGNED_SHORT_4_4_4_4,
       GL_UNSIGNED_SHORT_4_4_4_4_REV,        GL_UNSIGNED_SHORT_5_5_5_1,       GL_UNSIGNED_SHORT_1_5_5_5_REV,
       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(3G),  glTexImage1D(3G),  glTexImage2D(3G),   glTexImage3D(3G),   gluBuild1DMipmaps(3G),   gluBuild3DMipmaps(3G),
       gluErrorString(3G),         glGetTexImage(3G),         glGetTexLevelParameter(3G),        gluBuild1DMipmapLevels(3G),
       gluBuild2DMipmapLevels(3G), gluBuild3DMipmapLevels(3G)




                                                                                       GLUBUILD2DMIPMAPS(3G)