.\"##
.\" $XConsortium: p361,v 5.2 94/04/17 20:58:39 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 "SET POLYLINE REPRESENTATION" 3P "29 February 1991"
.SH NAME
SET POLYLINE REPRESENTATION \- define a polyline attribute bundle on a
workstation
.IX "Attribute Representations" "SET POLYLINE REPRESENTATION"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.5i 3i
.nf
void
pset_line_rep ( ws, index, rep )
Pint	ws;	\fIworkstation identifier\fP
Pint	index;	\fIpolyline bundle index\fP
Pline_bundle	*rep;	\fIpolyline representation pointer\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET POLYLINE REPRESENTATION\s+2
defines a bundle of polyline attributes
for a specified entry in the workstation's polyline bundle table.  
Depending on the \s-1ASF\s0 for each of the polyline attributes,
the bundled attributes may apply to the following primitives:
.RS
.ta 0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i
.LP
\(bu
.SM "POLYLINE"
.LP
\(bu 
.SM "POLYLINE 3"
.LP
\(bu
.SM "POLYLINE SET 3 WITH DATA"
.LP
\(bu
.SM "NON-UNIFORM B-SPLINE CURVE"
.LP
\(bu
.SM "ANNOTATION TEXT RELATIVE (when ``connected'' style is in use)"
.LP
\(bu
.SM "ANNOTATION TEXT RELATIVE 3 (when ``connected'' style is in use)"
.LP
\(bu
.SM "CELL ARRAY (when minimal simulation is performed)"
.LP
\(bu
.SM "CELL ARRAY 3 (when minimal simulation is performed)"
.ta
.RE
.\"PHIGS+:    \fBNote:\fP A separate subroutine, \s-2SET POLYLINE
.\"PHIGS+:    REPRESENTATION PLUS\s+2, sets these same attributes in the polyline
.\"PHIGS+:    bundle and also sets a value for polyline shading method. Use
.\"PHIGS+:    \s-2SET POLYLINE REPRESENTATION PLUS\s+2 when you are
.\"PHIGS+:    applying lighting and shading to your display
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation for which the polyline
representation is being defined.  
.IP \fIindex\fP
The \fIpolyline index\fP of the entry being defined.  
.IP \fIrep\fP
A pointer to a structure containing the 
attribute values defining the polyline representation, defined as follows:  
.nf
.ta .5i +\w'Pinterstyle 'u +\w'*integers;    'u
.sp .2
typedef struct {
.sp .2
	Pint	type;	/* line type */
	Pfloat	width;	/* linewidth scale factor */
	Pint	colr_ind;	/* colour index */
.sp .2
} Pline_bundle;
.fi
.sp
\fIrep->type\fP is an integer value specifying a linetype;
the following line types are defined:  
.nf
.ta .5i +.5i +1.5i +1i
.sp .2
1	PLINE_SOLID	\fISolid\fP
2	PLINE_DASH	\fIDashed\fP
3	PLINE_DOT	\fIDotted\fP
4	PLINE_DOT_DASH	\fIDot-dashed\fP
.sp .2
.fi
Support for \fIlinetypes\fP is workstation dependent.  
.sp
\fIrep->width\fP is the \fIlinewidth scale factor\fP.  
.sp
\fIrep->colr_ind\fP is the \fIpolyline colour\fP
index, which selects a colour value from the workstation's colour table.  
.SS Execution
When \s-2SET POLYLINE REPRESENTATION\s+2 is called, the polyline index 
entry in the table of defined polyline representations on the workstation 
is set to the linetype, linewidth scale factor, and polyline colour index values.
.LP
When polyline output primitives are displayed, the polyline
representation specified by the current polyline index entry in the
traversal state list provides the polyline attributes
for which the Aspect Source Flag (\s-2ASF\s+2) is \s-2BUNDLED\s+2.  
For example, when the current linetype \s-2ASF\s+2 is set to \s-2BUNDLED\s+2,
the effective linetype is
the linetype attribute in the polyline representation selected by
the current polyline index.  The current polyline index
is set by \s-2SET POLYLINE INDEX\s+2 elements.  
.\"PHIGS+:  .LP
.\"PHIGS+:  The source for polyline colour is determined by a combination of
.\"PHIGS+:  the polyline Colour Source Flag (CSF) and the polyline colour
.\"PHIGS+:  index ASF. While the polyline CSF is set to \s-2DIRECT\s+2,
.\"PHIGS+:  polyline colour is determined by a direct colour specification set
.\"PHIGS+:  with the \s-2SET POLYLINE COLOUR\s+2 subroutine, and the polyline
.\"PHIGS+:  colour index ASF has no effect. When the polyline colour CSF
.\"PHIGS+:  is set to \s-2INDEXED\s+2, the polyline colour index ASF
.\"PHIGS+:  determines whether the attribute is defined by a bundled or
.\"PHIGS+:  individual specification in the same way as the other attributes.
.LP
The polyline bundle table is numbered from 1.  
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(that is, the workstation category is neither 
\s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2)
.IP 100
Ignoring function, the bundle index value is less than one
.IP 103
Ignoring function, setting this bundle table entry would exceed
the maximum number of entries allowed in the workstation bundle table
.IP 104
Ignoring function, the specified line type is not available
on the specified workstation
.IP 113
Ignoring function, the colour index value is less than zero
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET POLYLINE INDEX (3P)"
.SM "SET INDIVIDUAL ASF (3P)"
.SM "INQUIRE POLYLINE FACILITIES (3P)"
.SM "INQUIRE POLYLINE REPRESENTATION (3P)"
.SM "SET LINETYPE (3P)"
.SM "SET LINEWIDTH SCALE FACTOR (3P)"
.SM "SET POLYLINE COLOUR INDEX (3P)"
.SM "SET POLYLINE COLOUR (3P+)"
.SM "SET POLYLINE REPRESENTATION PLUS (3P+)"
.fi