path: root/xc/unsupported/doc/PHIGS/man3/p399

.\"##
.\" $XConsortium: p399,v 5.2 94/04/17 20:59:06 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.
.\" 1. Substitute PHIGS PLUS function name (in CAPS) for "PNAME" in line below:
.ds pN TRIANGLE STRIP 3 WITH DATA
.TH "\*(pN" 3P+ "29 February 1991"
.SH NAME
\*(pN \- creates a \s-2\&3D\s+2 triangle strip structure element
that includes colour and shading data
.IX "PHIGS Extension Functions" "\*(pN"
.IX "Filled Area Primitives" "TRIANGLE STRIP 3 WITH DATA"
.IX "Primitives, Filled Area Primitives" "TRIANGLE STRIP 3 WITH DATA"
.IX "TRIANGLE STRIP 3 WITH DATA" "" "" "" PRINT "See Filled Area Primitives"
.IX "Strip" "TRIANGLE STRIP 3 WITH DATA"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
.\" 6. Insert C syntax below
void
ptri_strip3_data ( fflag, vflag, colour_model, nv, fdata, vdata )
Pint	fflag;	\fIwhat data is specified per facet\fP
Pint	vflag;	\fIwhat data is specified per vertex\fP
Pint	colour_model;	\fIcolour model\fP
Pint	nv;	\fInumber of vertices\fP
Pfacet_data_arr3	*fdata;	\fIfacet data\fP
Pfacet_vdata_arr3	*vdata;	\fIfacet vertex data\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2TRIANGLE STRIP 3 WITH DATA\s+2 
places a \s-2\&3D\s+2 triangle strip primitive with colour and shading data into
the open structure. 
.SS C Input Parameters
.IP \fIfflag\fR
The data per facet flag specifies the available data for each facet
in the strip.
.sp
.nf
.ta .5i +\w'0     'u +\w'PFACET_COLOUR_NORMAL    'u
0	PFACET_NONE	\fINo Facet Coordinates Specified\fP
1	PFACET_COLOUR	\fIFacet Colours Specified\fP
2	PFACET_NORMAL	\fIFacet Normal Specified\fP
3	PFACET_COLOUR_NORMAL	\fIFacet Normal and Colours Specified\fP
.sp
.fi
.IP \fIvflag\fR
The data per vertex flag specifies the available data for
each vertex of the primitive.
.sp
.nf
.ta .5i +2.5i +1i
0	PVERT_COORD	\fICoordinates Specified\fP
1	PVERT_COORD_COLOUR	\fICoordinates and Colours Specified\fP
2	PVERT_COORD_NORMAL	\fICoordinates and Normals Specified\fP 
3	PVERT_COORD_COLOUR_NORMAL	\fICoordinates, Colours, and Normals Specified\fP
.fi
.sp 
.IP \fIcolour_model\fR
The colour type for specified vertex colours.
.sp
.nf
.ta .5i +1.5i +1i
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 \fInv\fR
The number of vertices.
.IP \fIfdata\fR
A pointer, to a Pfacet_data_arr3 structure,
that specifies the colours and/or norms information for
each facet. Pfacet_data_arr3 is defined as:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef union {	
.sp .2	
	Pcoval	*colrs;	/* array (nv-2) of colours */
	Pvec3	*norms;	/* array (nv-2) of unit normals */
	Pconorm3	*conorms;	/* array (nv-2) of colours and normals */
	/* implementation-dependent types can go here */
.sp .2
} Pfacet_data_arr3;
.IP
.fi	
Pcoval is defined as: 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef union {	
.sp .2
	Pint	ind;	/* index in workstation colour bundle table */
	Pcolr_rep	direct;	/* direct colour components */
.sp .2
} Pcoval;
.fi
.IP
Pcolr_rep is defined as:
.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
.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 {
.yp .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
.IP
Pvec3 is defined as:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.IP
.fi
Pconorm3 is defined as:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pcoval	colr;	/* colour */
	Pvec3	norm;	/* unit normal */
.sp .2
} Pconorm3;
.IP
.fi
Pcoval and Pvec3 are defined above.
.IP \fIvdata\fR
A pointer, to a Pfacet_vdata_arr3 structure,
that specifies the coordinates of each triangle and
optionally associated colour information. Pfacet_vdata_arr3 is defined as: 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef union {	
.sp .2			
	Ppoint3	*points;	/* array (nv) of points */
	Pptco3	*ptcolrs;	/* array (nv) of points and colours */
	Pptnorm3	*ptnorms;	/* array (nv) of points and normals */
	Pptconorm3	*ptconorms;	/* array (nv) of points, colours, and normals */
	/* implementation dependent types can go here */
.sp .2
} Pfacet_vdata_arr3;
.IP
.fi
Ppoint3 is defined as: 
.sp .2
.nf
.ta .5i +1i +1i
.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 as:
.sp .2
.nf
.ta .5i +1i +1i
.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 as:	 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef union {	
.sp .2
	Pint	ind;	/* index in workstation colour bundle table */
	Pcolr_rep	direct;	/* direct colour components */
.sp .2
} Pcoval;
.IP
.fi
Pcolr_rep is defined as:
.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
.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 {
.yp .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
.IP
Pptnorm3 is defined as:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pvec3	norm;	/* unit normal */
.sp .2
} Pptnorm3;
.IP
.fi
Ppoint3 is defined above.
Pvec3 is defined as:
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.IP
.fi
Pptconorm3 is defined as: 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pcoval	colr;	/* colour */
	Pvec3	norm;	/* unit normal */
	/* point coordinates with colour and unit normal */
.sp .2
} Pptconorm3;
.IP
.fi
Ppoint3, Pcoval, and Pvec3 are defined above.
.fi
.SS Execution
Depending on the edit mode, a \s-2TRIANGLE STRIP 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-2TRIANGLE STRIP 3 WITH DATA\s+2 element.
.LP
When the structure is traversed, \s-2TRIANGLE STRIP 3 WITH DATA\s+2
generates a strip of \fIn\fP-2 connected triangles from \fIn\fP vertices. 
Line segments form the boundaries of all triangles in the strip. The 
triangular areas within the strip can be empty, hollow, shaded, or
filled with a color, pattern, or hatch style. A strip with less than 
three vertices can be created, but is ignored during traversal.
.LP
\s-2TRIANGLE STRIP 3 WITH DATA\s+2 uses the same attributes as the
\s-2FILL AREA SET 3 WITH DATA\s+2 structure element.   
.LP
The \s-2TRIANGLE STRIP 3 WITH DATA\s+2 element can specify the facet
colour and normal vector of each triangle, as well as colours and normal
vectors for each vertex. These colours and normal vectors are used in 
conjunction with the current lighting and depth cueing attributes to 
colour and shade the primitive. Note that unexpected lighting effects 
will result if the supplied normals are not of unit length. 
.SS Attributes Applied
The attributes listed below are used to display the
\s-2TRIANGLE STRIP 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 \fI\s-2PHIGS\s+2 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\s+2, \s-2*\s+2, \s-2STOP\s+2, \s-2*\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "FILL AREA SET 3 WITH DATA (3P+)"
.fi