Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> |
2 | <!-- saved from url=(0013)about:internet --> | |
3 | <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>gluBuild1DMipmaps</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="gluBuild1DMipmaps"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>gluBuild1DMipmaps — builds a one-dimensional mipmap</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">GLint <b class="fsfunc">gluBuild1DMipmaps</b>(</code></td><td>GLenum </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">internalFormat</var>, </td></tr><tr><td> </td><td>GLsizei </td><td><var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLenum </td><td><var class="pdparam">format</var>, </td></tr><tr><td> </td><td>GLenum </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const void * </td><td><var class="pdparam">data</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p> | |
4 | Specifies the target texture. Must be <code class="constant">GLU_TEXTURE_1D</code>. | |
5 | </p></dd><dt><span class="term"><em class="parameter"><code>internalFormat</code></em></span></dt><dd><p> | |
6 | Requests the internal storage format of the texture image. The most | |
7 | current version of the SGI implementation of GLU does not check this | |
8 | value for validity before passing it on to the underlying OpenGL | |
9 | implementation. A value that is not accepted by the OpenGL | |
10 | implementation will lead to an OpenGL error. The benefit of not | |
11 | checking this value at the GLU level is that OpenGL extensions can add | |
12 | new internal texture formats without requiring a revision of the GLU | |
13 | implementation. Older implementations of GLU check this value and | |
14 | raise a GLU error if it is not 1, 2, 3, or 4 or one of the following | |
15 | symbolic constants: | |
16 | <code class="constant">GLU_ALPHA</code>, | |
17 | <code class="constant">GLU_ALPHA4</code>, | |
18 | <code class="constant">GLU_ALPHA8</code>, | |
19 | <code class="constant">GLU_ALPHA12</code>, | |
20 | <code class="constant">GLU_ALPHA16</code>, | |
21 | <code class="constant">GLU_LUMINANCE</code>, | |
22 | <code class="constant">GLU_LUMINANCE4</code>, | |
23 | <code class="constant">GLU_LUMINANCE8</code>, | |
24 | <code class="constant">GLU_LUMINANCE12</code>, | |
25 | <code class="constant">GLU_LUMINANCE16</code>, | |
26 | <code class="constant">GLU_LUMINANCE_ALPHA</code>, | |
27 | <code class="constant">GLU_LUMINANCE4_ALPHA4</code>, | |
28 | <code class="constant">GLU_LUMINANCE6_ALPHA2</code>, | |
29 | <code class="constant">GLU_LUMINANCE8_ALPHA8</code>, | |
30 | <code class="constant">GLU_LUMINANCE12_ALPHA4</code>, | |
31 | <code class="constant">GLU_LUMINANCE12_ALPHA12</code>, | |
32 | <code class="constant">GLU_LUMINANCE16_ALPHA16</code>, | |
33 | <code class="constant">GLU_INTENSITY</code>, | |
34 | <code class="constant">GLU_INTENSITY4</code>, | |
35 | <code class="constant">GLU_INTENSITY8</code>, | |
36 | <code class="constant">GLU_INTENSITY12</code>, | |
37 | <code class="constant">GLU_INTENSITY16</code>, | |
38 | <code class="constant">GLU_RGB</code>, | |
39 | <code class="constant">GLU_R3_G3_B2</code>, | |
40 | <code class="constant">GLU_RGB4</code>, | |
41 | <code class="constant">GLU_RGB5</code>, | |
42 | <code class="constant">GLU_RGB8</code>, | |
43 | <code class="constant">GLU_RGB10</code>, | |
44 | <code class="constant">GLU_RGB12</code>, | |
45 | <code class="constant">GLU_RGB16</code>, | |
46 | <code class="constant">GLU_RGBA</code>, | |
47 | <code class="constant">GLU_RGBA2</code>, | |
48 | <code class="constant">GLU_RGBA4</code>, | |
49 | <code class="constant">GLU_RGB5_A1</code>, | |
50 | <code class="constant">GLU_RGBA8</code>, | |
51 | <code class="constant">GLU_RGB10_A2</code>, | |
52 | <code class="constant">GLU_RGBA12</code>, or | |
53 | <code class="constant">GLU_RGBA16</code>. | |
54 | </p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p> | |
55 | Specifies the width, in pixels, of the texture image. | |
56 | </p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p> | |
57 | Specifies the format of the pixel data. | |
58 | Must be one of | |
59 | <code class="constant">GLU_COLOR_INDEX</code>, | |
60 | <code class="constant">GLU_DEPTH_COMPONENT</code>, | |
61 | <code class="constant">GLU_RED</code>, | |
62 | <code class="constant">GLU_GREEN</code>, | |
63 | <code class="constant">GLU_BLUE</code>, | |
64 | <code class="constant">GLU_ALPHA</code>, | |
65 | <code class="constant">GLU_RGB</code>, | |
66 | <code class="constant">GLU_RGBA</code>, | |
67 | <code class="constant">GLU_BGR</code>, | |
68 | <code class="constant">GLU_BGRA</code>, | |
69 | <code class="constant">GLU_LUMINANCE</code>, or | |
70 | <code class="constant">GLU_LUMINANCE_ALPHA</code>. | |
71 | </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p> | |
72 | Specifies the data type for <em class="parameter"><code>data</code></em>. | |
73 | Must be one of | |
74 | <code class="constant">GLU_UNSIGNED_BYTE</code>, | |
75 | <code class="constant">GLU_BYTE</code>, | |
76 | <code class="constant">GLU_BITMAP</code>, | |
77 | <code class="constant">GLU_UNSIGNED_SHORT</code>, | |
78 | <code class="constant">GLU_SHORT</code>, | |
79 | <code class="constant">GLU_UNSIGNED_INT</code>, | |
80 | <code class="constant">GLU_INT</code>, | |
81 | <code class="constant">GLU_FLOAT</code>, | |
82 | <code class="constant">GLU_UNSIGNED_BYTE_3_3_2</code>, | |
83 | <code class="constant">GLU_UNSIGNED_BYTE_2_3_3_REV</code>, | |
84 | <code class="constant">GLU_UNSIGNED_SHORT_5_6_5</code>, | |
85 | <code class="constant">GLU_UNSIGNED_SHORT_5_6_5_REV</code>, | |
86 | <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4</code>, | |
87 | <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4_REV</code>, | |
88 | <code class="constant">GLU_UNSIGNED_SHORT_5_5_5_1</code>, | |
89 | <code class="constant">GLU_UNSIGNED_SHORT_1_5_5_5_REV</code>, | |
90 | <code class="constant">GLU_UNSIGNED_INT_8_8_8_8</code>, | |
91 | <code class="constant">GLU_UNSIGNED_INT_8_8_8_8_REV</code>, | |
92 | <code class="constant">GLU_UNSIGNED_INT_10_10_10_2</code>, or | |
93 | <code class="constant">GLU_UNSIGNED_INT_2_10_10_10_REV</code>. | |
94 | </p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p> | |
95 | Specifies a pointer to the image data in memory. | |
96 | </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p> | |
97 | <code class="function">gluBuild1DMipmaps</code> builds a series of prefiltered one-dimensional texture maps of decreasing | |
98 | resolutions called a mipmap. This is used for the antialiasing of | |
99 | texture mapped primitives. | |
100 | </p><p> | |
101 | A return value of zero indicates success, otherwise a GLU error code is | |
102 | returned (see <a class="citerefentry" href="gluErrorString.xml"><span class="citerefentry"><span class="refentrytitle">gluErrorString</span></span></a>). | |
103 | </p><p> | |
104 | Initially, the <em class="parameter"><code>width</code></em> of <em class="parameter"><code>data</code></em> is checked to see if it is | |
105 | a power of 2. If not, a copy of <em class="parameter"><code>data</code></em> is scaled up or down to the | |
106 | nearest power of 2. (If <em class="parameter"><code>width</code></em> is exactly between powers of 2, then | |
107 | the copy of <em class="parameter"><code>data</code></em> will scale upwards.) This copy will be used for | |
108 | subsequent mipmapping operations described below. | |
109 | For example, if <em class="parameter"><code>width</code></em> is 57, then a copy of <em class="parameter"><code>data</code></em> | |
110 | will scale up to 64 before mipmapping | |
111 | takes place. | |
112 | </p><p> | |
113 | Then, proxy textures (see <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>) are used to determine if | |
114 | the implementation can fit the requested texture. If not, <em class="parameter"><code>width</code></em> is | |
115 | continually halved until it fits. | |
116 | </p><p> | |
117 | Next, a series of mipmap levels is built by decimating a copy of | |
118 | <em class="parameter"><code>data</code></em> in half | |
119 | until size | |
120 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
121 | ||
122 | <mml:mrow> | |
123 | <mml:mn>1</mml:mn> | |
124 | <mml:mo>×</mml:mo> | |
125 | <mml:mn>1</mml:mn> | |
126 | </mml:mrow> | |
127 | </mml:math> | |
128 | is reached. At each level, each texel in the | |
129 | halved mipmap level is an average of the corresponding two texels in the larger | |
130 | mipmap level. | |
131 | </p><p> | |
132 | <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a> is called to load each of these mipmap levels. | |
133 | Level 0 is a copy of <em class="parameter"><code>data</code></em>. | |
134 | The highest level is | |
135 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
136 | ||
137 | <mml:mrow> | |
138 | <mml:mfenced open="" close=""> | |
139 | <mml:msub><mml:mi mathvariant="italic">log</mml:mi> | |
140 | <mml:mn>2</mml:mn> | |
141 | </mml:msub> | |
142 | </mml:mfenced> | |
143 | <mml:mo></mml:mo> | |
144 | <mml:mfenced open="(" close=")"> | |
145 | <mml:mi mathvariant="italic">width</mml:mi> | |
146 | </mml:mfenced> | |
147 | </mml:mrow> | |
148 | </mml:math>. | |
149 | For example, if <em class="parameter"><code>width</code></em> is 64 and the implementation can store a texture of | |
150 | this size, the following mipmap levels are | |
151 | built: | |
152 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
153 | ||
154 | <mml:mrow> | |
155 | <mml:mn>64</mml:mn> | |
156 | <mml:mo>×</mml:mo> | |
157 | <mml:mn>1</mml:mn> | |
158 | </mml:mrow> | |
159 | </mml:math>, | |
160 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
161 | ||
162 | <mml:mrow> | |
163 | <mml:mn>32</mml:mn> | |
164 | <mml:mo>×</mml:mo> | |
165 | <mml:mn>1</mml:mn> | |
166 | </mml:mrow> | |
167 | </mml:math>, | |
168 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
169 | ||
170 | <mml:mrow> | |
171 | <mml:mn>16</mml:mn> | |
172 | <mml:mo>×</mml:mo> | |
173 | <mml:mn>1</mml:mn> | |
174 | </mml:mrow> | |
175 | </mml:math>, | |
176 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
177 | ||
178 | <mml:mrow> | |
179 | <mml:mn>8</mml:mn> | |
180 | <mml:mo>×</mml:mo> | |
181 | <mml:mn>1</mml:mn> | |
182 | </mml:mrow> | |
183 | </mml:math>, | |
184 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
185 | ||
186 | <mml:mrow> | |
187 | <mml:mn>4</mml:mn> | |
188 | <mml:mo>×</mml:mo> | |
189 | <mml:mn>1</mml:mn> | |
190 | </mml:mrow> | |
191 | </mml:math>, | |
192 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
193 | ||
194 | <mml:mrow> | |
195 | <mml:mn>2</mml:mn> | |
196 | <mml:mo>×</mml:mo> | |
197 | <mml:mn>1</mml:mn> | |
198 | </mml:mrow> | |
199 | </mml:math>, | |
200 | and | |
201 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
202 | ||
203 | <mml:mrow> | |
204 | <mml:mn>1</mml:mn> | |
205 | <mml:mo>×</mml:mo> | |
206 | <mml:mn>1</mml:mn> | |
207 | </mml:mrow> | |
208 | </mml:math>. | |
209 | These correspond to | |
210 | levels 0 through 6, respectively. | |
211 | </p><p> | |
212 | See the <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a> reference page for a description of the | |
213 | acceptable values for the <em class="parameter"><code>type</code></em> parameter. See the <a class="citerefentry" href="glDrawPixels.xml"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a> | |
214 | reference page for a description of the acceptable values | |
215 | for the <em class="parameter"><code>data</code></em> parameter. | |
216 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p> | |
217 | Note that there is no direct way of querying the maximum level. This can | |
218 | be derived indirectly via <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a>. First, query | |
219 | for the | |
220 | width actually used at level 0. | |
221 | (The width may not be equal to <em class="parameter"><code>width</code></em> since | |
222 | proxy textures might have scaled it to fit the implementation.) | |
223 | Then the maximum | |
224 | level can be derived from the formula | |
225 | <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"> | |
226 | ||
227 | <mml:mrow> | |
228 | <mml:mfenced open="" close=""> | |
229 | <mml:msub><mml:mi mathvariant="italic">log</mml:mi> | |
230 | <mml:mn>2</mml:mn> | |
231 | </mml:msub> | |
232 | </mml:mfenced> | |
233 | <mml:mo></mml:mo> | |
234 | <mml:mfenced open="(" close=")"> | |
235 | <mml:mi mathvariant="italic">width</mml:mi> | |
236 | </mml:mfenced> | |
237 | </mml:mrow> | |
238 | </mml:math>. | |
239 | </p><p> | |
240 | Formats <code class="constant">GLU_BGR</code>, and <code class="constant">GLU_BGRA</code>, and types | |
241 | <code class="constant">GLU_UNSIGNED_BYTE_3_3_2</code>, | |
242 | <code class="constant">GLU_UNSIGNED_BYTE_2_3_3_REV</code>, | |
243 | <code class="constant">GLU_UNSIGNED_SHORT_5_6_5</code>, | |
244 | <code class="constant">GLU_UNSIGNED_SHORT_5_6_5_REV</code>, | |
245 | <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4</code>, | |
246 | <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4_REV</code>, | |
247 | <code class="constant">GLU_UNSIGNED_SHORT_5_5_5_1</code>, | |
248 | <code class="constant">GLU_UNSIGNED_SHORT_1_5_5_5_REV</code>, | |
249 | <code class="constant">GLU_UNSIGNED_INT_8_8_8_8</code>, | |
250 | <code class="constant">GLU_UNSIGNED_INT_8_8_8_8_REV</code>, | |
251 | <code class="constant">GLU_UNSIGNED_INT_10_10_10_2</code>, and | |
252 | <code class="constant">GLU_UNSIGNED_INT_2_10_10_10_REV</code> are only available if the GL version | |
253 | is 1.2 or greater, and if the GLU version is 1.3 or greater. | |
254 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p> | |
255 | <code class="constant">GLU_INVALID_VALUE</code> is returned if <em class="parameter"><code>width</code></em> is < 1. | |
256 | </p><p> | |
257 | <code class="constant">GLU_INVALID_ENUM</code> is returned if <em class="parameter"><code>format</code></em> or <em class="parameter"><code>type</code></em> are not legal. | |
258 | </p><p> | |
259 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_BYTE_3_3_2</code> or <code class="constant">GLU_UNSIGNED_BYTE_2_3_3_REV</code> | |
260 | and <em class="parameter"><code>format</code></em> is not <code class="constant">GLU_RGB</code>. | |
261 | </p><p> | |
262 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_SHORT_5_6_5</code> or <code class="constant">GLU_UNSIGNED_SHORT_5_6_5_REV</code> | |
263 | and <em class="parameter"><code>format</code></em> is not <code class="constant">GLU_RGB</code>. | |
264 | </p><p> | |
265 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4</code> or <code class="constant">GLU_UNSIGNED_SHORT_4_4_4_4_REV</code> | |
266 | and <em class="parameter"><code>format</code></em> is neither <code class="constant">GLU_RGBA</code> nor <code class="constant">GLU_BGRA</code>. | |
267 | </p><p> | |
268 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_SHORT_5_5_5_1</code> or <code class="constant">GLU_UNSIGNED_SHORT_1_5_5_5_REV</code> | |
269 | and <em class="parameter"><code>format</code></em> is neither <code class="constant">GLU_RGBA</code> nor <code class="constant">GLU_BGRA</code>. | |
270 | </p><p> | |
271 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_INT_8_8_8_8</code> or <code class="constant">GLU_UNSIGNED_INT_8_8_8_8_REV</code> | |
272 | and <em class="parameter"><code>format</code></em> is neither <code class="constant">GLU_RGBA</code> nor <code class="constant">GLU_BGRA</code>. | |
273 | </p><p> | |
274 | <code class="constant">GLU_INVALID_OPERATION</code> is returned if <em class="parameter"><code>type</code></em> is <code class="constant">GLU_UNSIGNED_INT_10_10_10_2</code> or <code class="constant">GLU_UNSIGNED_INT_2_10_10_10_REV</code> | |
275 | and <em class="parameter"><code>format</code></em> is neither <code class="constant">GLU_RGBA</code> nor <code class="constant">GLU_BGRA</code>. | |
276 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p> | |
277 | <a class="citerefentry" href="gluBuild1DMipmapLevels.xml"><span class="citerefentry"><span class="refentrytitle">gluBuild1DMipmapLevels</span></span></a>, | |
278 | <a class="citerefentry" href="gluBuild2DMipmapLevels.xml"><span class="citerefentry"><span class="refentrytitle">gluBuild2DMipmapLevels</span></span></a>, | |
279 | <a class="citerefentry" href="gluBuild2DMipmaps.xml"><span class="citerefentry"><span class="refentrytitle">gluBuild2DMipmaps</span></span></a>, | |
280 | <a class="citerefentry" href="gluBuild3DMipmapLevels.xml"><span class="citerefentry"><span class="refentrytitle">gluBuild3DMipmapLevels</span></span></a>, | |
281 | <a class="citerefentry" href="gluBuild3DMipmaps.xml"><span class="citerefentry"><span class="refentrytitle">gluBuild3DMipmaps</span></span></a>, | |
282 | <a class="citerefentry" href="gluErrorString.xml"><span class="citerefentry"><span class="refentrytitle">gluErrorString</span></span></a>, | |
283 | <a class="citerefentry" href="glDrawPixels.xml"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a>, | |
284 | <a class="citerefentry" href="glGetTexImage.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a>, | |
285 | <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a>, | |
286 | <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>, | |
287 | <a class="citerefentry" href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>, | |
288 | <a class="citerefentry" href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a> | |
289 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
290 | Copyright <span class="trademark"></span>© 1991-2006 | |
291 | Silicon Graphics, Inc. This document is licensed under the SGI | |
292 | Free Software B License. For details, see | |
293 | <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>. | |
294 | </p></div></div></body></html> |