LibertyBSD_xenocara/xenocara/doc/gl-docs/GLU/tessvertex.3gl

'\" e
'\"! eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 6 March 1997
.ds Re Release 1.2.0
.ds Dp May 02 11:53
.ds Dm 37 tessverte
.ds Xs 55990 5 tessvertex.gl
.TH GLUTESSVERTEX 3G
.SH NAME
.B "gluTessVertex
\- specify a vertex on a polygon

.SH C SPECIFICATION
void \f3gluTessVertex\fP(
GLUtesselator* \fItess\fP,
.nf
.ta \w'\f3void \fPgluTessVertex( 'u
	GLdouble \fI*location\fP,
	GLvoid* \fIdata\fP )
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIlocation\fP\ \ 'u 
\f2tess\fP
Specifies the tessellation object (created with \%\f3gluNewTess\fP).
.TP
\f2location\fP
Specifies the location of the vertex.
.TP
\f2data\fP
Specifies an opaque pointer passed back to the program with the vertex callback
(as specified by \%\f3gluTessCallback\fP).
.SH DESCRIPTION
\%\f3gluTessVertex\fP describes a vertex on a polygon that the program defines. Successive
\%\f3gluTessVertex\fP calls describe a closed contour. For example, 
to describe a quadrilateral \%\f3gluTessVertex\fP should be called four times.
\%\f3gluTessVertex\fP can only be called between \%\f3gluTessBeginContour\fP and 
\%\f3gluTessEndContour\fP.
.P
\f2data\fP normally points to a structure containing the vertex
location, as well as other per-vertex attributes such as color and normal.
This pointer is passed back to the user through the \%\f3GLU_TESS_VERTEX\fP
or \%\f3GLU_TESS_VERTEX_DATA\fP callback after tessellation 
(see the \%\f3gluTessCallback\fP reference page).
.SH EXAMPLE
A quadrilateral with a triangular hole in it can be described as follows:
.sp
.Ex
gluTessBeginPolygon(tobj, NULL);
 gluTessBeginContour(tobj);
   gluTessVertex(tobj, v1, v1);
   gluTessVertex(tobj, v2, v2);
   gluTessVertex(tobj, v3, v3);
   gluTessVertex(tobj, v4, v4);
 gluTessEndContour(tobj);
 gluTessBeginContour(tobj);
   gluTessVertex(tobj, v5, v5);
   gluTessVertex(tobj, v6, v6);
   gluTessVertex(tobj, v7, v7);
 gluTessEndContour(tobj);
gluTessEndPolygon(tobj);
.Ee
.sp
.SH NOTES
It is a common error to use a local variable for \f2location\fP or \f2data\fP and store
values into it as part of a loop.
For example:
.Ex
for (i = 0; i < NVERTICES; ++i) {
  GLdouble data[3];
  data[0] = vertex[i][0];
  data[1] = vertex[i][1];
  data[2] = vertex[i][2];
  gluTessVertex(tobj, data, data);
  }
.Ee
.P
This doesn't work.
Because the pointers specified by \f2location\fP and \f2data\fP might not be 
dereferenced until \%\f3gluTessEndPolygon\fP is executed,
all the vertex coordinates but the very last set could be overwritten
before tessellation begins.
.P
Two common symptoms of this problem are consists of a single point
(when a local variable is used for \f2data\fP) and a
\%\f3GLU_TESS_NEED_COMBINE_CALLBACK\fP error (when a local variable is
used for \f2location\fP).
.SH SEE ALSO
\%\f3gluTessBeginPolygon(3G)\fP, \%\f3gluNewTess(3G)\fP, \%\f3gluTessBeginContour(3G)\fP, 
\%\f3gluTessCallback(3G)\fP, 
\%\f3gluTessProperty(3G)\fP, \%\f3gluTessNormal(3G)\fP,
\%\f3gluTessEndPolygon(3G)\fP