.\"##
.\" $XConsortium: p346,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" 3P "29 February 1991"
.SH NAME
SET MODELLING CLIPPING VOLUME \- create structure element to set the current modelling clipping volume
.IX "Modelling and Transformation Attributes" "SET MODELLING CLIPPING VOLUME"
.IX "Modelling Clipping" "SET MODELLING CLIPPING VOLUME"
.IX "Attributes, Modelling and Transformation Attributes" "SET MODELLING CLIPPING VOLUME"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_model_clip_vol ( op, half_spaces )
Pint	op;	\fIoperator\fP
Phalf_space_list	*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\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\s+2 element contains two-dimensional 
half-spaces.  Each specified half-space is expanded to a three-dimensional 
half-space by setting the \fIz\fP-coordinate of the point and normal 
vector to zero.  These half-spaces are then transformed by the current 
composite modelling transformation.  These half-spaces are intersected 
to form a clipping volume.  
If no half-spaces are provided, then 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.
.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_list is defined in phigs.h as:
.nf
.ta .5i +\w'Phalf_space     'u +\w'num_half_spaces;     'u
.sp .4
typedef struct {
.sp .2
	Pint	num_half_spaces; 	/* number of half-spaces */
	Phalf_space	*half_spaces;	/* list of half-spaces */
.sp .2
} Phalf_space_list;
.fi
.sp .2
The number is the number of half-spaces in the array of Phalf_space
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_space is defined in phigs.h as:
.nf
.ta .5i +\w'Ppoint   'u +\w'norm;     'u
.sp .4
typedef struct {
.sp .2
	Ppoint	point;	/* point */
	Pvec	norm;	/* normal */
.sp .2
} Phalf_space;
.fi
.sp
Ppoint and Pvec 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 */
.sp .2
} Ppoint;
.sp
.ta .5i +\w'Pfloat     'u +\w'delta_x;     'u
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
.sp .2
} Pvec;
.fi
.sp
The \s-2\&2D\s+2 point and normal vector are expanded to \s-2\&3D\s+2 by using
.I z
components equal to 0.
.SS Execution
.LP
If the current edit mode is \s-2INSERT\s+2, a
\s-2SET MODELLING CLIPPING VOLUME\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 3 (3P)"
.fi
