NAME

DoVarSimplePolygonMesh − Create a variable simple polygon mesh primitive object

SYNOPSIS

C:

DtObject DoVarSimplePolygonMesh(colormodel,
vertexcount, vertlocs, vertnorms,
vertcolors, polygoncount, contours,
vertexlist, shape, smoothflag)
DtColorModel colormodel;
DtInt vertexcount;
DtReal vertlocs[];
DtReal vertnorms[];
DtReal vertcolors[];
DtInt polygoncount;
DtInt contours[];
DtInt vertexlist[];
DtShapeType shape;
DtFlag smoothflag;

FORTRAN:

INTEGER∗4 DOVSPM(COLMOD, VTXCNT, VTXLOC,
VTXNRM, VTXCLR, PLYCNT,
CONTURS, VTXLST, SHAPE,
SMOOFL)
INTEGER∗4 COLMOD
INTEGER∗4 VTXCNT
REAL∗8 VTXLOC(∗)
REAL∗8 VTXNRM(∗)
REAL∗8 VTXCLR(∗)
INTEGER∗4 PLYCNT
INTEGER∗4 CONTURS(PLYCNT)
INTEGER∗4 VTXLST(∗)
INTEGER∗4 SHAPE
INTEGER∗4 SMOOFL

DESCRIPTION

DoVarSimplePolygonMesh creates a primitive object that defines a variable collection of simple polygons, normally interconnected. 

The main difference between a variable simple polygon mesh and a simple polygon mesh is that the variable mesh does not copy the vertex data into its own data space.  It simply maintains pointers to the vertex data (locations, normals and colors) in user space.  A call to DpUpdVarSimplePolygonMesh <DPUVSM> informs an object that the user data has changed.  Each simple polygon must be as described in DoSimplePolygon, with the additional restriction that the shape must not be DcComplex <DCCPLX>. 

The parameter colormodel specifies the color model used if vertex colors are specified.  The parameter vertexcount specifies the number of vertices.  The parameter vertlocs is an array of vertex locations.  The parameter vertnorms is an array of vertex normals.  If vertex normals are not available use DcNullPtr <DCNULL>.  The parameter vertcolors is an array of vertex colors.  If vertex colors are not available use DcNullPtr <DCNULL>. 

The parameter polygoncount specifies the number of polygons in the mesh.  Simple polygons are each composed of one contour.  The parameter contours is an array of polygoncount integers, each of which specifies the number of vertices in the associated polygon. 

The parameter vertexlist is an array of integers that index the vertices array.  The first polygon in the mesh begins with the vertex specified by vertexlist[0], and continues using the vertices specified by the following entries in vertexlist.  The last vertex of a contour is implicitly connected to its first vertex.  The next polygon begins with the vertex specified next in the vertexlist array. 

The parameter shape hints at the geometry of the polygons in the mesh.  For these polygons, correctly specifying the shape of the polygon will result in optimal polygon decomposition when necessary.  Incorrectly specifying the shape may result in an incorrect or aborted decomposition.  The possible values for shape are:

DcConvex <DCCNVX>
Path is wholly convex.

DcConcave <DCCNCV>
Path may be concave but not self-intersecting.

Note that the shape must not be DcComplex <DCCPLX>. 

The parameter smoothflag specifies that if vertex normals are not provided, the average normal of the geometric normals from a vertex’s adjacent surfaces constitute the normal for vertex shading.  (This assumes the simple polygon mesh defines a smooth surface.) 

The geometric normal to each polygon is calculated using the right-hand rule (when the fingers of the right hand point in the order of the vertices, the thumb points in the direction of the normal).  Doré uses these normals for backface culling and facet shading. 

ERRORS

DoVarSimplePolygonMesh must be called with a valid specification for shape. 

[WARNING - invalid parameter]

DoVarSimplePolygonMesh must be called with at least three vertices. 

[WARNING - insufficient information]

DoVarSimplePolygonMesh will issue a warning if a zero vertex normal is calculated by Doré. 

[WARNING - triangle normals sum to 0 at vertex, check for back to back triangles]

DoVarSimplePolygonMesh will fail if the polygon is specified as DcComplex. 

[WARNING - value out of range]

SEE ALSO

DpUpdVarSimplePolygonMesh(3D), DoSimplePolygonMesh(3D), DoVarLineList(3D), DoVarPointList(3D), DoVarTriangleMesh(3D), DoVarTriangleStrip(3D)

September 02, 1992