upstream-doc/man2/glColorMaterial.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="glColorMaterial">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glColorMaterial</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glColorMaterial</refname>
  17         <refpurpose>cause a material color to track the current color</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glColorMaterial</function></funcdef>
  23                 <paramdef>GLenum <parameter>face</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>mode</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <refsect1 id="parameters"><title>Parameters</title>
  29         <variablelist>
  30         <varlistentry>
  31             <term><parameter>face</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies whether front,
  35                     back,
  36                     or both front and back material parameters should track the current color.
  37                     Accepted values are
  38                     <constant>GL_FRONT</constant>,
  39                     <constant>GL_BACK</constant>,
  40                     and <constant>GL_FRONT_AND_BACK</constant>.
  41                     The initial value is <constant>GL_FRONT_AND_BACK</constant>.
  42                 </para>
  43             </listitem>
  44         </varlistentry>
  45         <varlistentry>
  46             <term><parameter>mode</parameter></term>
  47             <listitem>
  48                 <para>
  49                     Specifies which of several material parameters track the current color.
  50                     Accepted values are
  51                     <constant>GL_EMISSION</constant>,
  52                     <constant>GL_AMBIENT</constant>,
  53                     <constant>GL_DIFFUSE</constant>,
  54                     <constant>GL_SPECULAR</constant>,
  55                     and <constant>GL_AMBIENT_AND_DIFFUSE</constant>.
  56                     The initial value is <constant>GL_AMBIENT_AND_DIFFUSE</constant>.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         </variablelist>
  61     </refsect1>
  62     <refsect1 id="description"><title>Description</title>
  63         <para>
  64             <function>glColorMaterial</function> specifies which material parameters track the current color.
  65             When <constant>GL_COLOR_MATERIAL</constant> is enabled,
  66             the material parameter or parameters specified by <parameter>mode</parameter>,
  67             of the material or materials specified by <parameter>face</parameter>,
  68             track the current color at all times.
  69         </para>
  70         <para>
  71             To enable and disable <constant>GL_COLOR_MATERIAL</constant>, call
  72             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL</constant>.
  73             <constant>GL_COLOR_MATERIAL</constant> is initially disabled.
  74         </para>
  75     </refsect1>
  76     <refsect1 id="notes"><title>Notes</title>
  77         <para>
  78             <function>glColorMaterial</function> makes it possible to change a subset of material parameters for each
  79             vertex using only the <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry> command,
  80             without calling <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>.
  81             If only such a subset of parameters is to be specified for each
  82             vertex, calling <function>glColorMaterial</function> is preferable to calling <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>.
  83         </para>
  84         <para>
  85             Call <function>glColorMaterial</function> before enabling <constant>GL_COLOR_MATERIAL</constant>.
  86         </para>
  87         <para>
  88             Calling <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>
  89             may leave the current color indeterminate, if the color array is enabled.
  90             If
  91             <function>glColorMaterial</function> is enabled while the current color is indeterminate, the
  92             lighting material state specified by <parameter>face</parameter> and <parameter>mode</parameter> is also indeterminate.
  93         </para>
  94         <para>
  95             If the GL version is 1.1 or greater, and <constant>GL_COLOR_MATERIAL</constant> is
  96             enabled, evaluated color values affect the results of the lighting
  97             equation as if the current color were being modified, but no change is
  98             made to the tracking lighting parameter of the current color.
  99         </para>
 100     </refsect1>
 101     <refsect1 id="errors"><title>Errors</title>
 102         <para>
 103             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>face</parameter> or <parameter>mode</parameter> is not an
 104             accepted value.
 105         </para>
 106         <para>
 107             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glColorMaterial</function> is executed between
 108             the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 109         </para>
 110     </refsect1>
 111     <refsect1 id="associatedgets"><title>Associated Gets</title>
 112         <para>
 113             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL</constant>
 114         </para>
 115         <para>
 116             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL_PARAMETER</constant>
 117         </para>
 118         <para>
 119             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_COLOR_MATERIAL_FACE</constant>
 120         </para>
 121     </refsect1>
 122     <refsect1 id="seealso"><title>See Also</title>
 123         <para>
 124             <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
 125             <citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
 126             <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
 127             <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
 128             <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
 129             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 130             <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>,
 131             <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>,
 132             <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
 133         </para>
 134     </refsect1>
 135     <refsect1 id="Copyright"><title>Copyright</title>
 136         <para>
 137             Copyright <trademark class="copyright"></trademark> 1991-2006
 138             Silicon Graphics, Inc. This document is licensed under the SGI
 139             Free Software B License. For details, see
 140             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 141         </para>
 142     </refsect1>
 143 </refentry>