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