.\"##
.\" $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