\& .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