upstream-man-pages/man2/gluBuild2DMipmaps.xml

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