'\" 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