upstream-doc/man2/glColor.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="glColor">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glColor</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glColor</refname>
  17         <refpurpose>set the current color</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glColor3b</function></funcdef>
  23                 <paramdef>GLbyte <parameter>red</parameter></paramdef>
  24                 <paramdef>GLbyte <parameter>green</parameter></paramdef>
  25                 <paramdef>GLbyte <parameter>blue</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glColor3s</function></funcdef>
  31                 <paramdef>GLshort <parameter>red</parameter></paramdef>
  32                 <paramdef>GLshort <parameter>green</parameter></paramdef>
  33                 <paramdef>GLshort <parameter>blue</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36         <funcsynopsis>
  37             <funcprototype>
  38                 <funcdef>void <function>glColor3i</function></funcdef>
  39                 <paramdef>GLint <parameter>red</parameter></paramdef>
  40                 <paramdef>GLint <parameter>green</parameter></paramdef>
  41                 <paramdef>GLint <parameter>blue</parameter></paramdef>
  42             </funcprototype>
  43         </funcsynopsis>
  44         <funcsynopsis>
  45             <funcprototype>
  46                 <funcdef>void <function>glColor3f</function></funcdef>
  47                 <paramdef>GLfloat <parameter>red</parameter></paramdef>
  48                 <paramdef>GLfloat <parameter>green</parameter></paramdef>
  49                 <paramdef>GLfloat <parameter>blue</parameter></paramdef>
  50             </funcprototype>
  51         </funcsynopsis>
  52         <funcsynopsis>
  53             <funcprototype>
  54                 <funcdef>void <function>glColor3d</function></funcdef>
  55                 <paramdef>GLdouble <parameter>red</parameter></paramdef>
  56                 <paramdef>GLdouble <parameter>green</parameter></paramdef>
  57                 <paramdef>GLdouble <parameter>blue</parameter></paramdef>
  58             </funcprototype>
  59         </funcsynopsis>
  60         <funcsynopsis>
  61             <funcprototype>
  62                 <funcdef>void <function>glColor3ub</function></funcdef>
  63                 <paramdef>GLubyte <parameter>red</parameter></paramdef>
  64                 <paramdef>GLubyte <parameter>green</parameter></paramdef>
  65                 <paramdef>GLubyte <parameter>blue</parameter></paramdef>
  66             </funcprototype>
  67         </funcsynopsis>
  68         <funcsynopsis>
  69             <funcprototype>
  70                 <funcdef>void <function>glColor3us</function></funcdef>
  71                 <paramdef>GLushort <parameter>red</parameter></paramdef>
  72                 <paramdef>GLushort <parameter>green</parameter></paramdef>
  73                 <paramdef>GLushort <parameter>blue</parameter></paramdef>
  74             </funcprototype>
  75         </funcsynopsis>
  76         <funcsynopsis>
  77             <funcprototype>
  78                 <funcdef>void <function>glColor3ui</function></funcdef>
  79                 <paramdef>GLuint <parameter>red</parameter></paramdef>
  80                 <paramdef>GLuint <parameter>green</parameter></paramdef>
  81                 <paramdef>GLuint <parameter>blue</parameter></paramdef>
  82             </funcprototype>
  83         </funcsynopsis>
  84         <funcsynopsis>
  85             <funcprototype>
  86                 <funcdef>void <function>glColor4b</function></funcdef>
  87                 <paramdef>GLbyte <parameter>red</parameter></paramdef>
  88                 <paramdef>GLbyte <parameter>green</parameter></paramdef>
  89                 <paramdef>GLbyte <parameter>blue</parameter></paramdef>
  90                 <paramdef>GLbyte <parameter>alpha</parameter></paramdef>
  91             </funcprototype>
  92         </funcsynopsis>
  93         <funcsynopsis>
  94             <funcprototype>
  95                 <funcdef>void <function>glColor4s</function></funcdef>
  96                 <paramdef>GLshort <parameter>red</parameter></paramdef>
  97                 <paramdef>GLshort <parameter>green</parameter></paramdef>
  98                 <paramdef>GLshort <parameter>blue</parameter></paramdef>
  99                 <paramdef>GLshort <parameter>alpha</parameter></paramdef>
 100             </funcprototype>
 101         </funcsynopsis>
 102         <funcsynopsis>
 103             <funcprototype>
 104                 <funcdef>void <function>glColor4i</function></funcdef>
 105                 <paramdef>GLint <parameter>red</parameter></paramdef>
 106                 <paramdef>GLint <parameter>green</parameter></paramdef>
 107                 <paramdef>GLint <parameter>blue</parameter></paramdef>
 108                 <paramdef>GLint <parameter>alpha</parameter></paramdef>
 109             </funcprototype>
 110         </funcsynopsis>
 111         <funcsynopsis>
 112             <funcprototype>
 113                 <funcdef>void <function>glColor4f</function></funcdef>
 114                 <paramdef>GLfloat <parameter>red</parameter></paramdef>
 115                 <paramdef>GLfloat <parameter>green</parameter></paramdef>
 116                 <paramdef>GLfloat <parameter>blue</parameter></paramdef>
 117                 <paramdef>GLfloat <parameter>alpha</parameter></paramdef>
 118             </funcprototype>
 119         </funcsynopsis>
 120         <funcsynopsis>
 121             <funcprototype>
 122                 <funcdef>void <function>glColor4d</function></funcdef>
 123                 <paramdef>GLdouble <parameter>red</parameter></paramdef>
 124                 <paramdef>GLdouble <parameter>green</parameter></paramdef>
 125                 <paramdef>GLdouble <parameter>blue</parameter></paramdef>
 126                 <paramdef>GLdouble <parameter>alpha</parameter></paramdef>
 127             </funcprototype>
 128         </funcsynopsis>
 129         <funcsynopsis>
 130             <funcprototype>
 131                 <funcdef>void <function>glColor4ub</function></funcdef>
 132                 <paramdef>GLubyte <parameter>red</parameter></paramdef>
 133                 <paramdef>GLubyte <parameter>green</parameter></paramdef>
 134                 <paramdef>GLubyte <parameter>blue</parameter></paramdef>
 135                 <paramdef>GLubyte <parameter>alpha</parameter></paramdef>
 136             </funcprototype>
 137         </funcsynopsis>
 138         <funcsynopsis>
 139             <funcprototype>
 140                 <funcdef>void <function>glColor4us</function></funcdef>
 141                 <paramdef>GLushort <parameter>red</parameter></paramdef>
 142                 <paramdef>GLushort <parameter>green</parameter></paramdef>
 143                 <paramdef>GLushort <parameter>blue</parameter></paramdef>
 144                 <paramdef>GLushort <parameter>alpha</parameter></paramdef>
 145             </funcprototype>
 146         </funcsynopsis>
 147         <funcsynopsis>
 148             <funcprototype>
 149                 <funcdef>void <function>glColor4ui</function></funcdef>
 150                 <paramdef>GLuint <parameter>red</parameter></paramdef>
 151                 <paramdef>GLuint <parameter>green</parameter></paramdef>
 152                 <paramdef>GLuint <parameter>blue</parameter></paramdef>
 153                 <paramdef>GLuint <parameter>alpha</parameter></paramdef>
 154             </funcprototype>
 155         </funcsynopsis>
 156     </refsynopsisdiv>
 157     <!-- eqn: ignoring delim $$ -->
 158     <refsect1 id="parameters"><title>Parameters</title>
 159         <variablelist>
 160         <varlistentry>
 161             <term><parameter>red</parameter></term>
 162             <term><parameter>green</parameter></term>
 163             <term><parameter>blue</parameter></term>
 164             <listitem>
 165                 <para>
 166                     Specify new red, green, and blue values for the current color.
 167                 </para>
 168             </listitem>
 169         </varlistentry>
 170         <varlistentry>
 171             <term><parameter>alpha</parameter></term>
 172             <listitem>
 173                 <para>
 174                     Specifies a new alpha value for the current color.
 175                     Included only in the four-argument <function>glColor4</function> commands.
 176                 </para>
 177             </listitem>
 178         </varlistentry>
 179         </variablelist>
 180     </refsect1>
 181     <refsynopsisdiv><title>C Specification</title>
 182         <funcsynopsis>
 183             <funcprototype>
 184                 <funcdef>void <function>glColor3bv</function></funcdef>
 185                 <paramdef>const GLbyte * <parameter>v</parameter></paramdef>
 186             </funcprototype>
 187         </funcsynopsis>
 188         <funcsynopsis>
 189             <funcprototype>
 190                 <funcdef>void <function>glColor3sv</function></funcdef>
 191                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 192             </funcprototype>
 193         </funcsynopsis>
 194         <funcsynopsis>
 195             <funcprototype>
 196                 <funcdef>void <function>glColor3iv</function></funcdef>
 197                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 198             </funcprototype>
 199         </funcsynopsis>
 200         <funcsynopsis>
 201             <funcprototype>
 202                 <funcdef>void <function>glColor3fv</function></funcdef>
 203                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 204             </funcprototype>
 205         </funcsynopsis>
 206         <funcsynopsis>
 207             <funcprototype>
 208                 <funcdef>void <function>glColor3dv</function></funcdef>
 209                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 210             </funcprototype>
 211         </funcsynopsis>
 212         <funcsynopsis>
 213             <funcprototype>
 214                 <funcdef>void <function>glColor3ubv</function></funcdef>
 215                 <paramdef>const GLubyte * <parameter>v</parameter></paramdef>
 216             </funcprototype>
 217         </funcsynopsis>
 218         <funcsynopsis>
 219             <funcprototype>
 220                 <funcdef>void <function>glColor3usv</function></funcdef>
 221                 <paramdef>const GLushort * <parameter>v</parameter></paramdef>
 222             </funcprototype>
 223         </funcsynopsis>
 224         <funcsynopsis>
 225             <funcprototype>
 226                 <funcdef>void <function>glColor3uiv</function></funcdef>
 227                 <paramdef>const GLuint * <parameter>v</parameter></paramdef>
 228             </funcprototype>
 229         </funcsynopsis>
 230         <funcsynopsis>
 231             <funcprototype>
 232                 <funcdef>void <function>glColor4bv</function></funcdef>
 233                 <paramdef>const GLbyte * <parameter>v</parameter></paramdef>
 234             </funcprototype>
 235         </funcsynopsis>
 236         <funcsynopsis>
 237             <funcprototype>
 238                 <funcdef>void <function>glColor4sv</function></funcdef>
 239                 <paramdef>const GLshort * <parameter>v</parameter></paramdef>
 240             </funcprototype>
 241         </funcsynopsis>
 242         <funcsynopsis>
 243             <funcprototype>
 244                 <funcdef>void <function>glColor4iv</function></funcdef>
 245                 <paramdef>const GLint * <parameter>v</parameter></paramdef>
 246             </funcprototype>
 247         </funcsynopsis>
 248         <funcsynopsis>
 249             <funcprototype>
 250                 <funcdef>void <function>glColor4fv</function></funcdef>
 251                 <paramdef>const GLfloat * <parameter>v</parameter></paramdef>
 252             </funcprototype>
 253         </funcsynopsis>
 254         <funcsynopsis>
 255             <funcprototype>
 256                 <funcdef>void <function>glColor4dv</function></funcdef>
 257                 <paramdef>const GLdouble * <parameter>v</parameter></paramdef>
 258             </funcprototype>
 259         </funcsynopsis>
 260         <funcsynopsis>
 261             <funcprototype>
 262                 <funcdef>void <function>glColor4ubv</function></funcdef>
 263                 <paramdef>const GLubyte * <parameter>v</parameter></paramdef>
 264             </funcprototype>
 265         </funcsynopsis>
 266         <funcsynopsis>
 267             <funcprototype>
 268                 <funcdef>void <function>glColor4usv</function></funcdef>
 269                 <paramdef>const GLushort * <parameter>v</parameter></paramdef>
 270             </funcprototype>
 271         </funcsynopsis>
 272         <funcsynopsis>
 273             <funcprototype>
 274                 <funcdef>void <function>glColor4uiv</function></funcdef>
 275                 <paramdef>const GLuint * <parameter>v</parameter></paramdef>
 276             </funcprototype>
 277         </funcsynopsis>
 278     </refsynopsisdiv>
 279     <refsect1 id="parameters2"><title>Parameters</title>
 280         <variablelist>
 281         <varlistentry>
 282             <term><parameter>v</parameter></term>
 283             <listitem>
 284                 <para>
 285                     Specifies a pointer to an array that contains red, green, blue,
 286                     and (sometimes) alpha values.
 287                 </para>
 288             </listitem>
 289         </varlistentry>
 290         </variablelist>
 291     </refsect1>
 292     <refsect1 id="description"><title>Description</title>
 293         <para>
 294             The GL stores both a current single-valued color index
 295             and a current four-valued RGBA color.
 296             <function>glColor</function> sets a new four-valued RGBA color.
 297             <function>glColor</function> has two major variants:
 298             <function>glColor3</function> and <function>glColor4</function>.
 299             <function>glColor3</function> variants specify new red,
 300             green,
 301             and blue values explicitly
 302             and set the current alpha value to 1.0 (full intensity) implicitly.
 303             <function>glColor4</function> variants specify all four color components explicitly.
 304         </para>
 305         <para>
 306             <function>glColor3b</function>, <function>glColor4b</function>,
 307             <function>glColor3s</function>, <function>glColor4s</function>, <function>glColor3i</function>, and <function>glColor4i</function> take
 308             three or four signed byte, short, or long integers as arguments.
 309             When <emphasis role="bold">v</emphasis> is appended to the name,
 310             the color commands can take a pointer to an array of such values.
 311         </para>
 312         <para>
 313             Current color values are stored in floating-point format,
 314             with unspecified mantissa and exponent sizes.
 315             Unsigned integer color components,
 316             when specified,
 317             are linearly mapped to floating-point values such that the largest
 318             representable value maps to 1.0 (full intensity),
 319             and 0 maps to 0.0 (zero intensity).
 320             Signed integer color components,
 321             when specified,
 322             are linearly mapped to floating-point values such that the most positive
 323             representable value maps to 1.0,
 324             and the most negative representable value maps to
 325             <inlineequation><mml:math>
 326                 <!-- eqn: -1.0:-->
 327                 <mml:mn>-1.0</mml:mn>
 328             </mml:math></inlineequation>.
 329             (Note that
 330             this mapping does not convert 0 precisely to 0.0.)
 331             Floating-point values are mapped directly.
 332         </para>
 333         <para>
 334             Neither floating-point nor signed integer values are clamped
 335             to the range
 336             <inlineequation><mml:math>
 337                 <!-- eqn: [0,1]:-->
 338                 <mml:mfenced open="[" close="]">
 339                     <mml:mn>0</mml:mn>
 340                     <mml:mn>1</mml:mn>
 341                 </mml:mfenced>
 342             </mml:math></inlineequation>
 343             before the current color is updated.
 344             However,
 345             color components are clamped to this range before they are interpolated
 346             or written into a color buffer.
 347         </para>
 348     </refsect1>
 349     <refsect1 id="notes"><title>Notes</title>
 350         <para>
 351             The initial value for the current color is (1, 1, 1, 1).
 352         </para>
 353         <para>
 354             The current color can be updated at any time.
 355             In particular,
 356             <function>glColor</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 357             call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 358         </para>
 359     </refsect1>
 360     <refsect1 id="associatedgets"><title>Associated Gets</title>
 361         <para>
 362             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_CURRENT_COLOR</constant>
 363         </para>
 364         <para>
 365             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_RGBA_MODE</constant>
 366         </para>
 367     </refsect1>
 368     <refsect1 id="seealso"><title>See Also</title>
 369         <para>
 370             <function>glColorPointer</function>,
 371             <citerefentry><refentrytitle>glIndex</refentrytitle></citerefentry>,
 372             <citerefentry><refentrytitle>glSecondaryColor</refentrytitle></citerefentry>
 373         </para>
 374     </refsect1>
 375     <refsect1 id="Copyright"><title>Copyright</title>
 376         <para>
 377             Copyright <trademark class="copyright"></trademark> 1991-2006
 378             Silicon Graphics, Inc. This document is licensed under the SGI
 379             Free Software B License. For details, see
 380             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 381         </para>
 382     </refsect1>
 383 </refentry>