.\"##
.\" $XConsortium: p244,v 5.2 94/04/17 20:57:17 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         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 name of Sun Microsystems,
.\"## 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 "POLYLINE 3" 3P "29 February 1991"
.SH NAME
POLYLINE 3 \- create structure element specifying \s-2\&3D\s+2 polyline
.IX "Line Primitives" "POLYLINE 3"
.IX "Primitives, Line Primitives" "POLYLINE 3"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
ppolyline3 ( point_list )
Ppoint_list3	*point_list;	\fIlist of points\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
The \s-2POLYLINE 3\s+2 function places a structure element containing
the full specification of a \s-2\&3D\s+2 polyline into the currently open structure,
according to the current edit mode.
A \s-2\&3D\s+2 polyline primitive is a set of connected straight lines in \s-2\&3D\s+2 space
defined by a series of Modelling Coordinate (\s-2MC\s+2) points. A polyline may
be closed or self-intersecting.
.SS C Input Parameters
.IP \fIpoint_list\fP
A pointer to a Ppoint_list3 structure containing a list of Ppoint3 structures,
which contain the \fIx\fP, \fIy\fP, and \fIz\fR coordinates for each point.
At least two points must be specified; a polyline structure element that has
fewer than two points will be treated in a workstation dependent fashion.
.IP
The Ppoint_list3 structure is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Ppoint3	'u +\w'num_points;     'u
.nf
typedef struct  {
.sp .2
	Pint	num_points;	/* number of Ppoint3s in the list */
	Ppoint3	*points;	/* list of points */
.sp .2
} Ppoint_list3;
.sp .4
.fi
The \fInum_points\fR component specifies the number of elements in the list.
The \fIpoints\fR component is a pointer to a list of Ppoint3s \fInum_points\fR long.
The Ppoint3 structure 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 */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.fi
.SS Execution
.LP
If the current edit mode is \s-2INSERT\s+2, the \s-2POLYLINE 3\s+2 element
is inserted into the open structure after the element pointed to by the
element pointer. If the current edit mode is \s-2REPLACE\s+2, the
\s-2POLYLINE 3\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-2POLYLINE 3\s+2 element.
.LP
When the structure is traversed, the polyline element draws straight
lines between the points specified, beginning with the first point
and ending with the last. The current values of the attributes listed
below will be applied to the polyline when it is drawn.
.LP
The coordinates used to specify the polyline primitive are called
Model Coordinates (\s-2MC\s+2).
Model Coordinates can be any coordinate units that are convenient to the application.
At traversal, these coordinate values are transformed by the current local
and global modelling transformations, the view representation selected by
the \fIcurrent view index\fP, and the workstation transformation current
on the workstation to which the structure is posted.
.SS Attributes Applied
The attributes listed below are used to display the
\s-2POLYLINE 3\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
polyline colour	polyline	colour index \s-2ASF\s+2
linewidth scale factor		linewidth scale factor \s-2ASF\s+2
linetype			linetype \s-2ASF\s+2
polyline shading method		polyline shading method \s-2ASF\s+2
polyline index
depth cue index
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 "INQUIRE POLYLINE FACILITIES (3P)"
.SM "POLYLINE (3P)"
.SM "POLYLINE SET 3 WITH DATA (3P+)"
.fi