Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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="gluNurbsCallback"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>1991-2006</year> | |
9 | <holder>Silicon Graphics, Inc.</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>gluNurbsCallback</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>gluNurbsCallback</refname> | |
17 | <refpurpose>define a callback for a NURBS object</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void <function>gluNurbsCallback</function></funcdef> | |
23 | <paramdef>GLUnurbs* <parameter>nurb</parameter></paramdef> | |
24 | <paramdef>GLenum <parameter>which</parameter></paramdef> | |
25 | <paramdef>_GLUfuncptr <parameter>CallBackFunc</parameter></paramdef> | |
26 | </funcprototype> | |
27 | </funcsynopsis> | |
28 | </refsynopsisdiv> | |
29 | <!-- eqn: ignoring delim $$ --> | |
30 | <refsect1 id="parameters"><title>Parameters</title> | |
31 | <variablelist> | |
32 | <varlistentry> | |
33 | <term><parameter>nurb</parameter></term> | |
34 | <listitem> | |
35 | <para> | |
36 | Specifies the NURBS object (created with <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>). | |
37 | </para> | |
38 | </listitem> | |
39 | </varlistentry> | |
40 | <varlistentry> | |
41 | <term><parameter>which</parameter></term> | |
42 | <listitem> | |
43 | <para> | |
44 | Specifies the callback being defined. | |
45 | Valid values are <constant>GLU_NURBS_BEGIN</constant>, <constant>GLU_NURBS_VERTEX</constant>, <constant>GLU_NURBS_NORMAL</constant>, <constant>GLU_NURBS_COLOR</constant>, <constant>GLU_NURBS_TEXTURE_COORD</constant>, <constant>GLU_NURBS_END</constant>, <constant>GLU_NURBS_BEGIN_DATA</constant>, <constant>GLU_NURBS_VERTEX_DATA</constant>, <constant>GLU_NURBS_NORMAL_DATA</constant>, <constant>GLU_NURBS_COLOR_DATA</constant>, <constant>GLU_NURBS_TEXTURE_COORD_DATA</constant>, <constant>GLU_NURBS_END_DATA</constant>, and <constant>GLU_NURBS_ERROR</constant>. | |
46 | </para> | |
47 | </listitem> | |
48 | </varlistentry> | |
49 | <varlistentry> | |
50 | <term><parameter>CallBackFunc</parameter></term> | |
51 | <listitem> | |
52 | <para> | |
53 | Specifies the function that the callback calls. | |
54 | </para> | |
55 | </listitem> | |
56 | </varlistentry> | |
57 | </variablelist> | |
58 | </refsect1> | |
59 | <refsect1 id="description"><title>Description</title> | |
60 | <para> | |
61 | <function>gluNurbsCallback</function> is used to define a callback to be used by a NURBS | |
62 | object. | |
63 | If the specified callback is already defined, then it is replaced. If | |
64 | <parameter>CallBackFunc</parameter> is NULL, then this callback will not get | |
65 | invoked and the related data, if any, will be lost. | |
66 | </para> | |
67 | <para> | |
68 | Except the error callback, these callbacks are used by NURBS tessellator (when <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_TESSELLATOR</constant>) to return back the OpenGL | |
69 | polygon primitives resulting from the tessellation. Note that there are two | |
70 | versions of each callback: one with a user data pointer and one without. If both versions for a particular callback are specified then the callback with | |
71 | the user data pointer will be used. Note that ``userData'' is a copy of the pointer that was specified at the last call to <function>gluNurbsCallbackData</function>. | |
72 | </para> | |
73 | <para> | |
74 | The error callback function is effective no matter which value that | |
75 | <constant>GLU_NURBS_MODE</constant> is set to. | |
76 | All other callback functions are effective only when <constant>GLU_NURBS_MODE</constant> | |
77 | is set to <constant>GLU_NURBS_TESSELLATOR</constant>. | |
78 | </para> | |
79 | <para> | |
80 | The legal callbacks are as follows: | |
81 | </para> | |
82 | <variablelist> | |
83 | <varlistentry> | |
84 | <term><constant>GLU_NURBS_BEGIN</constant></term> | |
85 | <listitem> | |
86 | <para> | |
87 | </para> | |
88 | <para> | |
89 | The begin callback indicates the start of a primitive. The function | |
90 | takes a single argument of type GLenum, which can be one of | |
91 | <constant>GLU_LINES</constant>, <constant>GLU_LINE_STRIP</constant>, <constant>GLU_TRIANGLE_FAN</constant>, <constant>GLU_TRIANGLE_STRIP</constant>, <constant>GLU_TRIANGLES</constant>, or <constant>GLU_QUAD_STRIP</constant>. The | |
92 | default begin callback function is NULL. The function prototype | |
93 | for this callback looks like: | |
94 | <programlisting> | |
95 | void begin( GLenum type ); | |
96 | </programlisting> | |
97 | </para> | |
98 | </listitem> | |
99 | </varlistentry> | |
100 | <varlistentry> | |
101 | <term><constant>GLU_NURBS_BEGIN_DATA</constant></term> | |
102 | <listitem> | |
103 | <para> | |
104 | </para> | |
105 | <para> | |
106 | The same as the <constant>GLU_NURBS_BEGIN</constant> callback except that it takes an | |
107 | additional pointer argument. This pointer is a copy of the pointer that | |
108 | was specified at the last call to <function>gluNurbsCallbackData</function>. The | |
109 | default callback function is NULL. The function prototype for this | |
110 | callback function looks like: | |
111 | <programlisting> | |
112 | void beginData(GLenum type, void *userData); | |
113 | </programlisting> | |
114 | </para> | |
115 | </listitem> | |
116 | </varlistentry> | |
117 | <varlistentry> | |
118 | <term><constant>GLU_NURBS_VERTEX</constant></term> | |
119 | <listitem> | |
120 | <para> | |
121 | </para> | |
122 | <para> | |
123 | The vertex callback indicates a vertex of the primitive. The | |
124 | coordinates of the vertex are stored in the parameter ``vertex''. All | |
125 | the generated vertices have dimension 3; that is, homogeneous | |
126 | coordinates have been transformed into affine coordinates. The default | |
127 | vertex callback function is NULL. The function prototype for this | |
128 | callback function looks like: | |
129 | <programlisting> | |
130 | void vertex( GLfloat *vertex ); | |
131 | </programlisting> | |
132 | </para> | |
133 | </listitem> | |
134 | </varlistentry> | |
135 | <varlistentry> | |
136 | <term><constant>GLU_NURBS_VERTEX_DATA</constant></term> | |
137 | <listitem> | |
138 | <para> | |
139 | </para> | |
140 | <para> | |
141 | This is the same as the <constant>GLU_NURBS_VERTEX</constant> callback, except that | |
142 | it takes an additional pointer argument. This pointer is a copy of the | |
143 | pointer that was specified at the last call to | |
144 | <function>gluNurbsCallbackData</function>. The default callback function is NULL. The | |
145 | function prototype for this callback function looks like: | |
146 | <programlisting> | |
147 | void vertexData( GLfloat *vertex, void *userData ); | |
148 | </programlisting> | |
149 | </para> | |
150 | </listitem> | |
151 | </varlistentry> | |
152 | <varlistentry> | |
153 | <term><constant>GLU_NURBS_NORMAL</constant></term> | |
154 | <listitem> | |
155 | <para> | |
156 | </para> | |
157 | <para> | |
158 | The normal callback is invoked as the vertex normal is generated. | |
159 | The components of the normal are stored in the parameter ``normal.'' | |
160 | In the case of a NURBS curve, the callback function is effective only when | |
161 | the user provides a normal map (<constant>GLU_MAP1_NORMAL</constant>). | |
162 | In the case of a NURBS surface, if a normal map (<constant>GLU_MAP2_NORMAL</constant>) | |
163 | is provided, then the generated normal is computed from the normal map. | |
164 | If a normal map is not provided, then a surface normal is computed in | |
165 | a manner similar to that described for evaluators when <constant>GLU_AUTO_NORMAL</constant> | |
166 | is enabled. | |
167 | The default normal callback function is NULL. The function | |
168 | prototype for this callback function looks like: | |
169 | <programlisting> | |
170 | void normal( GLfloat *normal ); | |
171 | </programlisting> | |
172 | </para> | |
173 | </listitem> | |
174 | </varlistentry> | |
175 | <varlistentry> | |
176 | <term><constant>GLU_NURBS_NORMAL_DATA</constant></term> | |
177 | <listitem> | |
178 | <para> | |
179 | </para> | |
180 | <para> | |
181 | The same as the <constant>GLU_NURBS_NORMAL</constant> callback except that it | |
182 | takes an additional pointer argument. This pointer is a copy of the pointer | |
183 | that was specified at the last call to <function>gluNurbsCallbackData</function>. The default callback function is NULL. The function prototype for this callback function looks like: | |
184 | <programlisting> | |
185 | void normalData( GLfloat *normal, void *userData ); | |
186 | </programlisting> | |
187 | </para> | |
188 | </listitem> | |
189 | </varlistentry> | |
190 | <varlistentry> | |
191 | <term><constant>GLU_NURBS_COLOR</constant></term> | |
192 | <listitem> | |
193 | <para> | |
194 | </para> | |
195 | <para> | |
196 | The color callback is invoked as the color of a vertex is generated. | |
197 | The components of the color are stored in the parameter ``color.'' | |
198 | This callback is effective only when the user provides a color map | |
199 | (<constant>GLU_MAP1_COLOR_4</constant> or <constant>GLU_MAP2_COLOR_4</constant>). ``color'' contains four | |
200 | components: R, G, B, A. The default color callback function is NULL. | |
201 | The prototype for this callback function looks like: | |
202 | <programlisting> | |
203 | void color( GLfloat *color ); | |
204 | </programlisting> | |
205 | </para> | |
206 | </listitem> | |
207 | </varlistentry> | |
208 | <varlistentry> | |
209 | <term><constant>GLU_NURBS_COLOR_DATA</constant></term> | |
210 | <listitem> | |
211 | <para> | |
212 | </para> | |
213 | <para> | |
214 | The same as the <constant>GLU_NURBS_COLOR</constant> callback except that it | |
215 | takes an additional pointer argument. This pointer is a copy of the pointer | |
216 | that was specified at the last call to <function>gluNurbsCallbackData</function>. The default callback function is NULL. The function prototype for this callback function looks like: | |
217 | <programlisting> | |
218 | void colorData( GLfloat *color, void *userData ); | |
219 | </programlisting> | |
220 | </para> | |
221 | </listitem> | |
222 | </varlistentry> | |
223 | <varlistentry> | |
224 | <term><constant>GLU_NURBS_TEXTURE_COORD</constant></term> | |
225 | <listitem> | |
226 | <para> | |
227 | </para> | |
228 | <para> | |
229 | The texture callback is invoked as the texture coordinates | |
230 | of a vertex are generated. These coordinates are stored in the parameter | |
231 | ``texCoord.'' The number of texture coordinates can be 1, 2, 3, or 4 depending | |
232 | on which type of texture map is specified | |
233 | (<constant>GLU_MAP1_TEXTURE_COORD_1</constant>, | |
234 | <constant>GLU_MAP1_TEXTURE_COORD_2</constant>, | |
235 | <constant>GLU_MAP1_TEXTURE_COORD_3</constant>, | |
236 | <constant>GLU_MAP1_TEXTURE_COORD_4</constant>, | |
237 | <constant>GLU_MAP2_TEXTURE_COORD_1</constant>, | |
238 | <constant>GLU_MAP2_TEXTURE_COORD_2</constant>, | |
239 | <constant>GLU_MAP2_TEXTURE_COORD_3</constant>, | |
240 | <constant>GLU_MAP2_TEXTURE_COORD_4</constant>). | |
241 | If no texture map is specified, this callback function will not be called. | |
242 | The default texture callback function is NULL. The function prototype | |
243 | for this callback function looks like: | |
244 | <programlisting> | |
245 | void texCoord( GLfloat *texCoord ); | |
246 | </programlisting> | |
247 | </para> | |
248 | </listitem> | |
249 | </varlistentry> | |
250 | <varlistentry> | |
251 | <term> <constant>GLU_NURBS_TEXTURE_COORD_DATA</constant></term> | |
252 | <listitem> | |
253 | <para> | |
254 | </para> | |
255 | <para> | |
256 | This is the same as the <constant>GLU_NURBS_TEXTURE_COORD</constant> callback, except that it | |
257 | takes an additional pointer argument. This pointer is a copy of the pointer | |
258 | that was specified at the last call to <function>gluNurbsCallbackData</function>. The default callback function is NULL. The function prototype for this callback function looks like: | |
259 | <programlisting> | |
260 | void texCoordData( GLfloat *texCoord, void *userData ); | |
261 | </programlisting> | |
262 | </para> | |
263 | </listitem> | |
264 | </varlistentry> | |
265 | <varlistentry> | |
266 | <term><constant>GLU_NURBS_END</constant></term> | |
267 | <listitem> | |
268 | <para> | |
269 | </para> | |
270 | <para> | |
271 | The end callback is invoked at the end of a primitive. The default end callback function is NULL. The function prototype for this callback function looks like: | |
272 | <programlisting> | |
273 | void end( void ); | |
274 | </programlisting> | |
275 | </para> | |
276 | </listitem> | |
277 | </varlistentry> | |
278 | <varlistentry> | |
279 | <term><constant>GLU_NURBS_END_DATA</constant></term> | |
280 | <listitem> | |
281 | <para> | |
282 | </para> | |
283 | <para> | |
284 | This is the same as the <constant>GLU_NURBS_END</constant> callback, except that it | |
285 | takes an additional pointer argument. This pointer is a copy of the pointer | |
286 | that was specified at the last call to <function>gluNurbsCallbackData</function>. The default callback function is NULL. The function prototype for this callback function looks like: | |
287 | <programlisting> | |
288 | void endData( void *userData ); | |
289 | </programlisting> | |
290 | </para> | |
291 | </listitem> | |
292 | </varlistentry> | |
293 | <varlistentry> | |
294 | <term><constant>GLU_NURBS_ERROR</constant></term> | |
295 | <listitem> | |
296 | <para> | |
297 | </para> | |
298 | <para> | |
299 | The error function is called when an error is encountered. | |
300 | Its single argument | |
301 | is of type GLenum, and it indicates the specific error that occurred. | |
302 | There are 37 errors unique to NURBS, named | |
303 | <constant>GLU_NURBS_ERROR1</constant> through <constant>GLU_NURBS_ERROR37</constant>. | |
304 | Character strings describing these errors can be retrieved with | |
305 | <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>. | |
306 | </para> | |
307 | </listitem> | |
308 | </varlistentry> | |
309 | </variablelist> | |
310 | </refsect1> | |
311 | <refsect1 id="notes"><title>Notes</title> | |
312 | <para> | |
313 | <function>gluNurbsCallback</function> is available only if the GLU version is 1.2 or greater. | |
314 | </para> | |
315 | <para> | |
316 | GLU version 1.2 supports only the <constant>GLU_ERROR</constant> parameter for | |
317 | <parameter>which</parameter>. The <constant>GLU_ERROR</constant> value is deprecated in GLU version 1.3 in | |
318 | favor of <constant>GLU_NURBS_ERROR</constant>. All other accepted values for <parameter>CallBackFunc</parameter> | |
319 | are available only if the GLU version is 1.3 or greater. | |
320 | </para> | |
321 | </refsect1> | |
322 | <refsect1 id="seealso"><title>See Also</title> | |
323 | <para> | |
324 | <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>, | |
325 | <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>, | |
326 | <function>gluNurbsCallbackData</function>, | |
327 | <citerefentry><refentrytitle>gluNurbsProperty</refentrytitle></citerefentry> | |
328 | </para> | |
329 | </refsect1> | |
330 | <refsect1 id="Copyright"><title>Copyright</title> | |
331 | <para> | |
332 | Copyright <trademark class="copyright"></trademark> 1991-2006 | |
333 | Silicon Graphics, Inc. This document is licensed under the SGI | |
334 | Free Software B License. For details, see | |
335 | <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>. | |
336 | </para> | |
337 | </refsect1> | |
338 | </refentry> |