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