upstream-man-pages/man4/glProvokingVertex.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="glProvokingVertex">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glProvokingVertex</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glProvokingVertex</refname>
  17         <refpurpose>specifiy the vertex to be used as the source of data for flat shaded varyings</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glProvokingVertex</function></funcdef>
  23                 <paramdef>GLenum <parameter>provokeMode</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>provokeMode</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies the vertex to be used as the source of data for flat shaded varyings.
  35                 </para>
  36             </listitem>
  37         </varlistentry>
  38         </variablelist>
  39     </refsect1>
  40     <refsect1 id="description"><title>Description</title>
  41         <para>
  42             <emphasis>Flatshading</emphasis> a vertex shader varying output means to assign all vetices of the primitive the same value
  43             for that output. The vertex from which these values is derived is known as the <emphasis>provoking vertex</emphasis> and
  44             <function>glProvokingVertex</function> specifies which vertex is to be used as the source of data for flat shaded varyings.
  45         </para>
  46         <para>
  47             <parameter>provokeMode</parameter> must be either <constant>GL_FIRST_VERTEX_CONVENTION</constant> or
  48             <constant>GL_LAST_VERTEX_CONVENTION</constant>, and controls the selection of the vertex whose values are assigned to flatshaded
  49             varying outputs. The interpretation of these values for the supported primitive types is:
  50             <informaltable frame="topbot">
  51                 <tgroup cols="3" align="left">
  52                     <colspec colwidth="1.1*" />
  53                     <colspec colwidth="1*" />
  54                     <colspec colwidth="1*" />
  55                     <thead>
  56                         <row>
  57                             <entry rowsep="1" align="left"><emphasis role="bold">
  58                             Primitive Type of Polygon <emphasis>i</emphasis>
  59                             </emphasis></entry>
  60                             <entry rowsep="1" align="left"><emphasis role="bold">
  61                             First Vertex Convention
  62                             </emphasis></entry>
  63                             <entry rowsep="1" align="left"><emphasis role="bold">
  64                             Last Vertex Convention
  65                             </emphasis></entry>
  66                         </row>
  67                         <row>
  68                             <entry>
  69                                 point
  70                             </entry>
  71                             <entry>
  72                                 <emphasis>i</emphasis>
  73                             </entry>
  74                             <entry>
  75                                 <emphasis>i</emphasis>
  76                             </entry>
  77                         </row>
  78                         <row>
  79                             <entry>
  80                                 independent line
  81                             </entry>
  82                             <entry>
  83                                 2<emphasis>i</emphasis> - 1
  84                             </entry>
  85                             <entry>
  86                                 2<emphasis>i</emphasis>
  87                             </entry>
  88                         </row>
  89                         <row>
  90                             <entry>
  91                                 line loop
  92                             </entry>
  93                             <entry>
  94                                 <emphasis>i</emphasis>
  95                             </entry>
  96                             <entry>
  97                                 <para>
  98                                 <emphasis>i</emphasis> + 1, if <emphasis>i</emphasis> &lt; <emphasis>n</emphasis>
  99                                 </para>
 100                                 <para>
 101                                 1, if <emphasis>i</emphasis> = <emphasis>n</emphasis>
 102                                 </para>
 103                             </entry>
 104                         </row>
 105                         <row>
 106                             <entry>
 107                                 line strip
 108                             </entry>
 109                             <entry>
 110                                 <emphasis>i</emphasis>
 111                             </entry>
 112                             <entry>
 113                                 <emphasis>i</emphasis> + 1
 114                             </entry>
 115                         </row>
 116                         <row>
 117                             <entry>
 118                                 independent triangle
 119                             </entry>
 120                             <entry>
 121                                 3<emphasis>i</emphasis> - 2
 122                             </entry>
 123                             <entry>
 124                                 3<emphasis>i</emphasis>
 125                             </entry>
 126                         </row>
 127                         <row>
 128                             <entry>
 129                                 triangle strip
 130                             </entry>
 131                             <entry>
 132                                 <emphasis>i</emphasis>
 133                             </entry>
 134                             <entry>
 135                                 <emphasis>i</emphasis> + 2
 136                             </entry>
 137                         </row>
 138                         <row>
 139                             <entry>
 140                                 triangle fan
 141                             </entry>
 142                             <entry>
 143                                 <emphasis>i</emphasis> + 1
 144                             </entry>
 145                             <entry>
 146                                 <emphasis>i</emphasis> + 2
 147                             </entry>
 148                         </row>
 149                         <row>
 150                             <entry>
 151                                 line adjacency
 152                             </entry>
 153                             <entry>
 154                                 4<emphasis>i</emphasis> - 2
 155                             </entry>
 156                             <entry>
 157                                 4<emphasis>i</emphasis> - 1
 158                             </entry>
 159                         </row>
 160                         <row>
 161                             <entry>
 162                                 line strip adjacency
 163                             </entry>
 164                             <entry>
 165                                 <emphasis>i</emphasis> + 1
 166                             </entry>
 167                             <entry>
 168                                 <emphasis>i</emphasis> + 2
 169                             </entry>
 170                         </row>
 171                         <row>
 172                             <entry>
 173                                 triangle adjacency
 174                             </entry>
 175                             <entry>
 176                                 6<emphasis>i</emphasis> - 5
 177                             </entry>
 178                             <entry>
 179                                 6<emphasis>i</emphasis> - 1
 180                             </entry>
 181                         </row>
 182                         <row>
 183                             <entry>
 184                                 triangle strip adjacency
 185                             </entry>
 186                             <entry>
 187                                 2<emphasis>i</emphasis> - 1
 188                             </entry>
 189                             <entry>
 190                                 2<emphasis>i</emphasis> + 3
 191                             </entry>
 192                         </row>
 193                     </thead>
 194                 </tgroup>
 195             </informaltable>
 196         </para>
 197         <para>
 198             If a vertex or geometry shader is active, user-defined varying outputs may be flatshaded by using the
 199             <code>flat</code> qualifier when declaring the output.
 200         </para>
 201     </refsect1>
 202     <refsect1 id="notes"><title>Notes</title>
 203         <para>
 204             <function>glProvokingVertex</function> is available only if the GL version is 3.2 or greater.
 205         </para>
 206     </refsect1>
 207     <refsect1 id="errors"><title>Errors</title>
 208         <para>
 209             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>provokeMode</parameter> is not an accepted value.
 210         </para>
 211     </refsect1>
 212     <refsect1 id="Copyright"><title>Copyright</title>
 213         <para>
 214             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 215             This material may be distributed subject to the terms and conditions set forth in
 216             the Open Publication License, v 1.0, 8 June 1999.
 217             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 218         </para>
 219     </refsect1>
 220 </refentry>