upstream-doc/man4/glBeginTransformFeedback.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="glBeginTransformFeedback">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2010</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glBeginTransformFeedback</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glBeginTransformFeedback</refname>
  17         <refpurpose>start transform feedback operation</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glBeginTransformFeedback</function></funcdef>
  23                 <paramdef>GLenum <parameter>primitiveMode</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29         <varlistentry>
  30             <term><parameter>primitiveMode</parameter></term>
  31             <listitem>
  32                 <para>
  33                     Specify the output type of the primitives that will be recorded into the
  34                     buffer objects that are bound for transform feedback.
  35                 </para>
  36             </listitem>
  37         </varlistentry>
  38         </variablelist>
  39     </refsect1>
  40     <refsynopsisdiv><title>C Specification</title>
  41         <funcsynopsis>
  42             <funcprototype>
  43                 <funcdef>void <function>glEndTransformFeedback</function></funcdef>
  44                 <paramdef><parameter>void</parameter></paramdef>
  45             </funcprototype>
  46         </funcsynopsis>
  47     </refsynopsisdiv>
  48     <refsect1 id="description"><title>Description</title>
  49         <para>
  50             Transform feedback mode captures the values of varying variables written by the vertex shader (or, if active, the geometry shader).
  51             Transform feedback is said to be active after a call to <function>glBeginTransformFeedback</function>
  52             until a subsequent call to <citerefentry><refentrytitle>glEndTransformFeedback</refentrytitle></citerefentry>.
  53             Transform feedback commands must be paired.
  54         </para>
  55         <para>
  56             If no geometry shader is present, while transform feedback is active the <parameter>mode</parameter> parameter to
  57             <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry> must match those specified
  58             in the following table:
  59         </para>
  60         <informaltable frame="topbot">
  61             <tgroup cols="2" align="left">
  62                 <colspec colwidth="1.1*" />
  63                 <colspec colwidth="1*" />
  64                 <thead>
  65                     <row>
  66                         <entry rowsep="1" align="left"><emphasis role="bold">
  67                         Transform Feedback <parameter>primitiveMode</parameter>
  68                         </emphasis></entry>
  69                         <entry rowsep="1" align="left"><emphasis role="bold">
  70                         Allowed Render Primitive <parameter>modes</parameter>
  71                         </emphasis></entry>
  72                     </row>
  73                 </thead>
  74                 <tbody>
  75                     <row>
  76                         <entry align="left">
  77                         <constant>GL_POINTS</constant>
  78                         </entry>
  79                         <entry align="left">
  80                         <constant>GL_POINTS</constant>
  81                         </entry>
  82                     </row>
  83                     <row>
  84                         <entry align="left">
  85                         <constant>GL_LINES</constant>
  86                         </entry>
  87                         <entry align="left">
  88                         <constant>GL_LINES</constant>, <constant>GL_LINE_LOOP</constant>, <constant>GL_LINE_STRIP</constant>,
  89                         <constant>GL_LINES_ADJACENCY</constant>, <constant>GL_LINE_STRIP_ADJACENCY</constant>
  90                         </entry>
  91                     </row>
  92                     <row>
  93                         <entry align="left">
  94                         <constant>GL_TRIANGLES</constant>
  95                         </entry>
  96                         <entry align="left">
  97                         <constant>GL_TRIANGLES</constant>, <constant>GL_TRIANGLE_STRIP</constant>, <constant>GL_TRIANGLE_FAN</constant>,
  98                         <constant>GL_TRIANGLES_ADJACENCY</constant>, <constant>GL_TRIANGLE_STRIP_ADJACENCY</constant>
  99                         </entry>
 100                     </row>
 101                 </tbody>
 102             </tgroup>
 103         </informaltable>
 104         <para>
 105             If a geometry shader is present, the output primitive type from the geometry shader must match those
 106             provided in the following table:
 107         <informaltable frame="topbot">
 108             <tgroup cols="2" align="left">
 109                 <colspec colwidth="1.1*" />
 110                 <colspec colwidth="1*" />
 111                 <thead>
 112                     <row>
 113                         <entry rowsep="1" align="left"><emphasis role="bold">
 114                         Transform Feedback <parameter>primitiveMode</parameter>
 115                         </emphasis></entry>
 116                         <entry rowsep="1" align="left"><emphasis role="bold">
 117                         Allowed Geometry Shader Output Primitive Type
 118                         </emphasis></entry>
 119                     </row>
 120                 </thead>
 121                 <tbody>
 122                     <row>
 123                         <entry align="left">
 124                         <constant>GL_POINTS</constant>
 125                         </entry>
 126                         <entry align="left">
 127                         <constant>points</constant>
 128                         </entry>
 129                     </row>
 130                     <row>
 131                         <entry align="left">
 132                         <constant>GL_LINES</constant>
 133                         </entry>
 134                         <entry align="left">
 135                         <constant>line_strip</constant>
 136                         </entry>
 137                     </row>
 138                     <row>
 139                         <entry align="left">
 140                         <constant>GL_TRIANGLES</constant>
 141                         </entry>
 142                         <entry align="left">
 143                         <constant>triangle_strip</constant>
 144                         </entry>
 145                     </row>
 146                 </tbody>
 147             </tgroup>
 148         </informaltable>
 149         </para>
 150     </refsect1>
 151     <refsect1 id="notes"><title>Notes</title>
 152         <para>
 153             Geometry shaders, and the <constant>GL_TRIANGLES_ADJACENCY</constant>, <constant>GL_TRIANGLE_STRIP_ADJACENCY</constant>,
 154             <constant>GL_LINES_ADJACENCY</constant> and <constant>GL_LINE_STRIP_ADJACENCY</constant> primtive modes are available
 155             only if the GL version is 3.2 or greater.
 156         </para>
 157     </refsect1>
 158     <refsect1 id="errors"><title>Errors</title>
 159         <para>
 160             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginTransformFeedback</function> is executed
 161             while transform feedback is active.
 162         </para>
 163         <para>
 164             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glEndTransformFeedback</function> is executed
 165             while transform feedback is not active.
 166         </para>
 167         <para>
 168             <constant>GL_INVALID_OPERATION</constant> is generated by <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>
 169             if no geometry shader is present, transform feedback is active and <parameter>mode</parameter> is not one of the allowed modes.
 170         </para>
 171         <para>
 172             <constant>GL_INVALID_OPERATION</constant> is generated by <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>
 173             if a geometry shader is present, transform feedback is active and the output primitive type of the geometry shader does not
 174             match the transform feedback <parameter>primitiveMode</parameter>.
 175         </para>
 176         <para>
 177             <constant>GL_INVALID_OPERATION</constant> is generated by <function>glEndTransformFeedback</function> if any binding
 178             point used in transform feedback mode does not have a buffer object bound.
 179         </para>
 180         <para>
 181             <constant>GL_INVALID_OPERATION</constant> is generated by <function>glEndTransformFeedback</function> if no binding
 182             points would be used, either because no program object is active of because the active program object has specified
 183             no varying variables to record.
 184         </para>
 185     </refsect1>
 186     <refsect1 id="Copyright"><title>Copyright</title>
 187         <para>
 188             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 189             This material may be distributed subject to the terms and conditions set forth in
 190             the Open Publication License, v 1.0, 8 June 1999.
 191             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 192         </para>
 193     </refsect1>
 194 </refentry>