upstream-doc/man2/gluScaleImage.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="gluScaleImage">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluScaleImage</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluScaleImage</refname>
  17         <refpurpose>scale an image to an arbitrary size</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>GLint <function>gluScaleImage</function></funcdef>
  23                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  24                 <paramdef>GLsizei <parameter>wIn</parameter></paramdef>
  25                 <paramdef>GLsizei <parameter>hIn</parameter></paramdef>
  26                 <paramdef>GLenum <parameter>typeIn</parameter></paramdef>
  27                 <paramdef>const void * <parameter>dataIn</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>wOut</parameter></paramdef>
  29                 <paramdef>GLsizei <parameter>hOut</parameter></paramdef>
  30                 <paramdef>GLenum <parameter>typeOut</parameter></paramdef>
  31                 <paramdef>GLvoid* <parameter>dataOut</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>format</parameter></term>
  40             <listitem>
  41                 <para>
  42                     Specifies the format of the pixel data.
  43                     The following symbolic values are valid:
  44                     <constant>GLU_COLOR_INDEX</constant>,
  45                     <constant>GLU_STENCIL_INDEX</constant>,
  46                     <constant>GLU_DEPTH_COMPONENT</constant>,
  47                     <constant>GLU_RED</constant>,
  48                     <constant>GLU_GREEN</constant>,
  49                     <constant>GLU_BLUE</constant>,
  50                     <constant>GLU_ALPHA</constant>,
  51                     <constant>GLU_RGB</constant>,
  52                     <constant>GLU_RGBA</constant>,
  53                     <constant>GLU_BGR</constant>,
  54                     <constant>GLU_BGRA</constant>,
  55                     <constant>GLU_LUMINANCE</constant>, and
  56                     <constant>GLU_LUMINANCE_ALPHA</constant>.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>wIn</parameter></term>
  62             <term><parameter>hIn</parameter></term>
  63             <listitem>
  64                 <para>
  65                     Specify in pixels the width and height, respectively, of the source image.
  66                 </para>
  67             </listitem>
  68         </varlistentry>
  69         <varlistentry>
  70             <term><parameter>typeIn</parameter></term>
  71             <listitem>
  72                 <para>
  73                     Specifies the data type for <parameter>dataIn</parameter>. Must be one of
  74                     <constant>GLU_UNSIGNED_BYTE</constant>,
  75                     <constant>GLU_BYTE</constant>,
  76                     <constant>GLU_BITMAP</constant>,
  77                     <constant>GLU_UNSIGNED_SHORT</constant>,
  78                     <constant>GLU_SHORT</constant>,
  79                     <constant>GLU_UNSIGNED_INT</constant>,
  80                     <constant>GLU_INT</constant>,
  81                     <constant>GLU_FLOAT</constant>,
  82                     <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
  83                     <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
  84                     <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
  85                     <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
  86                     <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
  87                     <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
  88                     <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
  89                     <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
  90                     <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
  91                     <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
  92                     <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, or
  93                     <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         <varlistentry>
  98             <term><parameter>dataIn</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Specifies a pointer to the source image.
 102                 </para>
 103             </listitem>
 104         </varlistentry>
 105         <varlistentry>
 106             <term><parameter>wOut</parameter></term>
 107             <term><parameter>hOut</parameter></term>
 108             <listitem>
 109                 <para>
 110                     Specify the width and height, respectively, in pixels of the destination image.
 111                 </para>
 112             </listitem>
 113         </varlistentry>
 114         <varlistentry>
 115             <term><parameter>typeOut</parameter></term>
 116             <listitem>
 117                 <para>
 118                     Specifies the data type for <parameter>dataOut</parameter>. Must be one of
 119                     <constant>GLU_UNSIGNED_BYTE</constant>,
 120                     <constant>GLU_BYTE</constant>,
 121                     <constant>GLU_BITMAP</constant>,
 122                     <constant>GLU_UNSIGNED_SHORT</constant>,
 123                     <constant>GLU_SHORT</constant>,
 124                     <constant>GLU_UNSIGNED_INT</constant>,
 125                     <constant>GLU_INT</constant>,
 126                     <constant>GLU_FLOAT</constant>,
 127                     <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
 128                     <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
 129                     <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
 130                     <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
 131                     <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
 132                     <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 133                     <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
 134                     <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 135                     <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
 136                     <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
 137                     <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, or
 138                     <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>.
 139                 </para>
 140             </listitem>
 141         </varlistentry>
 142         <varlistentry>
 143             <term><parameter>dataOut</parameter></term>
 144             <listitem>
 145                 <para>
 146                     Specifies a pointer to the destination image.
 147                 </para>
 148             </listitem>
 149         </varlistentry>
 150         </variablelist>
 151     </refsect1>
 152     <refsect1 id="description"><title>Description</title>
 153         <para>
 154             <function>gluScaleImage</function> scales a pixel image using the appropriate pixel store modes to
 155             unpack data from the source image and pack data into the destination image.
 156         </para>
 157         <para>
 158             When shrinking an image, <function>gluScaleImage</function> uses a box filter to sample the source image
 159             and create pixels for the destination image.  When magnifying an image,
 160             the pixels from the source image are linearly interpolated to create the
 161             destination image.
 162         </para>
 163         <para>
 164             A return value of zero indicates success, otherwise a GLU error code is returned (see <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>).
 165         </para>
 166         <para>
 167             See the <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> reference page for a description of
 168             the acceptable values for the <parameter>format</parameter>, <parameter>typeIn</parameter>, and <parameter>typeOut</parameter> parameters.
 169         </para>
 170     </refsect1>
 171     <refsect1 id="notes"><title>Notes</title>
 172         <para>
 173             Formats <constant>GLU_BGR</constant>, and <constant>GLU_BGRA</constant>, and types
 174             <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
 175             <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
 176             <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
 177             <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
 178             <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
 179             <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 180             <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
 181             <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 182             <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
 183             <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
 184             <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, and
 185             <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant> are only available if the GL version
 186             is 1.2 or greater.
 187         </para>
 188     </refsect1>
 189     <refsect1 id="errors"><title>Errors</title>
 190         <para>
 191             <constant>GLU_INVALID_VALUE</constant> is returned if <parameter>wIn</parameter>, <parameter>hIn</parameter>, <parameter>wOut</parameter>, or <parameter>hOut</parameter>
 192             is negative.
 193         </para>
 194         <para>
 195             <constant>GLU_INVALID_ENUM</constant> is returned if <parameter>format</parameter>, <parameter>typeIn</parameter>, or <parameter>typeOut</parameter> is not
 196             legal.
 197         </para>
 198         <para>
 199             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 200             <constant>GLU_UNSIGNED_BYTE_3_3_2</constant> or <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>
 201             and <parameter>format</parameter> is not <constant>GLU_RGB</constant>.
 202         </para>
 203         <para>
 204             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 205             <constant>GLU_UNSIGNED_SHORT_5_6_5</constant> or <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>
 206             and <parameter>format</parameter> is not <constant>GLU_RGB</constant>.
 207         </para>
 208         <para>
 209             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 210             <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant> or <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>
 211             and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
 212         </para>
 213         <para>
 214             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 215             <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant> or <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>
 216             and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
 217         </para>
 218         <para>
 219             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 220             <constant>GLU_UNSIGNED_INT_8_8_8_8</constant> or <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>
 221             and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
 222         </para>
 223         <para>
 224             <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
 225             <constant>GLU_UNSIGNED_INT_10_10_10_2</constant> or <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>
 226             and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
 227         </para>
 228     </refsect1>
 229     <refsect1 id="seealso"><title>See Also</title>
 230         <para>
 231             <citerefentry><refentrytitle>gluBuild1DMipmaps</refentrytitle></citerefentry>,
 232             <citerefentry><refentrytitle>gluBuild2DMipmaps</refentrytitle></citerefentry>,
 233             <citerefentry><refentrytitle>gluBuild3DMipmaps</refentrytitle></citerefentry>,
 234             <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>,
 235             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 236             <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>
 237         </para>
 238     </refsect1>
 239     <refsect1 id="Copyright"><title>Copyright</title>
 240         <para>
 241             Copyright <trademark class="copyright"></trademark> 1991-2006
 242             Silicon Graphics, Inc. This document is licensed under the SGI
 243             Free Software B License. For details, see
 244             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 245         </para>
 246     </refsect1>
 247 </refentry>