<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="gluScaleImage">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>gluScaleImage</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>gluScaleImage</refname>
        <refpurpose>scale an image to an arbitrary size</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>GLint <function>gluScaleImage</function></funcdef>
                <paramdef>GLenum <parameter>format</parameter></paramdef>
                <paramdef>GLsizei <parameter>wIn</parameter></paramdef>
                <paramdef>GLsizei <parameter>hIn</parameter></paramdef>
                <paramdef>GLenum <parameter>typeIn</parameter></paramdef>
                <paramdef>const void * <parameter>dataIn</parameter></paramdef>
                <paramdef>GLsizei <parameter>wOut</parameter></paramdef>
                <paramdef>GLsizei <parameter>hOut</parameter></paramdef>
                <paramdef>GLenum <parameter>typeOut</parameter></paramdef>
                <paramdef>GLvoid* <parameter>dataOut</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>format</parameter></term>
            <listitem>
                <para>
                    Specifies the format of the pixel data.
                    The following symbolic values are valid:
                    <constant>GLU_COLOR_INDEX</constant>,
                    <constant>GLU_STENCIL_INDEX</constant>,
                    <constant>GLU_DEPTH_COMPONENT</constant>,
                    <constant>GLU_RED</constant>,
                    <constant>GLU_GREEN</constant>,
                    <constant>GLU_BLUE</constant>,
                    <constant>GLU_ALPHA</constant>,
                    <constant>GLU_RGB</constant>,
                    <constant>GLU_RGBA</constant>,
                    <constant>GLU_BGR</constant>,
                    <constant>GLU_BGRA</constant>,
                    <constant>GLU_LUMINANCE</constant>, and
                    <constant>GLU_LUMINANCE_ALPHA</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>wIn</parameter></term>
            <term><parameter>hIn</parameter></term>
            <listitem>
                <para>
                    Specify in pixels the width and height, respectively, of the source image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>typeIn</parameter></term>
            <listitem>
                <para>
                    Specifies the data type for <parameter>dataIn</parameter>. Must be one of
                    <constant>GLU_UNSIGNED_BYTE</constant>,
                    <constant>GLU_BYTE</constant>,
                    <constant>GLU_BITMAP</constant>,
                    <constant>GLU_UNSIGNED_SHORT</constant>,
                    <constant>GLU_SHORT</constant>,
                    <constant>GLU_UNSIGNED_INT</constant>,
                    <constant>GLU_INT</constant>, 
                    <constant>GLU_FLOAT</constant>, 
                    <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
                    <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
                    <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
                    <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
                    <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
                    <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
                    <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, or
                    <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>dataIn</parameter></term>
            <listitem>
                <para>
                    Specifies a pointer to the source image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>wOut</parameter></term>
            <term><parameter>hOut</parameter></term>
            <listitem>
                <para>
                    Specify the width and height, respectively, in pixels of the destination image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>typeOut</parameter></term>
            <listitem>
                <para>
                    Specifies the data type for <parameter>dataOut</parameter>. Must be one of
                    <constant>GLU_UNSIGNED_BYTE</constant>,
                    <constant>GLU_BYTE</constant>,
                    <constant>GLU_BITMAP</constant>,
                    <constant>GLU_UNSIGNED_SHORT</constant>,
                    <constant>GLU_SHORT</constant>,
                    <constant>GLU_UNSIGNED_INT</constant>,
                    <constant>GLU_INT</constant>, 
                    <constant>GLU_FLOAT</constant>,
                    <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
                    <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
                    <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
                    <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
                    <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
                    <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
                    <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
                    <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, or
                    <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>dataOut</parameter></term>
            <listitem>
                <para>
                    Specifies a pointer to the destination image.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>gluScaleImage</function> scales a pixel image using the appropriate pixel store modes to 
            unpack data from the source image and pack data into the destination image.
        </para>
        <para>
            When shrinking an image, <function>gluScaleImage</function> uses a box filter to sample the source image
            and create pixels for the destination image.  When magnifying an image,
            the pixels from the source image are linearly interpolated to create the
            destination image.
        </para>
        <para>
            A return value of zero indicates success, otherwise a GLU error code is returned (see <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>).
        </para>
        <para>
            See the <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> reference page for a description of
            the acceptable values for the <parameter>format</parameter>, <parameter>typeIn</parameter>, and <parameter>typeOut</parameter> parameters.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            Formats <constant>GLU_BGR</constant>, and <constant>GLU_BGRA</constant>, and types 
            <constant>GLU_UNSIGNED_BYTE_3_3_2</constant>,
            <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant>,
            <constant>GLU_UNSIGNED_SHORT_5_6_5</constant>,
            <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant>,
            <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant>,
            <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
            <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant>,
            <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
            <constant>GLU_UNSIGNED_INT_8_8_8_8</constant>,
            <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant>,
            <constant>GLU_UNSIGNED_INT_10_10_10_2</constant>, and
            <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant> are only available if the GL version 
            is 1.2 or greater.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GLU_INVALID_VALUE</constant> is returned if <parameter>wIn</parameter>, <parameter>hIn</parameter>, <parameter>wOut</parameter>, or <parameter>hOut</parameter>
            is negative.
        </para>
        <para>
            <constant>GLU_INVALID_ENUM</constant> is returned if <parameter>format</parameter>, <parameter>typeIn</parameter>, or <parameter>typeOut</parameter> is not
            legal.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is 
            <constant>GLU_UNSIGNED_BYTE_3_3_2</constant> or <constant>GLU_UNSIGNED_BYTE_2_3_3_REV</constant> 
            and <parameter>format</parameter> is not <constant>GLU_RGB</constant>.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is 
            <constant>GLU_UNSIGNED_SHORT_5_6_5</constant> or <constant>GLU_UNSIGNED_SHORT_5_6_5_REV</constant> 
            and <parameter>format</parameter> is not <constant>GLU_RGB</constant>.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
            <constant>GLU_UNSIGNED_SHORT_4_4_4_4</constant> or <constant>GLU_UNSIGNED_SHORT_4_4_4_4_REV</constant> 
            and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
            <constant>GLU_UNSIGNED_SHORT_5_5_5_1</constant> or <constant>GLU_UNSIGNED_SHORT_1_5_5_5_REV</constant>
            and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
            <constant>GLU_UNSIGNED_INT_8_8_8_8</constant> or <constant>GLU_UNSIGNED_INT_8_8_8_8_REV</constant> 
            and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
        </para>
        <para>
            <constant>GLU_INVALID_OPERATION</constant> is returned if <parameter>typeIn</parameter> or <parameter>typeOut</parameter> is
            <constant>GLU_UNSIGNED_INT_10_10_10_2</constant> or <constant>GLU_UNSIGNED_INT_2_10_10_10_REV</constant>
            and <parameter>format</parameter> is neither <constant>GLU_RGBA</constant> nor <constant>GLU_BGRA</constant>.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>gluBuild1DMipmaps</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluBuild2DMipmaps</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluBuild3DMipmaps</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
