.\"##
.\" $XConsortium: p025,v 5.2 94/04/17 20:54:29 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-2COMPUTE FILL AREA SET GEOMETRIC NORMAL\s+2
.TH "COMPUTE FILL AREA SET GEOMETRIC NORMAL" 3P+ "29 February 1991"
.SH NAME
COMPUTE FILL AREA SET GEOMETRIC NORMAL \-  compute geometric normal of the
fill area set   
.IX "PHIGS Extension Functions" "COMPUTE FILL AREA SET GEOMETRIC NORMAL"
.IX "Normals" "COMPUTE FILL AREA SET GEOMETRIC NORMAL"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pcomp_fill_area_set_gnorm ( vflag, nfa, vdata, error_ind, normal )
Pint	vflag;	\fIwhat vertex data is available\fP
Pint	nfa;		\fInumber of fill areas\fP
Pfacet_vdata_list3	*vdata;		\fIfill area data\fP
Pint	*error_ind;	\fIOUT error indicator\fP
Pvec3	*normal;	\fIOUT geometric normal\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2COMPUTE FILL AREA SET GEOMETRIC NORMAL\s+2 computes the geometric
normal of the fill area set.
.LP
This is a \s-2PHIGS\s0 Extension function based on \s-2PHIGS PLUS\s+2
and is not part of the 
\s-2PHIGS\s+2 standard.
.SS C Input Parameters
All of the following data types are predefined in phigs.h.
.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_NORMAL     'u
0	PVERT_COORD	\fICoordinates Specified\fP
1	PVERT_COORD_COLOUR	\fICoordinates and Vertex Colour Specified\fP
2	PVERT_COORD_NORMAL	\fICoordinates and Vertex Normal Specified\fP
3	PVERT_COORD_COLOUR_NORMAL	\fICoordinates, Vertex Colour, and 
				Vertex Normal Specified\fP
.sp
.fi
.IP \fInfa\fR
The number of fill areas in the set.
.sp .5
.IP \fIvdata\fR
A pointer, to a list of nfa Pfacet_vdata_list3 structures,
that specifies the fill area set and
optionally associated colour information. Pfacet_vdata_list3 is defined as 
follows:
.sp .2
.nf
.ta .5i +\w'Pfacet_vdata_arr3    'u +\w'num_vertices;    'u
.sp .2
typedef struct {
.sp .2
	Pint	num_vertices;	/* number of vertices */
	Pfacet_vdata_arr3	vertex_data;	/* array of facet vertex data */
.sp .2
} Pfacet_vdata_list3;
.IP
.fi
Pfacet_vdata_arr3 is defined as follows:
.sp .2
.nf
.ta .5i +\w'Pptconorm3     'u +\w'*ptconorms;     'u
.sp .2
typedef union {	
.sp .2			
	Ppoint3	*points;	/* point */
	Pptco3	*ptcolrs;	/* point and color */
	Pptnorm3	*ptnorms;	/* point and normal */	
	Pptconorm3	*ptconorms;	/* point, color, and norml */
	/* implementation dependent types can go here */
.sp .2
} Pfacet_vdata_arr3;
.fi
.IP
Ppoint3 is defined 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 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 as follows:	 
.sp .2
.nf
.ta .5i +\w'Pcolr_rep     'u +\w'direct;	     'u
.sp .2
typedef union {	
.sp .2
	Pint	index;	/* index in workstation colour bundle table */
	Pcolr_rep	direct;	/* direct colour components */
.sp .2
} Pcoval;
.IP
.fi
Pcolr_rep is defined as follows:
.sp .2
.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
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
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
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 follows:
.sp .2
.nf
.ta .5i +\w'Pvec3     'u +\w'colour;     'u
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pvec3	normal;	/* norm */
.sp .2
} Pptnorm3;
.fi
.IP
Ppoint3 is defined above.
Pvec3 is defined as follows: 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {	
.sp .2
	Pfloat	x_val;	/* x magnitude */
	Pfloat	y_val;	/* y magnitude */
	Pfloat	z_val;	/* z magnitude */
.sp .2
} Pvec3;
.IP
.fi
Pptconorm3 is defined as follows: 
.sp .2
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {	
.sp .2
	Ppoint3	point;	/* point coordinates */
	Pcoval	colr;	/* colour */
	Pvec3	normal;	/* norm */
.sp .2
} Pptconorm3;
.IP
.fi
Ppoint3, Pcoval, and Pvec3 are defined above.
.SS C Output Parameters
.IP \fIerror_ind\fR
A pointer to the location to store the error number.
.IP \fInorm\fR
A pointer to the location to store the computed geometric normal. (Pvec3
is defined above.)
.fi
.SS Execution
The normalized geometric norm is computed for the fill area set 
defined by the supplied vertex coordinates. The geometric
normal is computed by first selecting three points: \fI\s-2A\s+2\fP,
\fI\s-2B\s+2\fP, and \fI\s-2C\s+2\fP.
Point \fI\s-2A\s+2\fP is the first point in the first list of vertices.
Point \fI\s-2B\s+2\fP
is the next point in that list that is noncoincident with 
\fI\s-2A\s+2\fP.
Point \fI\s-2C\s+2\fP is the next point in that list, after 
\fI\s-2B\s+2\fP, that is noncolinear
with \fI\s-2A\s+2\fP and \fI\s-2B\s+2\fP. The geometric normal 
is the cross product of the vector
extending from \fI\s-2A\s+2\fP to \fI\s-2B\s+2\fP with the vector
extending from \fI\s-2A\s+2\fP to \fI\s-2C\s+2\fP.
.LP
If it is not possible to find three such points in the first list
of vertices, then the rest of the lists are searched in order to
select three appropriate points from a single list. In case the 
search fails in all lists, then it is determined that the fill area
set is degenerate.
.sp .2
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP,*,*,*\s+2)
.IP 612
Warning, the fill area is degenerate
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "FILL AREA SET 3 (3P)"
.SM "FILL AREA SET 3 WITH DATA (3P+)"
.fi