Blame |
Last modification |
View Log
| RSS feed
<?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>