.\"
.\" $XConsortium: p058,v 5.3 94/04/17 20:54:56 hersh Exp $
.\"
.\" 
$XMCOPY
.\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" 
.\"                         All Rights Reserved
.\" 
.\" Permission to use, copy, modify, and distribute this software and its 
.\" documentation for any purpose and without fee is hereby granted, 
.\" provided that the above copyright notice appear in all copies and that
.\" both that copyright notice and this permission notice appear in 
.\" supporting documentation, and that the names of Sun Microsystems,
.\" and the X Consortium not be used in advertising or publicity 
.\" pertaining to distribution of the software without specific, written 
.\" prior permission.  
.\" 
.\" SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\" EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\" USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.TH "FILL AREA SET" 3P "15 August 1991"
.SH NAME
FILL AREA SET \- create a structure element specifying a \s-2\&2D\s+2 fill area set primitive
.IX "Filled Area Primitives" "FILL AREA SET"
.IX "Primitives, Filled Area Primitives" "FILL AREA SET"
.IX "Polygons, Filled Area Primitives" "FILL AREA SET"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pfill_area_set ( point_list_list )
Ppoint_list_list       *point_list_list;       \fI list of point lists\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
The \s-2FILL AREA SET\s+2 function puts a structure element containing
the \s-2\&2D\s+2 specification of a \s-2FILL AREA SET\s+2 primitive into the
currently open structure.  The \s-2FILL AREA SET\s+2 primitive is a group
of implicitly closed polygonal areas.
This allows for specifying areas with holes or disjoint regions.
The subroutine parameters specify the number
of fill areas to be drawn, the number of points used to define each, and
the Modelling coordinates of each point.
The \fIz\fP coordinates are assumed to be zeroes.
Each set of points defines a separate closed area.
All of the areas specified in a single function
call are drawn using the current values of the \s-2FILL AREA SET\s+2
attributes listed below.
.LP
If the current edit mode is \s-2INSERT\s+2, the structure element created
by the \s-2FILL AREA SET\s+2 subroutine is inserted into the open
structure after the element pointed to by the structure's element
pointer.  If the edit mode is \s-2REPLACE\s+2, the new \s-2FILL AREA
SET\s+2 element replaces the element pointed to by the element pointer. In
either case, the element pointer is updated to point to the new \s-2FILL
AREA SET\s+2 element.
.SS C Input Parameters
.IP \fIpoint_list_list\fP
A pointer to a list of Ppoint_list_list structures. Each Ppoint_list_list
structure has 2 fields, the \fInum_points_list\fP field, which is the
number of 2d point lists, and the \fIpoint_lists\fP, a pointer to a list of
PPoint_list.  Each Ppoint_list structure defines a fill area.
Ppoint_list_list is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Ppoint	'u +\w'num_points;	'u
.nf
typedef struct {
.sp .2
	Pint         num_point_lists;       /* number of point lists  */
	Ppoint_list *point_lists;          /* list of point lists */
.sp .2
} Ppoint_list_list;
.fi
.IP
Ppoint_list is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Ppoint	'u +\w'num_points;	'u
.nf
typedef struct {
.sp .2
	Pint	num_points;	/* number of Ppoint structures in the list */
	Ppoint	*points;	/* list of points */
.sp .2
} Ppoint_list;
.fi
.IP
The \fInum_points\fP component specifies the number of points used to define
the fill area. The \fIpoints\fP component is a pointer to a list,
\fInum_points\fP long, of Ppoint structures which contain the Modelling
Coordinates of each vertex of the fill area. Ppoint is defined in phigs.h
as follows:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.nf
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
.sp .2
} Ppoint;
.fi
.SS Execution
When the structure is traversed, the \s-2FILL AREA SET\s+2 element draws
the specified number of closed polygonal areas using the given points.
Each fill area forms a boundary by connecting the specified points in order.
Bounds will implicitly be closed by extending the boundary of the
fill area from the last point to the first.
.LP
The points are specified in Modelling Coordinates. These may be any
coordinate units that are convenient to the application.  At traversal,
these coordinates are transformed by the current Local and
global modelling transformations, the view representation
selected by the current view index, and
the workstation transformation current on the workstation to which the
structure is posted.
.\"See Chapter 7, "Transformations," in the \fI\s-2PEX-SI\s0 Programming
.\"Guide\fP for more information.
.LP
All the specified areas are drawn using the current values of the
primitive attributes listed below. The edge attributes, \s-2EDGE FLAG,
EDGETYPE, EDGEWIDTH SCALE FACTOR\s+2, and \s-2EDGE COLOUR INDEX\s+2 allow
you to control whether, and how, the edges of the areas are displayed
independently of the interior representation.
.\"Edges are not affected by any shading or lighting applied to the
.\"interior of the areas.
.LP
.SS Using Edge Attributes with Interior Style \s-2HOLLOW\s+2
.\"\fBUsing Edge Attributes With Interior Style \s-2HOLLOW\s+2\fP
.LP
If edges are not displayed, and the \s-2INTERIOR STYLE\s+2 is
\s-2HOLLOW\s+2, only the boundaries of the fill areas are drawn using the
interior colour.  If edges are displayed when the \s-2INTERIOR STYLE\s+2
is \s-2 HOLLOW\s+2, the edges will overlay the boundaries using the edge
colour.  If the \s-2EDGETYPE\s+2 is a broken line, the boundaries will
show through the breaks in the edge representation.
.SS Attributes Applied
The attributes listed below are used to display the
\s-2FILL AREA SET\s+2 primitive when the structure is traversed.
The Aspect Source 
Flags (\s-2ASF\s+2s) tell where to access the output display attributes. 
These attributes can come directly from the traversal state list,
or they can be accessed indirectly, using the appropriate index 
in the traversal state list and the corresponding bundled 
representation in the PHIGS workstation state list.
.RS
.nf
.ta .5i +\w'back interior reflectance equation   'u 
.sp
interior colour			interior colour index \s-2ASF\s+2
back interior colour		back interior colour \s-2ASF\s+2
interior style			interior style \s-2ASF\s+2
back interior style		back interior style \s-2ASF\s+2
interior style index		interior style index \s-2ASF\s+2
back interior style index	back interior style index \s-2ASF\s+2
interior shading method		interior shading method \s-2ASF\s+2
back interior shading method	back interior shading method \s-2ASF\s+2
interior reflectance equation 	interior reflectance equation \s-2ASF\s+2
back interior reflectance equation	back interior reflectance equation \s-2ASF\s+2
area properties			area properties \s-2ASF\s+2
back area properties		back area properties \s-2ASF\s+2
interior index
edge colour			edge colour index \s-2ASF\s+2
edge flag			edge flag \s-2ASF\s+2
edgetype			edgetype \s-2ASF\s+2
edgewidth scale factor		edgewidth scale factor \s-2ASF\s+2
edge index
face distinguishing mode
face culling mode
depth cue index
light source state
name set
.fi
.RE
.sp .2
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP, *, STOP, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "FILL AREA (3P)"
.SM "FILL AREA SET 3 (3P)"
.SM "FILL AREA SET 3 WITH DATA (3P+)"
.fi