gluBuild2DMipmaps(3gl)

1GLUBUILD2DMIPMAPS(3G)                                    GLUBUILD2DMIPMAPS(3G)
2
3
4

NAME

6       gluBuild2DMipmaps - builds a two-dimensional mipmap
7
8

C SPECIFICATION

10       GLint gluBuild2DMipmaps( GLenum target,
11                                GLint internalFormat,
12                                GLsizei width,
13                                GLsizei height,
14                                GLenum format,
15                                GLenum type,
16                                const void *data )
17
18

PARAMETERS

20       target          Specifies the target texture.  Must be GL_TEXTURE_2D.
21
22       internalFormat  Requests  the  internal  storage  of the texture image.
23                       The most current version of the SGI  implementation  of
24                       GLU does not check this value for validity before pass‐
25                       ing it on to the underlying OpenGL  implementation.   A
26                       value that is not accepted by the OpenGL implementation
27                       will lead to an  OpenGL  error.   The  benefit  of  not
28                       checking  this  value  at  the GLU level is that OpenGL
29                       extensions can add new internal texture formats without
30                       requiring  a revision of the GLU implementation.  Older
31                       implementations of GLU check this value and raise a GLU
32                       error  if it is not 1, 2, 3, or 4 or one of the follow‐
33                       ing symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8,
34                       GL_ALPHA12,  GL_ALPHA16,  GL_LUMINANCE,  GL_LUMINANCE4,
35                       GL_LUMINANCE8,     GL_LUMINANCE12,      GL_LUMINANCE16,
36                       GL_LUMINANCE_ALPHA,               GL_LUMINANCE4_ALPHA4,
37                       GL_LUMINANCE6_ALPHA2,             GL_LUMINANCE8_ALPHA8,
38                       GL_LUMINANCE12_ALPHA4,          GL_LUMINANCE12_ALPHA12,
39                       GL_LUMINANCE16_ALPHA16,  GL_INTENSITY,   GL_INTENSITY4,
40                       GL_INTENSITY8,  GL_INTENSITY12, GL_INTENSITY16, GL_RGB,
41                       GL_R3_G3_B2,  GL_RGB4,  GL_RGB5,   GL_RGB8,   GL_RGB10,
42                       GL_RGB12,   GL_RGB16,   GL_RGBA,   GL_RGBA2,  GL_RGBA4,
43                       GL_RGB5_A1,   GL_RGBA8,   GL_RGB10_A2,   GL_RGBA12   or
44                       GL_RGBA16.
45
46       width, height   Specifies in pixels the width and height, respectively,
47                       of the texture image.
48
49       format          Specifies the  of the  pixel  data.   Must  be  one  of
50                       GL_COLOR_INDEX,  GL_DEPTH_COMPONENT,  GL_RED, GL_GREEN,
51                       GL_BLUE, GL_ALPHA, GL_RGB,  GL_RGBA,  GL_BGR,  GL_BGRA,
52                       GL_LUMINANCE, or GL_LUMINANCE_ALPHA.
53
54       type            Specifies  the  data  type  for  data.   Must be one of
55                       GL_UNSIGNED_BYTE,          GL_BYTE,          GL_BITMAP,
56                       GL_UNSIGNED_SHORT,  GL_SHORT,  GL_UNSIGNED_INT, GL_INT,
57                       GL_FLOAT,                       GL_UNSIGNED_BYTE_3_3_2,
58                       GL_UNSIGNED_BYTE_2_3_3_REV,    GL_UNSIGNED_SHORT_5_6_5,
59                       GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
60                       GL_UNSIGNED_SHORT_4_4_4_4_REV,
61                       GL_UNSIGNED_SHORT_5_5_5_1,
62                       GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
63                       GL_UNSIGNED_INT_8_8_8_8_REV,
64                       GL_UNSIGNED_INT_10_10_10_2,                          or
65                       GL_UNSIGNED_INT_2_10_10_10_REV.
66
67       data            Specifies a pointer to the image data in memory.
68
69
70

DESCRIPTION

72       gluBuild2DMipmaps builds a series of prefiltered  two-dimensional  tex‐
73       ture  maps  of decreasing resolutions called a mipmap. This is used for
74       the antialiasing of texture-mapped primitives.
75
76       A return value of zero indicates success, otherwise a GLU error code is
77       returned (see gluErrorString).
78
79       Initially,  the width and height of data are checked to see if they are
80       a power of 2. If not, a copy of data (not data), is scaled up  or  down
81       to  the  nearest  power  of  2.  This  copy will be used for subsequent
82       mipmapping operations described below. (If width or height  is  exactly
83       between  powers  of  2, then the copy of data will scale upwards.)  For
84       example, if width is 57 and height is 23 then a copy of data will scale
85       up  to  64  in  width  and down to 16 in depth, before mipmapping takes
86       place.
87
88       Then, proxy textures (see glTexImage2D) are used to  determine  if  the
89       implementation  can  fit the requested texture. If not, both dimensions
90       are continually halved until it fits. (If the OpenGL version is ≤  1.0,
91       both  maximum  texture  dimensions are clamped to the value returned by
92       glGetIntegerv with the argument GL_MAX_TEXTURE_SIZE.)
93
94       Next, a series of mipmap levels is built by decimating a copy  of  data
95       in half along both dimensions until size 1×1 is reached. At each level,
96       each texel in the halved mipmap level is an average of the  correspond‐
97       ing four texels in the larger mipmap level. (In the case of rectangular
98       images, the decimation will ultimately reach an N×1 or  1×N  configura‐
99       tion. Here, two texels are averaged instead.)
100
101       glTexImage2D is called to load each of these mipmap levels.  Level 0 is
102       a copy of data.  The highest  level  is  log2(max(width,height)).   For
103       example,  if  width  is  64 and height is 16 and the implementation can
104       store a texture of this size, the following mipmap  levels  are  built:
105       64×16,  32×8, 16×4, 8×2, 4×1, 2×1 and 1×1. These correspond to levels 0
106       through 6, respectively.
107
108       See the glTexImage1D reference page for a description of the acceptable
109       values  for format parameter. See the glDrawPixels reference page for a
110       description of the acceptable values for type parameter.
111

NOTES

113       Note that there is no direct way of querying the  maximum  level.  This
114       can  be derived indirectly via glGetTexLevelParameter. First, query for
115       the width and height actually used at level 0.  (The width  and  height
116       may  not be equal to width and height respectively since proxy textures
117       might have scaled them to fit the implementation.)   Then  the  maximum
118       level can be derived from the formula log2(max(width,height)).
119

NOTES

121       Formats   GL_BGR,   and   GL_BGRA,  and  types  GL_UNSIGNED_BYTE_3_3_2,
122       GL_UNSIGNED_BYTE_2_3_3_REV,                    GL_UNSIGNED_SHORT_5_6_5,
123       GL_UNSIGNED_SHORT_5_6_5_REV,                 GL_UNSIGNED_SHORT_4_4_4_4,
124       GL_UNSIGNED_SHORT_4_4_4_4_REV,               GL_UNSIGNED_SHORT_5_5_5_1,
125       GL_UNSIGNED_SHORT_1_5_5_5_REV,                 GL_UNSIGNED_INT_8_8_8_8,
126       GL_UNSIGNED_INT_8_8_8_8_REV,      GL_UNSIGNED_INT_10_10_10_2,       and
127       GL_UNSIGNED_INT_2_10_10_10_REV  are only available if the GL version is
128       1.2 or greater and if the GLU version is 1.3 or greater.
129

ERRORS

131       GLU_INVALID_VALUE is returned if width, or height is < 1.
132
133       GLU_INVALID_ENUM is returned if internalFormat, format, or type is  not
134       legal.
135
136       GLU_INVALID_OPERATION  is returned if type is GL_UNSIGNED_BYTE_3_3_2 or
137       GL_UNSIGNED_BYTE_2_3_3_REV and format is not GL_RGB.
138
139       GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_SHORT_5_6_5 or
140       GL_UNSIGNED_SHORT_5_6_5_REV and format is not GL_RGB.
141
142       GLU_INVALID_OPERATION  is returned if type is GL_UNSIGNED_SHORT_4_4_4_4
143       or GL_UNSIGNED_SHORT_4_4_4_4_REV and  format  is  neither  GL_RGBA  nor
144       GL_BGRA.
145
146       GLU_INVALID_OPERATION  is returned if type is GL_UNSIGNED_SHORT_5_5_5_1
147       or GL_UNSIGNED_SHORT_1_5_5_5_REV and  format  is  neither  GL_RGBA  nor
148       GL_BGRA.
149
150       GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_INT_8_8_8_8 or
151       GL_UNSIGNED_INT_8_8_8_8_REV and format is neither GL_RGBA nor GL_BGRA.
152
153       GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_INT_10_10_10_2
154       or  GL_UNSIGNED_INT_2_10_10_10_REV  and  format  is neither GL_RGBA nor
155       GL_BGRA.
156