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