Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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> |