NAME

DoPolygonMesh − Create a polygon mesh primitive object

SYNOPSIS

C:

DtObject DoPolygonMesh(colormodel, vertextype,
vertexcount, vertices, polygoncount, polygons,
   contours, vertexlist, shape, smoothflag)
DtColorModel colormodel;
DtVertexType vertextype;
DtInt vertexcount;
DtReal vertices[];
DtInt polygoncount;
DtInt polygons[];
DtInt contours[];
DtInt vertexlist[];
DtShapeType shape;
DtFlag smoothflag;

FORTRAN:

INTEGER∗4 DOPGNM(COLMOD, VTXTYP, VTXCNT,
VTXS, PLYCNT, PLYGON, CONTURS,
VTXLST, SHAPE, SMOOFL)
INTEGER∗4 COLMOD
INTEGER∗4 VTXTYP
INTEGER∗4 VTXCNT
REAL∗8 VTXS(∗)
INTEGER∗4 PLYCNT
INTEGER∗4 PLYGON(PLYCNT)
INTEGER∗4 CONTURS(∗)
INTEGER∗4 VTXLST(∗)
INTEGER∗4 SHAPE
INTEGER∗4 SMOOFL

DESCRIPTION

DoPolygonMesh creates a primitive object that defines a collection of general polygons, normally interconnected.  Each polygon must be as described in DoPolygon. 

Mesh objects allow the user to specify a collection of vertices in space and connect the vertices into a collection of other geometric entities, usually forming a connected surface.  Polygon meshes are generally used to approximate a smooth surface. 

Geometric normals to the polygons in the mesh are calculated using the right-hand rule (the fingers of the right hand point in the order of vertices and the thumb points in the direction of the normal).  These normals are sometimes used for backface culling and facet shading. 

The parameter colormodel specifies the color model used if the vertices contain color information for shading purposes.  The parameter vertextype specifies the exact nature of the vertices.  FORTRANr more information, refer to Chapter 6, Doré Vertex Types, in the Doré Reference Manual or to the VertexTypes on-line manual page.) 

The parameter vertices is an array of vertex data.  The parameter vertexcount specifies the number of vertices contained in the vertices array. 

The parameter polygoncount specifies the number of polygons in the mesh.  The parameter polygons is an array of polygoncount integers, each of which specifies the number of contours in the associated polygon.  The parameter contours is an array of integers, one for each of the total number of contours in the mesh.  Each entry in the contours array specifies the number of vertices in the associated contour. 

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.  This argument has meaning only for polygons that consist of a single contour, that is, for polygons where polygons[i] = 1.  For these polygons, correctly specifying the shape of the contour 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.

DcComplex <DCCPLX>
Path may be self-intersecting.

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

ERRORS

DoPolygonMesh must be called with a valid specification for shape. 

[WARNING - invalid parameter]

DoPolygonMesh must be called with at least one contour of three vertices. 

[WARNING - insufficient information]

DoPolygonMesh 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]

SEE ALSO

DoPolygon(3D), DoSimplePolygon(3D), DoSimplePolygonMesh(3D), VertexTypes(3D)

September 02, 1992