.\"##
.\" $XConsortium: p320,v 5.2 94/04/17 20:58:09 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 Extension function name (in CAPS) for "PNAME" in line be.\"low:
.ds pN SET FACE DISTINGUISHING MODE
.TH "\*(pN" 3P+ "29 February 1991"
.SH NAME
\*(pN \-
create a structure element to set the face distinguishing mode
.IX "PHIGS Extension Functions" "\*(pN"
.IX "Filled Area Interior Attributes" "SET FACE DISTINGUISHING MODE"
.IX "Attributes, Filled Area Interior Attributes" "SET FACE DISTINGUISHING MODE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
.\" 6. Insert C syntax below
.nf
void
pset_face_disting_mode ( mode )
Pdisting_mode	mode;	\fIdistinguishing mode\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET FACE DISTINGUISHING MODE\s+2 creates a structure element
to set the face distinguishing mode.
The attribute face distinguishing mode defines control over the 
attributes applied when rendering front and back facing portions of area 
defining primitives.
.LP
An application indirectly specifies which of the two faces of an
area-defining primitive is the front face, by the ordering of the vertex
data.
.LP
A facet of an area defining primitive is defined to be back facing
if its geometric normal has a negative \fIz\fP component when transformed
to \s-2NPC\s+2; otherwise, the facet is front facing. 
.LP
If facet normals are supplied, they are used as geometric normals;
otherwise, a geometric normal is computed for each facet using a method
that depends on the primitive type:
.IP "\fIFill Area\fP or \fIFill Area Set\fP"
A geometric normal is computed
by first determining 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 of the vertices. Point \fI\s-2B\s+2\fP is the next point in the
list that is non-coincident with \fI\s-2A\s+2\fP. Point \fI\s-2C\s+2\fP
is the next point in
the list (after \fI\s-2B\s+2\fP) that is non-colinear 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. The utility function
\s-2COMPUTE FILL AREA SET GEOMETRIC NORMAL (3P+)\s+2 can be used to determine
the geometric normal for a fill area set primitive according to
the above procedure.
.\".LP
.IP "\fITriangle Strip Primitive\fP"
Determination of the
geometric normal for each triangle is computed as for a fill area,
using the vertices of the triangle. Order of facets in triangles
is reversed for even numbered facets, with facets numbering
starting at 1. 
.IP "\fIQuadrilateral Mesh Primitive\fP"
Determination of the
geometric normal for each quadrilateral is calculated by taking
the cross product of its diagonals.
.IP "\fINon-uniform B-Spline Surface\fP"
The geometric normal is computed
as the normalized cross product of the tangent vector along the \fIu\fP
direction and the tangent vector along the \fIv\fP direction.
.ig XX
.LP
Notice that when the geometric normal is computed, the order of
points determines the sense of
direction; that is, whether it is front or back facing.
.XX
.SS C Input Parameters
.IP \fImode\fP
A pointer to a Pdisting_mode structure. A  Pdisting_mode structure is
defined as:
.sp .4
.nf
.ta .5i
typedef enum {
.sp .2
	PDISTING_NO,
	PDISTING_YES
.sp .2
} Pdisting_mode;
.fi
.SS Execution
Depending on the edit mode, a \s-2SET FACE DISTINGUISHING MODE\s+2
element is inserted into the open structure after the element pointer,
or replaces the element pointed at by the element pointer. The element
pointer is then updated to point to the new
\s-2SET FACE DISTINGUISHING MODE (3P+)\s+2
element.
.LP
When the face distinguishing mode
is \fINo\fP, the back face attributes are not
used, and the front face attributes are used for both front facing and 
back facing portions of the primitives. When the face distinguishing mode
is \fIYes\fP, the back face
attributes are used for back facing portions.
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP, *, STOP, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET FACE CULLING MODE (3P+)"
.fi