\&
.sp 1
.ce 3
\s+1\fBChapter 8\fP\s-1

\s+1\fBName Sets\fP\s-1
.sp 2
.nr H1 8
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 8: Name Sets
.XE
.IN "name sets"
.LP
A name set is a PEX resource which maintains a set of identifiers
called names.  A name set allows conditional treatment of output primitives
during rendering, picking, and structure searching operations.
.LP
Search contexts and pick measures also have attributes that are name set
resource identifiers.
.LP
Renderer resources and PHIGS workstation resources each have a name set
attribute considered as the current name set. The contents of the current name
set cannot be directly modified or queried in the PHIGS workstation resource. 
The name set used in a renderer resource is set through the pipeline
context resource that provides the initial state for the renderer. There are
output commands that cause identifiers to be added to or removed from this name
set.  Thus, as a structure traversal or series of output commands is executed,
the contents of the current name set can fluctuate.
.LP
.IN "filters"
Special filters are built into renderer, search context, pick measure, and
PHIGS workstation resources.  These filters consist of a pair of name set
resource identifiers, one of which is considered as the "inclusion set" and the other
which is considered as the "exclusion set".  Both are provided
because sometimes it is easier to specify what passes the filter test,
while other times it is easier to specify what does not pass the filter test.
.LP
The filtering criteria is successfully met if, when an output
primitive command is executed, the inclusion name set contains at least
one name contained in the current name set, and exclusion name set does not
contain any names in the current name set.  If a name
is contained in both the inclusion set and the exclusion set, it is
considered to be only in the exclusion set.
.LP
Conditional operations that are supported with name sets include
highlighting, treating primitives as though they were invisible, and ignoring
certain primitives when searching through a structure network or performing
a picking operation.
.LP
The user can render the scene in different ways by modifying the
highlighting inclusion and exclusion sets and retraversing the structure
network.  If the highlighting inclusion and exclusion sets are empty when
the structure network is traversed, the scene is drawn as normal.
If the user calls
.PN PEXChangeNameSet
to add "antique" to
the highlighting inclusion set, all of the "antique" objects are 
highlighted the next time the structure network is traversed.  If the user 
adds "wooden" to the highlighting inclusion set, all "wooden" objects
and all "antique" objects are highlighted.  If "wooden" is added
to the highlighting exclusion set instead, all objects that are "antique"
but not "wooden" are highlighted.
.LP
The only attribute in a name set is a list of names.  For performance reasons,
the set of available names can be limited by an implementation.   (See
.PN PEXGetImpDepConstants .)
PEXlib includes functions to create, copy, free,
query, and modify name sets.
.bp
.XS
Function Descriptions
.XE
.SH
PEXChangeNameSet - Change Name Set
.XS
	PEXChangeNameSet
.XE
.IN "PEXChangeNameSet" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXChangeNameSet\^(\^Display *\fIdisplay\fP\^, PEXNameSet \fInameset\fP\^, int \fIaction\fP\^, unsigned long \fIcount\fP\^, PEXName *\fInames\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fInameset\fP 1i
The resource identifier of the name set.
.IP \fIaction\fP 1i
Type of change to be made
.Pn ( PEXNSAdd ,
.PN PEXNSRemove ,
.PN PEXNSReplace ).
.IP \fIcount\fP 1i
The number of names.
.IP \fInames\fP 1i
An array of names.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function modifies the specified name set resource.  The list of names
is added to the name set if the specified action is
.PN PEXNSAdd ,
removed from the name set if the specified action is
.PN PEXNSRemove ,
or used to replace the names currently in the name set if the specified action is
.PN PEXNSReplace .
If requested to remove a name that does not exist, it is silently ignored.
.RE
.SH
Data Structures
.ID
.Co
typedef XID             PEXNameSet;
typedef unsigned long   PEXName;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.IP \fIBadValue\fP 1i
The specified value for action parameter is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateNameSet ,
.PN PEXGetNameSet
.RE
.bp
.SH
PEXCopyNameSet - Copy Name Set
.XS
	PEXCopyNameSet
.XE
.IN "PEXCopyNameSet" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXCopyNameSet\^(\^Display *\fIdisplay\fP\^, PEXNameSet \fIsrc_nameset\fP\^, PEXNameSet \fIdst_nameset\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIsrc_nameset\fP 1i
The resource identifier of the source name set.
.IP \fIdst_nameset\fP 1i
The resource identifier of the destination name set.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function copies the contents of the source name set to the
destination name set.  Both must already exist as valid
name set resources.  All values already in the destination name set are
overwritten.
.RE
.SH
Data Structures
.ID
.Co
typedef XID             PEXNameSet;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateNameSet
.RE
.bp
.SH
PEXCreateNameSet - Create Name Set
.XS
	PEXCreateNameSet
.XE
.IN "PEXCreateNameSet" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXNameSet PEXCreateNameSet\^(\^Display *\fIdisplay\fP\^)
.FN
.RE
.SH
Argument
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.RE
.SH
Returns
.RS
.LP
The resource identifier of the newly-created name set.
.RE
.SH
Description
.RS
.LP
This function creates a name set resource and returns the resource
identifier of the created name set.  The returned identifier is
used to refer to the created name set.
.RE
.SH
Data Structures
.ID
.Co
typedef XID             PEXNameSet;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate the resource.
.RE
.SH
See Also
.RS
.LP
.PN PEXFreeNameSet
.RE
.bp
.SH
PEXFreeNameSet - Free Name Set
.XS
	PEXFreeNameSet
.XE
.IN "PEXFreeNameSet" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeNameSet\^(\^Display *\fIdisplay\fP\^, PEXNameSet \fInameset\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fInameset\fP 1i
The resource identifier of the name set.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deletes the association between the name set resource
identifier and the name set.  The name set
is freed when no other resource references it.
.RE
.SH
Errors
.RS
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateNameSet
.RE
.bp
.SH
PEXGetNameSet - Get Name Set
.XS
	PEXGetNameSet
.XE
.IN "PEXGetNameSet" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXGetNameSet\^(\^Display *\fIdisplay\fP\^, PEXNameSet \fInameset\fP\^, unsigned long *\fIcount_return\fP\^, PEXName **\fInames_return\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fInameset\fP 1i
The resource identifier of the name set to be queried.
.IP \fIcount_return\fP 1i
Returns the number of names.
.IP \fInames_return\fP 1i
Returns an array of names.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful; non-zero otherwise.
.RE
.SH
Description
.RS
.LP
This function returns the names in the specified name set.
.LP
PEXlib allocates memory for the return value.
.PN XFree
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef XID             PEXNameSet;
typedef unsigned long   PEXName;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateNameSet ,
.PN PEXChangeNameSet
.RE
.bp
