upstream-man-pages/man2/glShadeModel.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="glShadeModel">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glShadeModel</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glShadeModel</refname>
  17         <refpurpose>select flat or smooth shading</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glShadeModel</function></funcdef>
  23                 <paramdef>GLenum <parameter>mode</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <!-- eqn: ignoring delim $$ -->
  28     <refsect1 id="parameters"><title>Parameters</title>
  29         <variablelist>
  30         <varlistentry>
  31             <term><parameter>mode</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies a symbolic value representing a shading technique.
  35                     Accepted values are <constant>GL_FLAT</constant> and <constant>GL_SMOOTH</constant>.
  36                     The initial value is <constant>GL_SMOOTH</constant>.
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         </variablelist>
  41     </refsect1>
  42     <refsect1 id="description"><title>Description</title>
  43         <para>
  44             GL primitives can have either flat or smooth shading.
  45             Smooth shading,
  46             the default,
  47             causes the computed colors of vertices to be interpolated as the
  48             primitive is rasterized,
  49             typically assigning different colors to each resulting pixel fragment.
  50             Flat shading selects the computed color of just one vertex
  51             and assigns it to all the pixel fragments
  52             generated by rasterizing a single primitive.
  53             In either case, the computed color of a vertex is the result of
  54             lighting if lighting is enabled,
  55             or it is the current color at the time the vertex was specified if
  56             lighting is disabled.
  57         </para>
  58         <para>
  59             Flat and smooth shading are indistinguishable for points.
  60             Starting when <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> is issued and counting vertices and
  61             primitives from 1, the GL gives each flat-shaded line segment
  62             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
  63             the
  64             computed color of vertex
  65             <inlineequation><mml:math>
  66                 <!-- eqn: i  +  1:-->
  67                 <mml:mrow>
  68                     <mml:mi mathvariant="italic">i</mml:mi>
  69                     <mml:mo>+</mml:mo>
  70                     <mml:mn>1</mml:mn>
  71                 </mml:mrow>
  72             </mml:math></inlineequation>,
  73             its second vertex.
  74             Counting similarly from 1,
  75             the GL gives each flat-shaded polygon the computed color of the vertex listed
  76             in the following table.
  77             This is the last vertex to specify the polygon in all cases except single
  78             polygons,
  79             where the first vertex specifies the flat-shaded color.
  80         </para>
  81         <para>
  82         </para>
  83         <informaltable frame="topbot">
  84             <tgroup cols="2" align="left">
  85                 <colspec/>
  86                 <colspec align="center"/>
  87                 <thead>
  88                     <row>
  89                         <entry rowsep="1" align="left"><emphasis role="bold">
  90                         Primitive Type of Polygon
  91                         <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
  92                         </emphasis></entry>
  93                         <entry rowsep="1" align="center"><emphasis role="bold">
  94                         Vertex
  95                         </emphasis></entry>
  96                     </row>
  97                 </thead>
  98                 <tbody>
  99                     <row>
 100                         <entry align="left">
 101                         Single polygon
 102                         (<inlineequation><mml:math>
 103                             <!-- eqn: i  ==  1:-->
 104                             <mml:mrow>
 105                                 <mml:mi mathvariant="italic">i</mml:mi>
 106                                 <mml:mo>==</mml:mo>
 107                                 <mml:mn>1</mml:mn>
 108                             </mml:mrow>
 109                         </mml:math></inlineequation>)
 110                         </entry>
 111                         <entry align="center">
 112                         1
 113                         </entry>
 114                     </row>
 115                     <row>
 116                         <entry align="left">
 117                         Triangle strip
 118                         </entry>
 119                         <entry align="center">
 120                         <inlineequation><mml:math>
 121                             <!-- eqn: i  +  2:-->
 122                             <mml:mrow>
 123                                 <mml:mi mathvariant="italic">i</mml:mi>
 124                                 <mml:mo>+</mml:mo>
 125                                 <mml:mn>2</mml:mn>
 126                             </mml:mrow>
 127                         </mml:math></inlineequation>
 128                         </entry>
 129                     </row>
 130                     <row>
 131                         <entry align="left">
 132                         Triangle fan
 133                         </entry>
 134                         <entry align="center">
 135                         <inlineequation><mml:math>
 136                             <!-- eqn: i  +  2:-->
 137                             <mml:mrow>
 138                                 <mml:mi mathvariant="italic">i</mml:mi>
 139                                 <mml:mo>+</mml:mo>
 140                                 <mml:mn>2</mml:mn>
 141                             </mml:mrow>
 142                         </mml:math></inlineequation>
 143                         </entry>
 144                     </row>
 145                     <row>
 146                         <entry align="left">
 147                         Independent triangle
 148                         </entry>
 149                         <entry align="center">
 150                         <inlineequation><mml:math>
 151                             <!-- eqn: 3 i:-->
 152                             <mml:mrow>
 153                                 <mml:mn>3</mml:mn>
 154                                 <mml:mo>&it;</mml:mo>
 155                                 <mml:mi mathvariant="italic">i</mml:mi>
 156                             </mml:mrow>
 157                         </mml:math></inlineequation>
 158                         </entry>
 159                     </row>
 160                     <row>
 161                         <entry align="left">
 162                         Quad strip
 163                         </entry>
 164                         <entry align="center">
 165                         <inlineequation><mml:math>
 166                             <!-- eqn: 2 i  +  2:-->
 167                             <mml:mrow>
 168                                 <mml:mn>2</mml:mn>
 169                                 <mml:mo>&it;</mml:mo>
 170                                 <mml:mi mathvariant="italic">i</mml:mi>
 171                                 <mml:mo>+</mml:mo>
 172                                 <mml:mn>2</mml:mn>
 173                             </mml:mrow>
 174                         </mml:math></inlineequation>
 175                         </entry>
 176                     </row>
 177                     <row>
 178                         <entry align="left">
 179                         Independent quad
 180                         </entry>
 181                         <entry align="center">
 182                         <inlineequation><mml:math>
 183                             <!-- eqn: 4 i:-->
 184                             <mml:mrow>
 185                                 <mml:mn>4</mml:mn>
 186                                 <mml:mo>&it;</mml:mo>
 187                                 <mml:mi mathvariant="italic">i</mml:mi>
 188                             </mml:mrow>
 189                         </mml:math></inlineequation>
 190                         </entry>
 191                     </row>
 192                 </tbody>
 193             </tgroup>
 194         </informaltable>
 195         <para>
 196             Flat and smooth shading are specified by <function>glShadeModel</function> with <parameter>mode</parameter> set to
 197             <constant>GL_FLAT</constant> and <constant>GL_SMOOTH</constant>, respectively.
 198         </para>
 199     </refsect1>
 200     <refsect1 id="errors"><title>Errors</title>
 201         <para>
 202             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is any value other than
 203             <constant>GL_FLAT</constant> or <constant>GL_SMOOTH</constant>.
 204         </para>
 205         <para>
 206             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glShadeModel</function>
 207             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 208             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 209         </para>
 210     </refsect1>
 211     <refsect1 id="associatedgets"><title>Associated Gets</title>
 212         <para>
 213             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_SHADE_MODEL</constant>
 214         </para>
 215     </refsect1>
 216     <refsect1 id="seealso"><title>See Also</title>
 217         <para>
 218             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
 219             <citerefentry><refentrytitle>glColor</refentrytitle></citerefentry>,
 220             <citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>,
 221             <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
 222         </para>
 223     </refsect1>
 224     <refsect1 id="Copyright"><title>Copyright</title>
 225         <para>
 226             Copyright <trademark class="copyright"></trademark> 1991-2006
 227             Silicon Graphics, Inc. This document is licensed under the SGI
 228             Free Software B License. For details, see
 229             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 230         </para>
 231     </refsect1>
 232 </refentry>