.\" @(#)PEXSetOfFillAreaSets.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXSetOfFillAreaSets 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXSetOfFillAreaSets - 3D Set of Fill Area Sets Primitive
.SH SYNTAX
.HP
void PEXSetOfFillAreaSets\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, int \fIshape_hint\fP\^, unsigned int \fIfacet_attributes\fP\^, unsigned int \fIvertex_attributes\fP\^, unsigned int \fIedge_attributes\fP\^,
int \fIcontour_hint\fP\^, int \fIcontours_all_one\fP\^, int \fIcolor_type\fP\^,
unsigned int \fIset_count\fP\^, PEXArrayOfFacetData \fIfacet_data\fP\^, unsigned int \fIvertex_count\fP\^, PEXArrayOfVertex \fIvertices\fP\^, unsigned int \fIindex_count\fP\^, PEXSwitch *\fIedge_flags\fP\^, PEXConnectivityData *\fIconnectivity\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIresource_id\fP 1i
The resource identifier of the renderer or structure.
.IP \fIreq_type\fP 1i
The request type for the output command (
.B PEXOCRender,
.B PEXOCStore,
.B PEXOCRenderSingle
or
.B PEXOCStoreSingle
).
.IP \fIshape_hint\fP 1i
The shape which describes all of the contours (
.B PEXShapeComplex,
.B PEXShapeNonConvex,
.B PEXShapeConvex,
.B PEXShapeUnknown
).
.IP \fIfacet_attributes\fP 1i
A mask indicating the facet attributes provided (
.B PEXGANone,
.B PEXGAColor,
.B PEXGANormal
).
.IP \fIvertex_attributes\fP 1i
A mask indicating the vertex attributes provided (
.B PEXGANone,
.B PEXGAColor,
.B PEXGANormal
).
.IP \fIedge_attributes\fP 1i
A mask indicating the edge attributes provided (
.B PEXGANone
or
.B PEXGAEdges
).
.IP \fIcontour_hint\fP 1i
A flag indicating whether contours are disjoint or overlapping (
.B PEXContourDisjoint,
.B PEXContourNested,
.B PEXContourIntersecting,
.B PEXContourUnknown
).
.IP \fIcontours_all_one\fP 1i
.SB True
if each fill area set contains only one contour;
.SB False
otherwise.
.IP \fIcolor_type\fP 1i
The type of color data provided (
.B PEXColorTypeIndexed,
.B PEXColorTypeRGB,
.B PEXColorTypeCIE,
.B PEXColorTypeHSV,
.B PEXColorTypeHLS,
.B PEXColorTypeRGB8,
.B PEXColorTypeRGB16
).
.IP \fIset_count\fP 1i
The number of fill area sets.
.IP \fIfacet_data\fP 1i
An array of facet data.
.IP \fIvertex_count\fP 1i
The number of vertices.
.IP \fIvertices\fP 1i
An array of vertices.
.IP \fIindex_count\fP 1i
The number of vertex connectivity indices (also number of edge flags,
if edges are specified).
.IP \fIedge_flags\fP 1i
An array of edge flags.
.IP \fIconnectivity\fP 1i
A pointer to the list of contour connectivity data.
.SH RETURNS
.LP
None
.SH DESCRIPTION
.\" indexing
.IX PEXSetOfFillAreaSets
.LP
This function creates a set of fill area sets output primitive.
.LP
A fill area may cross over itself to create a complex shape.  The odd-even
rule is used for determining the area that lies in the interior of the fill
area.
The shape hint is provided to enable performance improvements
for certain shapes.
Fill areas that are of higher complexity than indicated by the shape hint
are rendered
in an implementation-dependent manner.  Consequently,
applications should pass
.B PEXShapeUnknown
as the shape unless they are
certain the fill area's shape is one of the other three.
Note that a fill area set with more than one contour is always allowed to have
contours that intersect.  If is quite possible that the only times rendering
optimization can occur are when the number of contours in a fill area set
is equal to one or if the contours all one flag is
.SB True,
and the shape hint is
.B PEXShapeConvex.
.LP
The contour hint provides further information about the
relationships between contours in the fill area set.
If the contour hint is
.B PEXContourDisjoint
all contours will be spatially disjoint.  No overlapping
or intersection occurs between any contours in the fill area set.  If
the contour hint is
.B PEXContourNested
contours will either be disjoint or
wholly contained within another contour.  No contour will have edges
that intersect or are coincident with edges of any other contour.  If
the contour hint is
.B PEXContourIntersecting
separated contours may have edges
that are coincident or overlap.  If the contour hint is
.B PEXContourUnknown
nothing is known about the interrelationships between contours.  Fill
area sets with contours that have higher complexity interrelationships
than that indicated by the contour hint are rendered in an
implementation-dependent manner.
.LP
The facet attributes indicate the content of the facet data.
This data may be a color, a normal, or a color followed by a normal.
Use the constants
.B PEXGANone,
.B PEXGAColor
and
.B PEXGANormal
to construct a mask indicating the data provided.
If specified, the
facet color takes precedence over the
surface color.
If specified, the facet normal is used to
determine whether the fill area is back-facing.
.LP
The vertex attributes indicate the content of each fill area vertex.
In addition to the coordinate (x,y,z), applications may specify
a color, a normal, or a color followed by a normal for each vertex.
Use the constants
.B PEXGANone,
.B PEXGAColor
and
.B PEXGANormal
to construct a mask indicating the data provided.
If specified, vertex colors will override facet color or the current
surface color.
If specified, vertex normals are taken to be normals at the vertices of
the fill area.
.LP
The reflection model and the surface interpolation will
affect how the additional data is used in rendering the surface.
.LP
Color values passed must be of the specified color type.
Normals are assumed to be unit length vectors.  The effect if the normal
is not unit length is implementation-dependent.
.LP
The edge attributes indicate the content of the edge flags.  Use
.B PEXGAEdges
to indicate edge flags are provided or
.B PEXGANone
if no edge flags are provided.
The edge flags, if present, are set to
.B PEXOn
or
.B PEXOff
and are
used to indicate which edges should be rendered.
The edge control for vertex i indicates whether or
not to render the edge between vertex i and vertex i+1.
Surface edges are always rendered with the surface edge color and are not
affected by the facet or vertex colors.
.LP
The
.I connectivity
of the primitive is defined by the
.I connectivity
list.
The
.I connectivity
list is a pointer to an array of
.B PEXConnectivityData
structures.  Each entry in the array gives the contours for one fill area set
in the set of fill area sets, and, in turn, contains a pointer to an array of
.B PEXListOfUShort
structures.  Each of these latter structures gives the index of the vertices
of one contour in that fill area set.  The indices select a vertex in the array
of vertices.
Vertices are numbered with indices starting from zero (i.e. the first
vertex is referenced as vertex 0).
As a special case, if the contours all one flag is
.SB True
then the contour count
field in each fill area set is guaranteed to be one.
.LP
All attributes affecting the representation of fill area sets also
affect the representation of this primitive.
.SH DATA STRUCTURES
.LP
.nf
typedef struct {
	unsigned short		count;		/* number of lists */
	PEXListOfUShort	*lists;
.br
} PEXConnectivityData;
.sp
typedef struct {
	unsigned short		count;		/* number of shorts */
	unsigned short		*shorts;
.br
} PEXListOfUShort;
.sp
typedef  unsigned char	PEXSwitch;
.fi
.sp .5
See also
.B PEXlib.h.
.SH ERRORS
.TP
.SB BadPEXOutputCommand
The output command contains an invalid value.
.TP
.SB BadPEXRenderer
The specified renderer resource identifier is invalid.
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXSetInteriorStyle (3)
.BR PEXSetInteriorStyleIndex (3)
.BR PEXSetSurfaceColorIndex (3)
.BR PEXSetSurfaceColor (3)
.BR PEXSetReflectionAttributes (3)
.BR PEXSetReflectionModel (3)
.BR PEXSetSurfaceInterpMethod (3)
.BR PEXSetBFInteriorStyle (3)
.BR PEXSetBFInteriorStyleIndex (3)
.BR PEXSetBFSurfaceColorIndex (3)
.BR PEXSetBFSurfaceColor (3)
.BR PEXSetBFReflectionAttributes (3)
.BR PEXSetBFReflectionModel (3)
.BR PEXSetBFSurfaceInterpMethod (3)
.BR PEXSetFacetCullingMode (3)
.BR PEXSetFacetDistinguishFlag (3)
.BR PEXSetPatternSize (3)
.BR PEXSetPatternAttributes (3)
.BR PEXSetPatternAttributes2D (3)
.BR PEXSetInteriorBundleIndex (3)
.BR PEXSetSurfaceEdgeFlag (3)
.BR PEXSetSurfaceEdgeType (3)
.BR PEXSetSurfaceEdgeWidth (3)
.BR PEXSetSurfaceEdgeColor (3)
.BR PEXSetSurfaceEdgeColorIndex (3)
.BR PEXSetEdgeBundleIndex (3)
.fi