upstream-man-pages/man2/xhtml/glFeedbackBuffer.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glFeedbackBuffer</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glFeedbackBuffer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glFeedbackBuffer — controls feedback mode</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glFeedbackBuffer</b>(</code></td><td>GLsizei  </td><td><var class="pdparam">size</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>GLfloat *  </td><td><var class="pdparam">buffer</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>
   4                     Specifies the maximum number of values that can be written into <em class="parameter"><code>buffer</code></em>.
   5                 </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
   6                     Specifies a symbolic constant that describes the information
   7                     that will be returned for each vertex.
   8                     <code class="constant">GL_2D</code>,
   9                     <code class="constant">GL_3D</code>,
  10                     <code class="constant">GL_3D_COLOR</code>,
  11                     <code class="constant">GL_3D_COLOR_TEXTURE</code>, and
  12                     <code class="constant">GL_4D_COLOR_TEXTURE</code> are accepted.
  13                 </p></dd><dt><span class="term"><em class="parameter"><code>buffer</code></em></span></dt><dd><p>
  14                     Returns the feedback data.
  15                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  16             The <code class="function">glFeedbackBuffer</code> function controls feedback.
  17             Feedback, like selection, is a GL mode.
  18             The mode is selected by calling
  19             <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> with <code class="constant">GL_FEEDBACK</code>.
  20             When the GL is in feedback mode,
  21             no pixels are produced by rasterization.
  22             Instead, information about primitives that would have been
  23             rasterized is fed back to the application using the GL.
  24         </p><p>
  25             <code class="function">glFeedbackBuffer</code> has three arguments:
  26             <em class="parameter"><code>buffer</code></em> is a pointer to an array of floating-point values
  27             into which feedback information is placed.
  28             <em class="parameter"><code>size</code></em> indicates the size of the array.
  29             <em class="parameter"><code>type</code></em> is a symbolic constant describing the information
  30             that is fed back for each vertex.
  31             <code class="function">glFeedbackBuffer</code> must be issued before feedback mode is enabled
  32             (by calling <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> with argument <code class="constant">GL_FEEDBACK</code>).
  33             Setting <code class="constant">GL_FEEDBACK</code> without establishing the feedback buffer,
  34             or calling <code class="function">glFeedbackBuffer</code> while the GL is in feedback mode,
  35             is an error.
  36         </p><p>
  37             When <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called while in feedback mode, it returns the number of entries
  38             placed in the feedback array and resets the feedback array pointer to the base
  39             of the feedback buffer. The returned value never exceeds <em class="parameter"><code>size</code></em>. If the feedback
  40             data required more room than was available in <em class="parameter"><code>buffer</code></em>,
  41             <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> returns a negative value.
  42             To take the GL out of feedback mode, call
  43             <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> with a parameter value other than <code class="constant">GL_FEEDBACK</code>.
  44         </p><p>
  45             While in feedback mode,
  46             each primitive, bitmap, or pixel rectangle that would be rasterized
  47             generates a block of values that are copied into the feedback array.
  48             If doing so would cause the number of entries to exceed the maximum,
  49             the block is partially written so as to fill the array
  50             (if there is any room left at all),
  51             and an overflow flag is set.
  52             Each block begins with a code indicating the primitive type,
  53             followed by values that describe the primitive's vertices and
  54             associated data.
  55             Entries are also written for bitmaps and pixel rectangles.
  56             Feedback occurs after polygon culling and <a class="citerefentry" href="glPolygonMode.xml"><span class="citerefentry"><span class="refentrytitle">glPolygonMode</span></span></a> interpretation
  57             of polygons has taken place,
  58             so polygons that are culled are not returned in the feedback buffer.
  59             It can also occur after polygons with more than three edges are broken up
  60             into triangles,
  61             if the GL implementation renders polygons by performing this decomposition.
  62         </p><p>
  63             The <a class="citerefentry" href="glPassThrough.xml"><span class="citerefentry"><span class="refentrytitle">glPassThrough</span></span></a> command can be used to insert a marker
  64             into the feedback buffer.
  65             See <a class="citerefentry" href="glPassThrough.xml"><span class="citerefentry"><span class="refentrytitle">glPassThrough</span></span></a>.
  66         </p><p>
  67             Following is the grammar for the blocks of values written
  68             into the feedback buffer.
  69             Each primitive is indicated with a unique identifying value
  70             followed by some number of vertices.
  71             Polygon entries include an integer value indicating how many vertices follow.
  72             A vertex is fed back as some number of floating-point values,
  73             as determined by <em class="parameter"><code>type</code></em>.
  74             Colors are fed back as four values in RGBA mode and one value
  75             in color index mode.
  76         </p><p>
  77             </p><p>
  78                 feedbackList <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> feedbackItem feedbackList | feedbackItem
  79             </p><p>
  80             </p><p>
  81                 feedbackItem <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> point | lineSegment | polygon | bitmap | pixelRectangle | passThru
  82             </p><p>
  83             </p><p>
  84                 point <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_POINT_TOKEN</code> vertex
  85             </p><p>
  86             </p><p>
  87                 lineSegment <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_LINE_TOKEN</code> vertex vertex | <code class="constant">GL_LINE_RESET_TOKEN</code> vertex vertex
  88             </p><p>
  89             </p><p>
  90                 polygon <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_POLYGON_TOKEN</code> n polySpec
  91             </p><p>
  92             </p><p>
  93                 polySpec <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> polySpec vertex | vertex vertex vertex
  94             </p><p>
  95             </p><p>
  96                 bitmap <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_BITMAP_TOKEN</code> vertex
  97             </p><p>
  98             </p><p>
  99                 pixelRectangle <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_DRAW_PIXEL_TOKEN</code> vertex | <code class="constant">GL_COPY_PIXEL_TOKEN</code> vertex
 100             </p><p>
 101             </p><p>
 102                 passThru <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> <code class="constant">GL_PASS_THROUGH_TOKEN</code> value
 103             </p><p>
 104             </p><p>
 105                 vertex <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture
 106             </p><p>
 107             </p><p>
 108                 2d <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value
 109             </p><p>
 110             </p><p>
 111                 3d <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value
 112             </p><p>
 113             </p><p>
 114                 3dColor <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value color
 115             </p><p>
 116             </p><p>
 117                 3dColorTexture <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value color tex
 118             </p><p>
 119             </p><p>
 120                 4dColorTexture <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value value color tex
 121             </p><p>
 122             </p><p>
 123                 color <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> rgba | index
 124             </p><p>
 125             </p><p>
 126                 rgba <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value value
 127             </p><p>
 128             </p><p>
 129                 index <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value
 130             </p><p>
 131             </p><p>
 132                 tex <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mrow><mml:mn>←</mml:mn></mml:mrow></mml:math> value value value value
 133             </p><p>
 134             </p><p>
 135             </p><p>
 136         </p><p>
 137             <span class="emphasis"><em>value</em></span>
 138             is a floating-point number,
 139             and
 140             <span class="emphasis"><em>n</em></span>
 141             is a floating-point integer giving the number of vertices in the polygon.
 142             <code class="constant">GL_POINT_TOKEN</code>,
 143             <code class="constant">GL_LINE_TOKEN</code>,
 144             <code class="constant">GL_LINE_RESET_TOKEN</code>,
 145             <code class="constant">GL_POLYGON_TOKEN</code>,
 146             <code class="constant">GL_BITMAP_TOKEN</code>,
 147             <code class="constant">GL_DRAW_PIXEL_TOKEN</code>,
 148             <code class="constant">GL_COPY_PIXEL_TOKEN</code> and
 149             <code class="constant">GL_PASS_THROUGH_TOKEN</code> are symbolic floating-point constants.
 150             <code class="constant">GL_LINE_RESET_TOKEN</code> is returned whenever the line stipple pattern
 151             is reset.
 152             The data returned as a vertex depends on the feedback <em class="parameter"><code>type</code></em>.
 153         </p><p>
 154             The following table gives the correspondence between <em class="parameter"><code>type</code></em>
 155             and the number of values per vertex.
 156             <span class="emphasis"><em>k</em></span> is 1 in color index mode and 4 in RGBA mode.
 157         </p><p>
 158         </p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="left" /><col align="center" /><col align="center" /><col align="center" /></colgroup><thead><tr><th align="left"><span class="bold"><strong>
 159                         Type
 160                         </strong></span></th><th align="left"><span class="bold"><strong>
 161                         Coordinates
 162                         </strong></span></th><th align="center"><span class="bold"><strong>
 163                         Color
 164                         </strong></span></th><th align="center"><span class="bold"><strong>
 165                         Texture
 166                         </strong></span></th><th align="center"><span class="bold"><strong>
 167                         Total Number of Values
 168                         </strong></span></th></tr></thead><tbody><tr><td align="left">
 169                         <code class="constant">GL_2D</code>
 170                         </td><td align="left">
 171                         <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>
 172                         </td><td align="center">
 173                         </td><td align="center">
 174                         </td><td align="center">
 175                         2
 176                         </td></tr><tr><td align="left">
 177                         <code class="constant">GL_3D</code>
 178                         </td><td align="left">
 179                         <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>
 180                         </td><td align="center">
 181                         </td><td align="center">
 182                         </td><td align="center">
 183                         3
 184                         </td></tr><tr><td align="left">
 185                         <code class="constant">GL_3D_COLOR</code>
 186                         </td><td align="left">
 187                         <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>
 188                         </td><td align="center">
 189                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">k</mml:mi></mml:math>
 190                         </td><td align="center">
 191                         </td><td align="center">
 192                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 193
 194                             <mml:mrow>
 195                                 <mml:mn>3</mml:mn>
 196                                 <mml:mo>+</mml:mo>
 197                                 <mml:mi mathvariant="italic">k</mml:mi>
 198                             </mml:mrow>
 199                         </mml:math>
 200                         </td></tr><tr><td align="left">
 201                         <code class="constant">GL_3D_COLOR_TEXTURE</code>
 202                         </td><td align="left">
 203                         <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>
 204                         </td><td align="center">
 205                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">k</mml:mi></mml:math>
 206                         </td><td align="center">
 207                         4
 208                         </td><td align="center">
 209                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 210
 211                             <mml:mrow>
 212                                 <mml:mn>7</mml:mn>
 213                                 <mml:mo>+</mml:mo>
 214                                 <mml:mi mathvariant="italic">k</mml:mi>
 215                             </mml:mrow>
 216                         </mml:math>
 217                         </td></tr><tr><td align="left">
 218                         <code class="constant">GL_4D_COLOR_TEXTURE</code>
 219                         </td><td align="left">
 220                         <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>, <span class="emphasis"><em>w</em></span>
 221                         </td><td align="center">
 222                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">k</mml:mi></mml:math>
 223                         </td><td align="center">
 224                         4
 225                         </td><td align="center">
 226                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 227
 228                             <mml:mrow>
 229                                 <mml:mn>8</mml:mn>
 230                                 <mml:mo>+</mml:mo>
 231                                 <mml:mi mathvariant="italic">k</mml:mi>
 232                             </mml:mrow>
 233                         </mml:math>
 234                         </td></tr></tbody></table></div><p>
 235             Feedback vertex coordinates are in window coordinates,
 236             except <span class="emphasis"><em>w</em></span>,
 237             which is in clip coordinates.
 238             Feedback colors are lighted, if lighting is enabled.
 239             Feedback texture coordinates are generated,
 240             if texture coordinate generation is enabled.
 241             They are always transformed by the texture matrix.
 242         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 243             <code class="function">glFeedbackBuffer</code>, when used in a display list, is not compiled into the display list
 244             but is executed immediately.
 245         </p><p>
 246             <code class="function">glFeedbackBuffer</code> returns only the texture coordinate of texture unit <code class="constant">GL_TEXTURE0</code>.
 247         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 248             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not an accepted value.
 249         </p><p>
 250             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>size</code></em> is negative.
 251         </p><p>
 252             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glFeedbackBuffer</code> is called while the
 253             render mode is <code class="constant">GL_FEEDBACK</code>,
 254             or if <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a> is called with argument <code class="constant">GL_FEEDBACK</code> before
 255             <code class="function">glFeedbackBuffer</code> is called at least once.
 256         </p><p>
 257             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glFeedbackBuffer</code>
 258             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 259             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 260         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 261             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_RENDER_MODE</code>
 262         </p><p>
 263             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FEEDBACK_BUFFER_POINTER</code>
 264         </p><p>
 265             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FEEDBACK_BUFFER_SIZE</code>
 266         </p><p>
 267             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_FEEDBACK_BUFFER_TYPE</code>
 268         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 269             <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>,
 270             <a class="citerefentry" href="glLineStipple.xml"><span class="citerefentry"><span class="refentrytitle">glLineStipple</span></span></a>,
 271             <a class="citerefentry" href="glPassThrough.xml"><span class="citerefentry"><span class="refentrytitle">glPassThrough</span></span></a>,
 272             <a class="citerefentry" href="glPolygonMode.xml"><span class="citerefentry"><span class="refentrytitle">glPolygonMode</span></span></a>,
 273             <a class="citerefentry" href="glRenderMode.xml"><span class="citerefentry"><span class="refentrytitle">glRenderMode</span></span></a>,
 274             <a class="citerefentry" href="glSelectBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glSelectBuffer</span></span></a>
 275         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 276             Copyright <span class="trademark"></span>© 1991-2006
 277             Silicon Graphics, Inc. This document is licensed under the SGI
 278             Free Software B License. For details, see
 279             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 280         </p></div></div></body></html>