.\"##
.\" $XConsortium: p335,v 5.2 94/04/17 20:58:20 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 INVISIBILITY FILTER" 3P "29 February 1991"
.SH NAME
SET INVISIBILITY FILTER \- set the workstation's name set filter that 
determines which primitives are invisible
.IX "Invisibility" "SET INVISIBILITY FILTER"
.IX "Namesets" "SET INVISIBILITY FILTER"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_invis_filter ( ws, filter )
Pint	ws;	\fIworkstation identifier\fP
Pfilter	*filter;	\fIhighlighting filter\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET INVISIBILITY FILTER\s+2 sets the workstation's \fIinvisibility filter\fP,
which is compared to the traversal-time \fIcurrent name set\fP of each primitive
to determine if the primitive is invisible.  
.LP
The filter contains an \fIinclusion set\fP and an \fIexclusion set\fP of names.  
During traversal, a primitive is invisible
if at least one name in the current name set is in the inclusion set 
and no name in the current name set is in the exclusion set.  
This means the exclusion set has precedence over the inclusion set.  
Each name in the current name set, inclusion set, and exclusion set
is a small positive integer.
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation whose invisibility filter is to be set.
.IP \fIfilter\fP
A pointer to a Pfilter structure containing the inclusion set and exclusion set
of names. Pfilter is defined in phigs.h as follows:
.sp .2
.ta .5i +1i +1.25i
.nf
typedef struct {
.sp .2
	Pint_list	incl_set;	/* inclusion set */
	Pint_list	excl_set;	/* exclusion set */
.sp .2
} Pfilter;
.fi
.sp .4
The Pint_list structure is defined in phigs.h as follows:
.sp .2
.ta .5i +\w'Pint	'u +\w'*num_ints;	'u
.nf
typedef struct {
.sp .2
	Pint	num_ints;	/* number of Pints in list */
	Pint	*ints;	/* list of integers */
.sp .2
} Pint_list;
.fi
.sp .4
.SS Execution
\s-2SET INVISIBILITY FILTER\s+2 sets the workstation's
invisibility filter, which contains
an inclusion set and an exclusion set of names, both empty by default.
A primitive is invisible
if at least one name in the current name set is in the inclusion set
and no name in the current name set is in the exclusion set.  
If the workstation's invisibility filter inclusion set is empty,
then no primitives are invisible.  
.LP
If the current name set is empty, then subsequent primitives are not invisible.   
.\" They may not actually be VISIBLE, since they could be obscured or clipped,
.\" but they won't be invisible by reason of the INVISIBILITY filtering.
When traversal of a posted structure network starts, the current name set
is empty.  During traversal, the member names specified
by the \s-2ADD NAMES TO SET\s+2 element are added to the current name set 
by the union operation on the sets.  
\s-2REMOVE NAMES FROM SET\s+2 elements remove names from the current name set.  
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(in other words, the workstation category is neither 
\s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ADD NAMES TO SET (3P)"
.SM "REMOVE NAMES FROM SET (3P)"
.SM "INQUIRE INVISIBILITY FILTER (3P)"
.fi