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