Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> | |
4 | <refentry id="gluBuild1DMipmaps"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>1991-2006</year> | |
9 | <holder>Silicon Graphics, Inc.</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>gluBuild1DMipmaps</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>gluBuild1DMipmaps</refname> | |
17 | <refpurpose>builds a one-dimensional mipmap</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>GLint <function>gluBuild1DMipmaps</function></funcdef> | |
23 | <paramdef>GLenum <parameter>target</parameter></paramdef> | |
24 | <paramdef>GLint <parameter>internalFormat</parameter></paramdef> | |
25 | <paramdef>GLsizei <parameter>width</parameter></paramdef> | |
26 | <paramdef>GLenum <parameter>format</parameter></paramdef> | |
27 | <paramdef>GLenum <parameter>type</parameter></paramdef> | |
28 | <paramdef>const void * <parameter>data</parameter></paramdef> | |
29 | </funcprototype> | |
30 | </funcsynopsis> | |
31 | </refsynopsisdiv> | |
32 | <!-- eqn: ignoring delim $$ --> | |
33 | <refsect1 id="parameters"><title>Parameters</title> | |
34 | <variablelist> | |
35 | <varlistentry> | |
36 | <term><parameter>target</parameter></term> | |
37 | <listitem> | |
38 | <para> | |
39 | Specifies the target texture. Must be <constant>GLU_TEXTURE_1D</constant>. | |
40 | </para> | |
41 | </listitem> | |
42 | </varlistentry> | |
43 | <varlistentry> | |
44 | <term><parameter>internalFormat</parameter></term> | |
45 | <listitem> | |
46 | <para> | |
47 | Requests the internal storage format of the texture image. The most | |
48 | current version of the SGI implementation of GLU does not check this | |
49 | value for validity before passing it on to the underlying OpenGL | |
50 | implementation. A value that is not accepted by the OpenGL | |
51 | implementation will lead to an OpenGL error. The benefit of not | |
52 | checking this value at the GLU level is that OpenGL extensions can add | |
53 | new internal texture formats without requiring a revision of the GLU | |
54 | implementation. Older implementations of GLU check this value and | |
55 | raise a GLU error if it is not 1, 2, 3, or 4 or one of the following | |
56 | symbolic constants: | |
57 | <constant>GLU_ALPHA</constant>, | |
58 | <constant>GLU_ALPHA4</constant>, | |
59 | <constant>GLU_ALPHA8</constant>, | |
60 | <constant>GLU_ALPHA12</constant>, | |
61 | <constant>GLU_ALPHA16</constant>, | |
62 | <constant>GLU_LUMINANCE</constant>, | |
63 | <constant>GLU_LUMINANCE4</constant>, | |
64 | <constant>GLU_LUMINANCE8</constant>, | |
65 | <constant>GLU_LUMINANCE12</constant>, | |
66 | <constant>GLU_LUMINANCE16</constant>, | |
67 | <constant>GLU_LUMINANCE_ALPHA</constant>, | |
68 | <constant>GLU_LUMINANCE4_ALPHA4</constant>, | |
69 | <constant>GLU_LUMINANCE6_ALPHA2</constant>, | |
70 | <constant>GLU_LUMINANCE8_ALPHA8</constant>, | |
71 | <constant>GLU_LUMINANCE12_ALPHA4</constant>, | |
72 | <constant>GLU_LUMINANCE12_ALPHA12</constant>, | |
73 | <constant>GLU_LUMINANCE16_ALPHA16</constant>, | |
74 | <constant>GLU_INTENSITY</constant>, | |
75 | <constant>GLU_INTENSITY4</constant>, | |
76 | <constant>GLU_INTENSITY8</constant>, | |
77 | <constant>GLU_INTENSITY12</constant>, | |
78 | <constant>GLU_INTENSITY16</constant>, | |
79 | <constant>GLU_RGB</constant>, | |
80 | <constant>GLU_R3_G3_B2</constant>, | |
81 | <constant>GLU_RGB4</constant>, | |
82 | <constant>GLU_RGB5</constant>, | |
83 | <constant>GLU_RGB8</constant>, | |
84 | <constant>GLU_RGB10</constant>, | |
85 | <constant>GLU_RGB12</constant>, | |
86 | <constant>GLU_RGB16</constant>, | |
87 | <constant>GLU_RGBA</constant>, | |
88 | <constant>GLU_RGBA2</constant>, | |
89 | <constant>GLU_RGBA4</constant>, | |
90 | <constant>GLU_RGB5_A1</constant>, | |
91 | <constant>GLU_RGBA8</constant>, | |
92 | <constant>GLU_RGB10_A2</constant>, | |
93 | <constant>GLU_RGBA12</constant>, or | |
94 | <constant>GLU_RGBA16</constant>. | |
95 | </para> | |
96 | </listitem> | |
97 | </varlistentry> | |
98 | <varlistentry> | |
99 | <term><parameter>width</parameter></term> | |
100 | <listitem> | |
101 | <para> | |
102 | Specifies the width, in pixels, of the texture image. | |
103 | </para> | |
104 | </listitem> | |
105 | </varlistentry> | |
106 | <varlistentry> | |
107 | <term><parameter>format</parameter></term> | |
108 | <listitem> | |
109 | <para> | |
110 | Specifies the format of the pixel data. | |
111 | Must be one of | |
112 | <constant>GLU_COLOR_INDEX</constant>, | |
113 | <constant>GLU_DEPTH_COMPONENT</constant>, | |
114 | <constant>GLU_RED</constant>, | |
115 | <constant>GLU_GREEN</constant>, | |
116 | <constant>GLU_BLUE</constant>, | |
117 | <constant>GLU_ALPHA</constant>, | |
118 | <constant>GLU_RGB</constant>, | |
119 | <constant>GLU_RGBA</constant>, | |
120 | <constant>GLU_BGR</constant>, | |
121 | <constant>GLU_BGRA</constant>, | |
122 | <constant>GLU_LUMINANCE</constant>, or | |
123 | <constant>GLU_LUMINANCE_ALPHA</constant>. | |
124 | </para> | |
125 | </listitem> | |
126 | </varlistentry> | |
127 | <varlistentry> | |
128 | <term><parameter>type</parameter></term> | |
129 | <listitem> | |
130 | <para> | |
131 | Specifies the data type for <parameter>data</parameter>. | |
132 | Must be one of | |
133 | <constant>GLU_UNSIGNED_BYTE</constant>, | |
134 | <constant>GLU_BYTE</constant>, | |
135 | <constant>GLU_BITMAP</constant>, | |
136 | <constant>GLU_UNSIGNED_SHORT</constant>, | |
137 | <constant>GLU_SHORT</constant>, | |
138 | <constant>GLU_UNSIGNED_INT</constant>, | |
139 | <constant>GLU_INT</constant>, | |
140 | <constant>GLU_FLOAT</constant>, | |
141 | <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>, | |
142 | <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>, | |
143 | <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>, | |
144 | <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>, | |
145 | <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>, | |
146 | <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>, | |
147 | <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>, | |
148 | <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>, | |
149 | <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>, | |
150 | <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>, | |
151 | <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, or | |
152 | <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>. | |
153 | </para> | |
154 | </listitem> | |
155 | </varlistentry> | |
156 | <varlistentry> | |
157 | <term><parameter>data</parameter></term> | |
158 | <listitem> | |
159 | <para> | |
160 | Specifies a pointer to the image data in memory. | |
161 | </para> | |
162 | </listitem> | |
163 | </varlistentry> | |
164 | </variablelist> | |
165 | </refsect1> | |
166 | <refsect1 id="description"><title>Description</title> | |
167 | <para> | |
168 | <function>gluBuild1DMipmaps</function> builds a series of prefiltered one-dimensional texture maps of decreasing | |
169 | resolutions called a mipmap. This is used for the antialiasing of | |
170 | texture mapped primitives. | |
171 | </para> | |
172 | <para> | |
173 | A return value of zero indicates success, otherwise a GLU error code is | |
174 | returned (see <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>). | |
175 | </para> | |
176 | <para> | |
177 | Initially, the <parameter>width</parameter> of <parameter>data</parameter> is checked to see if it is | |
178 | a power of 2. If not, a copy of <parameter>data</parameter> is scaled up or down to the | |
179 | nearest power of 2. (If <parameter>width</parameter> is exactly between powers of 2, then | |
180 | the copy of <parameter>data</parameter> will scale upwards.) This copy will be used for | |
181 | subsequent mipmapping operations described below. | |
182 | For example, if <parameter>width</parameter> is 57, then a copy of <parameter>data</parameter> | |
183 | will scale up to 64 before mipmapping | |
184 | takes place. | |
185 | </para> | |
186 | <para> | |
187 | Then, proxy textures (see <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>) are used to determine if | |
188 | the implementation can fit the requested texture. If not, <parameter>width</parameter> is | |
189 | continually halved until it fits. | |
190 | </para> | |
191 | <para> | |
192 | Next, a series of mipmap levels is built by decimating a copy of | |
193 | <parameter>data</parameter> in half | |
194 | until size | |
195 | <inlineequation><mml:math> | |
196 | <!-- eqn: 1 times 1:--> | |
197 | <mml:mrow> | |
198 | <mml:mn>1</mml:mn> | |
199 | <mml:mo>×</mml:mo> | |
200 | <mml:mn>1</mml:mn> | |
201 | </mml:mrow> | |
202 | </mml:math></inlineequation> | |
203 | is reached. At each level, each texel in the | |
204 | halved mipmap level is an average of the corresponding two texels in the larger | |
205 | mipmap level. | |
206 | </para> | |
207 | <para> | |
208 | <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> is called to load each of these mipmap levels. | |
209 | Level 0 is a copy of <parameter>data</parameter>. | |
210 | The highest level is | |
211 | <inlineequation><mml:math> | |
212 | <!-- eqn: {log sub 2}(width):--> | |
213 | <mml:mrow> | |
214 | <mml:mfenced open="" close=""> | |
215 | <mml:msub><mml:mi mathvariant="italic">log</mml:mi> | |
216 | <mml:mn>2</mml:mn> | |
217 | </mml:msub> | |
218 | </mml:mfenced> | |
219 | <mml:mo>⁡</mml:mo> | |
220 | <mml:mfenced open="(" close=")"> | |
221 | <mml:mi mathvariant="italic">width</mml:mi> | |
222 | </mml:mfenced> | |
223 | </mml:mrow> | |
224 | </mml:math></inlineequation>. | |
225 | For example, if <parameter>width</parameter> is 64 and the implementation can store a texture of | |
226 | this size, the following mipmap levels are | |
227 | built: | |
228 | <inlineequation><mml:math> | |
229 | <!-- eqn: 64 times 1:--> | |
230 | <mml:mrow> | |
231 | <mml:mn>64</mml:mn> | |
232 | <mml:mo>×</mml:mo> | |
233 | <mml:mn>1</mml:mn> | |
234 | </mml:mrow> | |
235 | </mml:math></inlineequation>, | |
236 | <inlineequation><mml:math> | |
237 | <!-- eqn: 32 times 1:--> | |
238 | <mml:mrow> | |
239 | <mml:mn>32</mml:mn> | |
240 | <mml:mo>×</mml:mo> | |
241 | <mml:mn>1</mml:mn> | |
242 | </mml:mrow> | |
243 | </mml:math></inlineequation>, | |
244 | <inlineequation><mml:math> | |
245 | <!-- eqn: 16 times 1:--> | |
246 | <mml:mrow> | |
247 | <mml:mn>16</mml:mn> | |
248 | <mml:mo>×</mml:mo> | |
249 | <mml:mn>1</mml:mn> | |
250 | </mml:mrow> | |
251 | </mml:math></inlineequation>, | |
252 | <inlineequation><mml:math> | |
253 | <!-- eqn: 8 times 1:--> | |
254 | <mml:mrow> | |
255 | <mml:mn>8</mml:mn> | |
256 | <mml:mo>×</mml:mo> | |
257 | <mml:mn>1</mml:mn> | |
258 | </mml:mrow> | |
259 | </mml:math></inlineequation>, | |
260 | <inlineequation><mml:math> | |
261 | <!-- eqn: 4 times 1:--> | |
262 | <mml:mrow> | |
263 | <mml:mn>4</mml:mn> | |
264 | <mml:mo>×</mml:mo> | |
265 | <mml:mn>1</mml:mn> | |
266 | </mml:mrow> | |
267 | </mml:math></inlineequation>, | |
268 | <inlineequation><mml:math> | |
269 | <!-- eqn: 2 times 1:--> | |
270 | <mml:mrow> | |
271 | <mml:mn>2</mml:mn> | |
272 | <mml:mo>×</mml:mo> | |
273 | <mml:mn>1</mml:mn> | |
274 | </mml:mrow> | |
275 | </mml:math></inlineequation>, | |
276 | and | |
277 | <inlineequation><mml:math> | |
278 | <!-- eqn: 1 times 1:--> | |
279 | <mml:mrow> | |
280 | <mml:mn>1</mml:mn> | |
281 | <mml:mo>×</mml:mo> | |
282 | <mml:mn>1</mml:mn> | |
283 | </mml:mrow> | |
284 | </mml:math></inlineequation>. | |
285 | These correspond to | |
286 | levels 0 through 6, respectively. | |
287 | </para> | |
288 | <para> | |
289 | See the <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> reference page for a description of the | |
290 | acceptable values for the <parameter>type</parameter> parameter. See the <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> | |
291 | reference page for a description of the acceptable values | |
292 | for the <parameter>data</parameter> parameter. | |
293 | </para> | |
294 | </refsect1> | |
295 | <refsect1 id="notes"><title>Notes</title> | |
296 | <para> | |
297 | Note that there is no direct way of querying the maximum level. This can | |
298 | be derived indirectly via <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>. First, query | |
299 | for the | |
300 | width actually used at level 0. | |
301 | (The width may not be equal to <parameter>width</parameter> since | |
302 | proxy textures might have scaled it to fit the implementation.) | |
303 | Then the maximum | |
304 | level can be derived from the formula | |
305 | <inlineequation><mml:math> | |
306 | <!-- eqn: {log sub 2}(width):--> | |
307 | <mml:mrow> | |
308 | <mml:mfenced open="" close=""> | |
309 | <mml:msub><mml:mi mathvariant="italic">log</mml:mi> | |
310 | <mml:mn>2</mml:mn> | |
311 | </mml:msub> | |
312 | </mml:mfenced> | |
313 | <mml:mo>⁡</mml:mo> | |
314 | <mml:mfenced open="(" close=")"> | |
315 | <mml:mi mathvariant="italic">width</mml:mi> | |
316 | </mml:mfenced> | |
317 | </mml:mrow> | |
318 | </mml:math></inlineequation>. | |
319 | </para> | |
320 | <para> | |
321 | Formats <constant>GLU_BGR</constant>, and <constant>GLU_BGRA</constant>, and types | |
322 | <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>, | |
323 | <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>, | |
324 | <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>, | |
325 | <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>, | |
326 | <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>, | |
327 | <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>, | |
328 | <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>, | |
329 | <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>, | |
330 | <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>, | |
331 | <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>, | |
332 | <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, and | |
333 | <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant> are only available if the GL version | |
334 | is 1.2 or greater, and if the GLU version is 1.3 or greater. | |
335 | </para> | |
336 | </refsect1> | |
337 | <refsect1 id="errors"><title>Errors</title> | |
338 | <para> | |
339 | <constant>GLU_INVALID_VALUE</constant> is returned if <parameter>width</parameter> is < 1. | |
340 | </para> | |
341 | <para> | |
342 | <constant>GLU_INVALID_ENUM</constant> is returned if <parameter>format</parameter> or <parameter>type</parameter> are not legal. | |
343 | </para> | |
344 | <para> | |
345 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_BYTE_3_3_2</constant> or <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant> | |
346 | and <parameter>format</parameter> is not <constant>GLU_RGB</constant>. | |
347 | </para> | |
348 | <para> | |
349 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_SHORT_5_6_5</constant> or <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant> | |
350 | and <parameter>format</parameter> is not <constant>GLU_RGB</constant>. | |
351 | </para> | |
352 | <para> | |
353 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant> or <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant> | |
354 | and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>. | |
355 | </para> | |
356 | <para> | |
357 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant> or <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant> | |
358 | and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>. | |
359 | </para> | |
360 | <para> | |
361 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_INT_8_8_8_8</constant> or <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant> | |
362 | and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>. | |
363 | </para> | |
364 | <para> | |
365 | <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is <constant>GLU_UNSIGNED_INT_10_10_10_2</constant> or <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant> | |
366 | and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>. | |
367 | </para> | |
368 | </refsect1> | |
369 | <refsect1 id="seealso"><title>See Also</title> | |
370 | <para> | |
371 | <citerefentry><refentrytitle>gluBuild1DMipmapLevels</refentrytitle></citerefentry>, | |
372 | <citerefentry><refentrytitle>gluBuild2DMipmapLevels</refentrytitle></citerefentry>, | |
373 | <citerefentry><refentrytitle>gluBuild2DMipmaps</refentrytitle></citerefentry>, | |
374 | <citerefentry><refentrytitle>gluBuild3DMipmapLevels</refentrytitle></citerefentry>, | |
375 | <citerefentry><refentrytitle>gluBuild3DMipmaps</refentrytitle></citerefentry>, | |
376 | <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>, | |
377 | <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>, | |
378 | <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>, | |
379 | <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>, | |
380 | <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>, | |
381 | <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>, | |
382 | <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> | |
383 | </para> | |
384 | </refsect1> | |
385 | <refsect1 id="Copyright"><title>Copyright</title> | |
386 | <para> | |
387 | Copyright <trademark class="copyright"></trademark> 1991-2006 | |
388 | Silicon Graphics, Inc. This document is licensed under the SGI | |
389 | Free Software B License. For details, see | |
390 | <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>. | |
391 | </para> | |
392 | </refsect1> | |
393 | </refentry> |