glColor.xml

<?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="glColor">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glColor</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glColor</refname>
        <refpurpose>set the current color</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3b</function></funcdef>
                <paramdef>GLbyte <parameter>red</parameter></paramdef>
                <paramdef>GLbyte <parameter>green</parameter></paramdef>
                <paramdef>GLbyte <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3s</function></funcdef>
                <paramdef>GLshort <parameter>red</parameter></paramdef>
                <paramdef>GLshort <parameter>green</parameter></paramdef>
                <paramdef>GLshort <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3i</function></funcdef>
                <paramdef>GLint <parameter>red</parameter></paramdef>
                <paramdef>GLint <parameter>green</parameter></paramdef>
                <paramdef>GLint <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3f</function></funcdef>
                <paramdef>GLfloat <parameter>red</parameter></paramdef>
                <paramdef>GLfloat <parameter>green</parameter></paramdef>
                <paramdef>GLfloat <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3d</function></funcdef>
                <paramdef>GLdouble <parameter>red</parameter></paramdef>
                <paramdef>GLdouble <parameter>green</parameter></paramdef>
                <paramdef>GLdouble <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3ub</function></funcdef>
                <paramdef>GLubyte <parameter>red</parameter></paramdef>
                <paramdef>GLubyte <parameter>green</parameter></paramdef>
                <paramdef>GLubyte <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3us</function></funcdef>
                <paramdef>GLushort <parameter>red</parameter></paramdef>
                <paramdef>GLushort <parameter>green</parameter></paramdef>
                <paramdef>GLushort <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3ui</function></funcdef>
                <paramdef>GLuint <parameter>red</parameter></paramdef>
                <paramdef>GLuint <parameter>green</parameter></paramdef>
                <paramdef>GLuint <parameter>blue</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4b</function></funcdef>
                <paramdef>GLbyte <parameter>red</parameter></paramdef>
                <paramdef>GLbyte <parameter>green</parameter></paramdef>
                <paramdef>GLbyte <parameter>blue</parameter></paramdef>
                <paramdef>GLbyte <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4s</function></funcdef>
                <paramdef>GLshort <parameter>red</parameter></paramdef>
                <paramdef>GLshort <parameter>green</parameter></paramdef>
                <paramdef>GLshort <parameter>blue</parameter></paramdef>
                <paramdef>GLshort <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4i</function></funcdef>
                <paramdef>GLint <parameter>red</parameter></paramdef>
                <paramdef>GLint <parameter>green</parameter></paramdef>
                <paramdef>GLint <parameter>blue</parameter></paramdef>
                <paramdef>GLint <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4f</function></funcdef>
                <paramdef>GLfloat <parameter>red</parameter></paramdef>
                <paramdef>GLfloat <parameter>green</parameter></paramdef>
                <paramdef>GLfloat <parameter>blue</parameter></paramdef>
                <paramdef>GLfloat <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4d</function></funcdef>
                <paramdef>GLdouble <parameter>red</parameter></paramdef>
                <paramdef>GLdouble <parameter>green</parameter></paramdef>
                <paramdef>GLdouble <parameter>blue</parameter></paramdef>
                <paramdef>GLdouble <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4ub</function></funcdef>
                <paramdef>GLubyte <parameter>red</parameter></paramdef>
                <paramdef>GLubyte <parameter>green</parameter></paramdef>
                <paramdef>GLubyte <parameter>blue</parameter></paramdef>
                <paramdef>GLubyte <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4us</function></funcdef>
                <paramdef>GLushort <parameter>red</parameter></paramdef>
                <paramdef>GLushort <parameter>green</parameter></paramdef>
                <paramdef>GLushort <parameter>blue</parameter></paramdef>
                <paramdef>GLushort <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4ui</function></funcdef>
                <paramdef>GLuint <parameter>red</parameter></paramdef>
                <paramdef>GLuint <parameter>green</parameter></paramdef>
                <paramdef>GLuint <parameter>blue</parameter></paramdef>
                <paramdef>GLuint <parameter>alpha</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>red</parameter></term>
            <term><parameter>green</parameter></term>
            <term><parameter>blue</parameter></term>
            <listitem>
                <para>
                    Specify new red, green, and blue values for the current color.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>alpha</parameter></term>
            <listitem>
                <para>
                    Specifies a new alpha value for the current color.
                    Included only in the four-argument <function>glColor4</function> commands.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3bv</function></funcdef>
                <paramdef>const GLbyte * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3sv</function></funcdef>
                <paramdef>const GLshort * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3iv</function></funcdef>
                <paramdef>const GLint * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3fv</function></funcdef>
                <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3dv</function></funcdef>
                <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3ubv</function></funcdef>
                <paramdef>const GLubyte * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3usv</function></funcdef>
                <paramdef>const GLushort * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor3uiv</function></funcdef>
                <paramdef>const GLuint * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4bv</function></funcdef>
                <paramdef>const GLbyte * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4sv</function></funcdef>
                <paramdef>const GLshort * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4iv</function></funcdef>
                <paramdef>const GLint * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4fv</function></funcdef>
                <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4dv</function></funcdef>
                <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4ubv</function></funcdef>
                <paramdef>const GLubyte * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4usv</function></funcdef>
                <paramdef>const GLushort * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glColor4uiv</function></funcdef>
                <paramdef>const GLuint * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters2"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>v</parameter></term>
            <listitem>
                <para>
                    Specifies a pointer to an array that contains red, green, blue,
                    and (sometimes) alpha values.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            The GL stores both a current single-valued color index
            and a current four-valued RGBA color.
            <function>glColor</function> sets a new four-valued RGBA color.
            <function>glColor</function> has two major variants:
            <function>glColor3</function> and <function>glColor4</function>.
            <function>glColor3</function> variants specify new red,
            green,
            and blue values explicitly
            and set the current alpha value to 1.0 (full intensity) implicitly.
            <function>glColor4</function> variants specify all four color components explicitly.
        </para>
        <para>
            <function>glColor3b</function>, <function>glColor4b</function>,
            <function>glColor3s</function>, <function>glColor4s</function>, <function>glColor3i</function>, and <function>glColor4i</function> take
            three or four signed byte, short, or long integers as arguments.
            When <emphasis role="bold">v</emphasis> is appended to the name,
            the color commands can take a pointer to an array of such values.
        </para>
        <para>
            Current color values are stored in floating-point format,
            with unspecified mantissa and exponent sizes.
            Unsigned integer color components,
            when specified,
            are linearly mapped to floating-point values such that the largest
            representable value maps to 1.0 (full intensity),
            and 0 maps to 0.0 (zero intensity).
            Signed integer color components,
            when specified,
            are linearly mapped to floating-point values such that the most positive
            representable value maps to 1.0,
            and the most negative representable value maps to 
            <inlineequation><mml:math>
                <!-- eqn: -1.0:-->
                <mml:mn>-1.0</mml:mn>
            </mml:math></inlineequation>.
            (Note that
            this mapping does not convert 0 precisely to 0.0.)
            Floating-point values are mapped directly.
        </para>
        <para>
            Neither floating-point nor signed integer values are clamped
            to the range 
            <inlineequation><mml:math>
                <!-- eqn: [0,1]:-->
                <mml:mfenced open="[" close="]">
                    <mml:mn>0</mml:mn>
                    <mml:mn>1</mml:mn>
                </mml:mfenced>
            </mml:math></inlineequation>
            before the current color is updated.
            However,
            color components are clamped to this range before they are interpolated
            or written into a color buffer.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            The initial value for the current color is (1, 1, 1, 1).
        </para>
        <para>
            The current color can be updated at any time.
            In particular,
            <function>glColor</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
            call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_COLOR</constant>
        </para>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_RGBA_MODE</constant>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <function>glColorPointer</function>,
            <citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glSecondaryColor</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>