.\"##
.\" $XConsortium: p245,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.
.ds f \s-2POLYLINE SET 3 WITH DATA\s+2
.TH "POLYLINE SET 3 WITH DATA" 3P+ "29 February 1991"
.SH NAME
POLYLINE SET 3 WITH DATA \- create a \s-2\&3D\s+2 polyline set
structure element that includes colour and shading data  
.IX "PHIGS Extension Functions" "POLYLINE SET 3 WITH DATA"
.IX "Line Primitives" "POLYLINE SET 3 WITH DATA"
.IX "Primitives, Line Primitives" "POLYLINE SET 3 WITH DATA"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
ppolyline_set3_data ( vflag, colour_type, npl, vdata )
Pint	vflag;	\fIdata per vertex flag\fP
Pint	colour_type;	\fIcolour type\fP
Pint	npl;	\fInumber of polylines in the set\fP
Pline_vdata_list3	*vdata;	\fIper line vertex data list\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2POLYLINE SET 3 WITH DATA\s+2 
creates a \s-2\&3D\s+2 polyline set primitive with colour and shading data.
.LP
A \s-2\&3D\s+2 polyline with data primitive is a set of connected lines
in a \s-2\&3D\s+2 space defined by a series of Modelling Coordinate points.
The element can optionally specify colour information
for each vertex of the primitive.
.SS C Input Parameters
.IP \fIvflag\fR
The data per vertex flag specifies the available data for each vertex of the primitive.
.sp
.nf
.ta .5i +\w'0     'u +\w'PVERT_COORD_COLOUR     'u
0	PVERT_COORD	\fICoordinates Specified\fP
1	PVERT_COORD_COLOUR	\fICoordinates and Colours Specified\fP
.sp
.fi
.IP \fIcolour_type\fR
The colour type for specified vertex colours.
.sp
.nf
.ta .5i +\w'0     'u +\w'PMODEL_CIELUV     'u
0	PINDIRECT	\fIColour Index Specified\fP
1	PMODEL_RGB	\fIRed, Green, and Blue\fP
2	PMODEL_CIELUV	\fICIE Colour Model\fP
3	PMODEL_HSV	\fIHue, Saturation, and Value\fP
4	PMODEL_HLS	\fIHue, Lightness, and Saturation\fP
.sp
.fi
.IP \fInpl\fP
The number of polylines in the set.
.IP \fIvdata\fR
A pointer to an array of \fInpl\fP Pline_vdata_list3 structures that specifies
the list of vertices and optionally associated colour information.
Pline_vdata_list3 is defined in phigs.h as follows:
.sp .4
.nf
.ta .5i +\w'Pline_vdata_arr3     'u +\w'num_vertices;     'u
typedef struct {
.sp .2
	Pint	num_vertices;	/* number of vertices */
	Pline_vdata_arr3	vertex_data;	/* line vertex data */
.sp .2
} Pline_vdata_list3;
.IP
.fi
Pline_vdata_arr3 is defined in phigs.h as follows:
.ta .5i +\w'Ppoint3     'u +\w'*ptcolrs;     'u
.nf
.sp .4
typedef union {
.sp .2
	Ppoint3	*points;	/* array of points */
	Pptco3	*ptcolrs;	/* array of points with colours */
	/* implementation-dependent data */
.sp .2
}Pline_vdata_arr3;
.IP
.fi
Ppoint3 is defined in phigs.h as follows: 
.sp .2
.nf
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.sp .2
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.IP
.fi
Pptco3 is defined in phigs.h as follows: 
.sp .2
.nf
.ta .5i +\w'Ppoint3     'u +\w'point;     'u
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pcoval	colr;	/* colour */
.sp .2
} Pptco3;
.IP
.fi
Ppoint3 is defined above.
Pcoval is defined in phigs.h as follows: 
.sp .2
.nf
.ta .5i +\w'Pcolr_rep     'u +\w'colour;     'u
.sp .2
typedef union {	
.sp .2
	Pint	ind;	/* index in workstation colour bundle table */
	Pcolr_rep	direct;	/* direct colour components */
.sp .2
} Pcoval;
.sp .2
.fi
When \fIcolour_model\fP is \s-2PINDIRECT,\s+2 \fIind\fR is
used; otherwise, \fIdirect\fR is used.
.IP
Pcolr_rep is defined in phigs.h as follows:
.ta .5i +1i +1i
.nf
.sp .2
typedef union {
.sp .2
	Prgb	rgb;	/* Red Green Blue colour specification */
	Pcieluv	cieluv;	/* CIE L*U*V* colour specification */
	Phls	hls;	/* Hue Lightness Saturation colour specification */
	Phsv	hsv;	/* Hue Saturation Value colour specification */
	Pdata	unsupp;	/* Colour in unsupported colour model */
.sp .2
} Pcolr_rep;
.sp .2
.fi
.IP
Prgb is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	red;	/* red, hue, etc */
	Pfloat	green;	/* green, saturation, lightness, etc */
	Pfloat	blue;	/* blue, value, saturation, etc */
.sp .2
} Prgb;
.fi
.IP
Pcieluv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	cieluv_x;	/* x coefficient */
	Pfloat	cieluv_y;	/* y coefficient */
	Pfloat	cieluv_y_lum;	/* y luminance */
.sp .2
} Pcieluv;
.fi
.IP
Phls is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	hue;	/* hue */
	Pfloat	lightness;	/* lightness */
	Pfloat	satur;	/* saturation */
.sp .2
} Phls;
.fi
.IP
Phsv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	hue;	/* hue */
	Pfloat	satur;	/* saturation */
	Pfloat	value;	/* value */
.sp .2
} Phsv;
.fi
.IP
Pdata is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	size_t	size;	/* size of data */	
	char	*data	/* pointer to data */
.sp .2
} Pdata;
.fi
.SS Execution
Depending on the edit mode, a 
\s-2POLYLINE SET 3 WITH DATA\s+2  
element is inserted into the open structure after the element pointer,
or replaces the element pointed to by the element pointer. In either
case, the element pointer is updated to point to the newly created
\s-2POLYLINE SET 3 WITH DATA\s+2 element.
.LP
When the structure is traversed, \s-2POLYLINE SET 3 WITH DATA\s+2
generates a set of unconnected polylines defined by a set of points.
Each point sequence in the set generates connected line segments. 
Colour information for shading the line segments can be specified
with each point as part of the primitive definition.  
.LP
\s-2POLYLINE SET 3 WITH DATA\s+2 elements containing less than 
two points can be created, but are treated in a workstation-dependent fashion.
.SS Attributes Applied
The attributes listed below are used to display the
\s-2POLYLINE SET 3 WITH DATA\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\s+2, \s-2*\s+2, \s-2STOP\s+2, \s-2*\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INQUIRE POLYLINE FACILITIES PLUS (3P+)"
.SM "POLYLINE 3 (3P)"
.fi