.\"##
.\" $XConsortium: p347,v 5.2 94/04/17 20:58:28 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 MODELLING CLIPPING VOLUME 3" 3P "29 February 1991"
.SH NAME
SET MODELLING CLIPPING VOLUME 3 \- create structure element to set the 
current 3D modelling clipping volume
.IX "Modelling Clipping" "SET MODELLING CLIPPING VOLUME 3"
.IX "Modelling and Transformation Attributes" "SET MODELLING CLIPPING VOLUME 3"
.IX "Attributes, Modelling and Transformation Attributes" "SET MODELLING CLIPPING VOLUME 3"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_model_clip_vol3 ( op, half_spaces )
Pint	op;	\fIoperator\fP
Phalf_space_list3	*half_spaces;	\fIlist of half-spaces\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
.LP
\s-2SET MODELLING CLIPPING VOLUME 3\s+2
creates a structure element
containing the operator and half-spaces specified, and places the element
in the current structure.  During traversal, this element is used to
modify the value of the current modelling clipping volume attribute,
which may affect all output primitives.
.LP
A \s-2SET MODELLING CLIPPING VOLUME 3\s+2 element contains half-spaces in 
the model space.  Each specified half-space is transformed by the current 
composite modelling transformation. These half-spaces are intersected 
to form a clipping volume.  
If no half-spaces are provided, the clipping volume is defined to be all 
of modelling coordinate space.  Clipping volume is combined as specified by 
\s-2OPERATOR\s+2 with \fIcurrent modelling clipping volume\fP to form a new 
value of \fIcurrent modelling clipping volume\fP.  This volume is used to clip 
subsequent output primitives during structure traversal. 
.\" The resulting 
.\" clipping volume is not affected by subsequent modelling transformation 
.\" elements encountered during structure traversal.
.\".LP
.\"\fBNote:\fP This function places the appropriate data in the
.\"Central Structure Store and in \s-2PEX-SI\s0 archives,
.\"but the structure element is currently ignored during traversal.
.SS C Input Parameters
.IP \fIop\fP
The operator that describes the application of the
half-spaces
in this element to the current modelling clipping volume.
Operator values defined in phigs.h are:
.nf
.ta .5i +\w'PMC_INTERSECT     'u
.sp .2
	PMC_REPLACE	\fIReplace\fP
	PMC_INTERSECT	\fIIntersect\fP
.fi
.sp .2
.IP \fIhalf_spaces\fP
The list of half-spaces to store in the element.
Phalf_space_list3 is defined in phigs.h as:
.nf
.ta .5i +\w'Phalf_space3     'u +\w'num_half_spaces;     'u
.sp .4
typedef struct {
.sp .2
	Pint	num_half_spaces; 	/* number of half-spaces */
	Phalf_space3	*half_spaces;	/* list of half-spaces */
.sp .2
} Phalf_space_list3;
.fi
.sp
The number
is the number of half-spaces in the array of Phalf_space3
elements pointed to by
half-spaces,
as specified by a point, and the normal to the plane containing the point,
in the direction of the half-space.
Phalf_space3 is defined in phigs.h as:
.nf
.ta .5i +\w'Pvec3     'u +\w'norm;     'u
.sp .4
typedef struct {
.sp .2
	Ppoint3	point;	/* point */
	Pvec3	norm;	/* normal */
.sp .2
} Phalf_space3;
.fi
.sp
Ppoint3 and Pvec3 are similar structures (but have different semantics), defined by phigs.h:
.nf
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.sp .4
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.sp
.nf
.ta .5i +\w'Pfloat     'u +\w'delta_x;     'u
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.fi
.SS Execution
.LP 
If the current edit mode is \s-2INSERT\s+2, a
\s-2SET MODELLING CLIPPING VOLUME 3\s+2 element is inserted
into the currently open
structure after the element pointed to by the current element pointer. If
the edit mode is \s-2REPLACE\s+2, the new element
replaces the element pointed to by the element pointer. In either case, the
element pointer is updated to point to the new element.
.LP
During traversal, this element is used to
modify the value of the current modelling clipping volume attribute,
which affects all output primitives.  
This volume is used to clip 
subsequent output primitives during structure traversal. 
.\" The resulting 
.\" clipping volume is not affected by subsequent modelling transformation 
.\" elements encountered during structure traversal. 
.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 "INQUIRE MODELLING CLIPPING FACILITIES (3P)"
.SM "SET MODELLING CLIPPING INDICATOR (3P)"
.SM "RESTORE MODELLING CLIPPING VOLUME (3P)"
.SM "SET MODELLING CLIPPING VOLUME (3P)"
.fi