← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/vnc4/gutsy

« back to all changes in this revision

Viewing changes to unix/xc/doc/man/GLU/build3dmipmaplevels.3gl

  • Committer: Bazaar Package Importer
  • Author(s): Ola Lundqvist
  • Date: 2006-05-15 20:35:17 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060515203517-l4lre1ku942mn26k
Tags: 4.1.1+X4.3.0-10
* Correction of critical security issue. Thanks to Martin Kogler
  <e9925248@student.tuwien.ac.at> that informed me about the issue,
  and provided the patch.
  This flaw was originally found by Steve Wiseman of intelliadmin.com.
* Applied patch from Javier Kohen <jkohen@users.sourceforge.net> that
  inform the user that only 8 first characters of the password will
  actually be used when typing more than 8 characters, closes:
  #355619.

Show diffs side-by-side

added added

removed removed

Lines of Context:
unix/xc/doc/man/GLU/build3dmipmaplevels.3gl
 
1
'\" e
 
2
'\"! eqn | mmdoc
 
3
'\"macro stdmacro
 
4
.ds Vn Version 1.2
 
5
.ds Dt 6 March 1997
 
6
.ds Re Release 1.2.0
 
7
.ds Dp May 02 11:53
 
8
.ds Dm 37 build3dmi
 
9
.ds Xs 53966 9 build3dmipmaplevels.gl
 
10
.TH GLUBUILD3DMIPMAPLEVELS 3G
 
11
.SH NAME
 
12
.B "gluBuild3DMipmapLevels
 
13
\- builds a subset of three-dimensional mipmap levels
 
14
 
 
15
.SH C SPECIFICATION
 
16
GLint \f3gluBuild3DMipmapLevels\fP(
 
17
GLenum \fItarget\fP,
 
18
.nf
 
19
.ta \w'\f3GLint \fPgluBuild3DMipmapLevels( 'u
 
20
        GLint \fIinternalFormat\fP,
 
21
        GLsizei \fIwidth\fP,
 
22
        GLsizei \fIheight\fP,
 
23
        GLsizei \fIdepth\fP,
 
24
        GLenum \fIformat\fP,
 
25
        GLenum \fItype\fP,
 
26
        GLint \fIlevel\fP,
 
27
        GLint \fIbase\fP,
 
28
        GLint \fImax\fP,
 
29
        const void \fI*data\fP )
 
30
.fi
 
31
 
 
32
.EQ
 
33
delim $$
 
34
.EN
 
35
.SH PARAMETERS
 
36
.TP \w'\fIinternalFormat\fP\ \ 'u 
 
37
\f2target\fP
 
38
Specifies the target texture.  Must be \%\f3GL_TEXTURE_3D\fP.
 
39
.TP
 
40
\f2internalFormat\fP
 
41
Requests the internal storage  of the texture image.  The most
 
42
current version of the SGI implementation of GLU does not check this
 
43
value for validity before passing it on to the underlying OpenGL
 
44
implementation.  A value that is not accepted by the OpenGL
 
45
implementation will lead to an OpenGL error.  The benefit of not
 
46
checking this value at the GLU level is that OpenGL extensions can add
 
47
new internal texture formats without requiring a revision of the GLU
 
48
implementation.  Older implementations of GLU check this value and
 
49
raise a GLU error if it is not 1, 2, 3, or 4 or one of the following
 
50
symbolic constants:
 
51
\%\f3GL_ALPHA\fP,
 
52
\%\f3GL_ALPHA4\fP,
 
53
\%\f3GL_ALPHA8\fP,
 
54
\%\f3GL_ALPHA12\fP,
 
55
\%\f3GL_ALPHA16\fP,
 
56
\%\f3GL_LUMINANCE\fP,
 
57
\%\f3GL_LUMINANCE4\fP,
 
58
\%\f3GL_LUMINANCE8\fP,
 
59
\%\f3GL_LUMINANCE12\fP,
 
60
\%\f3GL_LUMINANCE16\fP,
 
61
\%\f3GL_LUMINANCE_ALPHA\fP,
 
62
\%\f3GL_LUMINANCE4_ALPHA4\fP,
 
63
\%\f3GL_LUMINANCE6_ALPHA2\fP,
 
64
\%\f3GL_LUMINANCE8_ALPHA8\fP,
 
65
\%\f3GL_LUMINANCE12_ALPHA4\fP,
 
66
\%\f3GL_LUMINANCE12_ALPHA12\fP,
 
67
\%\f3GL_LUMINANCE16_ALPHA16\fP,
 
68
\%\f3GL_INTENSITY\fP,
 
69
\%\f3GL_INTENSITY4\fP,
 
70
\%\f3GL_INTENSITY8\fP,
 
71
\%\f3GL_INTENSITY12\fP,
 
72
\%\f3GL_INTENSITY16\fP,
 
73
\%\f3GL_RGB\fP,
 
74
\%\f3GL_R3_G3_B2\fP,
 
75
\%\f3GL_RGB4\fP,
 
76
\%\f3GL_RGB5\fP,
 
77
\%\f3GL_RGB8\fP,
 
78
\%\f3GL_RGB10\fP,
 
79
\%\f3GL_RGB12\fP,
 
80
\%\f3GL_RGB16\fP,
 
81
\%\f3GL_RGBA\fP,
 
82
\%\f3GL_RGBA2\fP,
 
83
\%\f3GL_RGBA4\fP,
 
84
\%\f3GL_RGB5_A1\fP,
 
85
\%\f3GL_RGBA8\fP,
 
86
\%\f3GL_RGB10_A2\fP,
 
87
\%\f3GL_RGBA12\fP, or
 
88
\%\f3GL_RGBA16\fP.
 
89
.TP
 
90
\f2width\fP, \f2height\fP, \f2depth\fP
 
91
Specifies in pixels the width, height and depth respectively, of the texture
 
92
image. These should be a power of 2.
 
93
.TP
 
94
\f2format\fP
 
95
Specifies the  of the pixel data.
 
96
Must be one of
 
97
\%\f3GL_COLOR_INDEX\fP,
 
98
\%\f3GL_DEPTH_COMPONENT\fP,
 
99
\%\f3GL_RED\fP,
 
100
\%\f3GL_GREEN\fP,
 
101
\%\f3GL_BLUE\fP,
 
102
\%\f3GL_ALPHA\fP,
 
103
\%\f3GL_RGB\fP,
 
104
\%\f3GL_RGBA\fP,
 
105
\%\f3GL_BGR\fP,
 
106
\%\f3GL_BGRA\fP,
 
107
\%\f3GL_LUMINANCE\fP, or
 
108
\%\f3GL_LUMINANCE_ALPHA\fP.
 
109
.TP
 
110
\f2type\fP
 
111
Specifies the data type for \f2data\fP.
 
112
Must be one of
 
113
\%\f3GL_UNSIGNED_BYTE\fP,
 
114
\%\f3GL_BYTE\fP,
 
115
\%\f3GL_BITMAP\fP,
 
116
\%\f3GL_UNSIGNED_SHORT\fP,
 
117
\%\f3GL_SHORT\fP,
 
118
\%\f3GL_UNSIGNED_INT\fP,
 
119
\%\f3GL_INT\fP, 
 
120
\%\f3GL_FLOAT\fP, 
 
121
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
 
122
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
 
123
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
 
124
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
 
125
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
 
126
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
 
127
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
 
128
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
 
129
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
 
130
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
 
131
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, or
 
132
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP.
 
133
.TP
 
134
\f2level\fP
 
135
Specifies the mipmap level of the image data.
 
136
.TP
 
137
\f2base\fP
 
138
Specifies the minimum mipmap level to pass to \f3glTexImage3D\fP.
 
139
.TP
 
140
\f2max\fP
 
141
Specifies the maximum mipmap level to pass to \f3glTexImage3D\fP.
 
142
.TP
 
143
\f2data\fP
 
144
Specifies a pointer to the image data in memory.
 
145
.SH DESCRIPTION
 
146
\%\f3gluBuild3DMipmapLevels\fP builds a subset of prefiltered three-dimensional texture maps of
 
147
decreasing resolutions called a mipmap. This is used for the antialiasing of
 
148
texture mapped primitives.
 
149
.P
 
150
A return value of zero indicates success, otherwise a GLU error code is
 
151
returned (see \%\f3gluErrorString\fP).
 
152
.P
 
153
A series of mipmap levels from \f2base\fP to \f2max\fP is built by
 
154
decimating \f2data\fP in half along both dimensions until size $1 ~times~ 1
 
155
~times~ 1$ is reached. At each level, each texel in the halved mipmap
 
156
level is an average of the corresponding eight texels in the larger
 
157
mipmap level. (If exactly one of the dimensions is 1, four texels are
 
158
averaged.  If exactly two of the dimensions are 1, two texels are
 
159
averaged.)  \f3glTexImage3D\fP is called to load these mipmap levels
 
160
from \f2base\fP to \f2max\fP. If \f2max\fP is larger than the highest mipmap
 
161
level for the texture of the specified size, then a GLU error code is
 
162
returned (see \%\f3gluErrorString\fP) and nothing is loaded.
 
163
.P
 
164
For example, if \f2level\fP is 2 and \f2width\fP is 16, \f2height\fP is 8 and \f2depth\fP
 
165
is 4, the following levels are possible: $16 ~times~ 8 ~times~ 4$, $8 ~times~
 
166
4 ~times~ 2$, $4 ~times~ 2 ~times~ 1$, $2 ~times~ 1 ~times~ 1$,
 
167
$1 ~times~ 1 ~times~ 1$.
 
168
These correspond to levels 2 through 6 respectively.  If \f2base\fP is
 
169
3 and \f2max\fP is 5, then only mipmap levels $8 ~times~ 4 ~times~ 2$, $4
 
170
~times~ 2 ~times~ 1$ and $2 ~times~ 1 ~times~ 1$ are loaded. However, if
 
171
\f2max\fP is 7 then an error is returned and nothing is loaded, since
 
172
\f2max\fP is larger than the highest mipmap level which is, in this case,
 
173
6.
 
174
.P
 
175
The highest mipmap level can be derived from the formula
 
176
${log sub 2} ( max ("width","height","depth")^{2 sup "level"})$.
 
177
.P
 
178
See the \f3glTexImage1D\fP reference page for a description of the
 
179
acceptable values for \f2format\fP parameter. See the \f3glDrawPixels\fP 
 
180
reference page for a description of the acceptable values 
 
181
for \f2type\fP parameter.
 
182
.SH NOTES
 
183
\%\f3gluBuild3DMipmapLevels\fP is only available if the GLU version is 1.3 or greater.
 
184
.P
 
185
Formats \%\f3GL_BGR\fP, and \%\f3GL_BGRA\fP, and types 
 
186
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
 
187
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
 
188
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
 
189
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
 
190
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
 
191
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
 
192
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
 
193
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
 
194
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
 
195
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
 
196
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
 
197
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP are only available if the GL version 
 
198
is 1.2 or greater.
 
199
.SH ERRORS
 
200
\%\f3GLU_INVALID_VALUE\fP is returned if \f2level\fP > \f2base\fP, \f2base\fP < 0,
 
201
\f2max\fP < \f2base\fP or \f2max\fP is > the highest mipmap level for \f2data\fP.
 
202
.P
 
203
\%\f3GLU_INVALID_VALUE\fP is returned if \f2width\fP, \f2height\fP, or \f2depth\fP is < 1.
 
204
.P
 
205
\%\f3GLU_INVALID_ENUM\fP is returned if \f2internalFormat\fP, \f2format\fP, or \f2type\fP is not 
 
206
legal.
 
207
.P
 
208
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_BYTE_3_3_2\fP or \%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP
 
209
and \f2format\fP is not \%\f3GL_RGB\fP.
 
210
.P
 
211
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_6_5\fP or \%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP
 
212
and \f2format\fP is not \%\f3GL_RGB\fP.
 
213
.P
 
214
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP or \%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP
 
215
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
 
216
.P
 
217
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP or \%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP
 
218
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
 
219
.P
 
220
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_8_8_8_8\fP or \%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP
 
221
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
 
222
.P
 
223
\%\f3GLU_INVALID_OPERATION\fP is returned if \f2type\fP is \%\f3GL_UNSIGNED_INT_10_10_10_2\fP or \%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP
 
224
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
 
225
.SH SEE ALSO
 
226
\f3glDrawPixels(3G)\fP,
 
227
\f3glTexImage1D(3G)\fP,
 
228
\f3glTexImage2D(3G)\fP, 
 
229
\f3glTexImage3D(3G)\fP,
 
230
\%\f3gluBuild1DMipmaps(3G)\fP,
 
231
\%\f3gluBuild2DMipmaps(3G)\fP,
 
232
\%\f3gluBuild3DMipmaps(3G)\fP, 
 
233
\%\f3gluErrorString(3G)\fP, 
 
234
\f3glGetTexImage(3G)\fP,
 
235
\f3glGetTexLevelParameter(3G)\fP,
 
236
\%\f3gluBuild1DMipmapLevels(3G)\fP,
 
237
\%\f3gluBuild2DMipmapLevels(3G)\fP