\&
.sp 1
.ce 3
\s+1\fBChapter 9\fP\s-1
\s+1\fBSpatial Searches\fP\s-1
.sp 2
.nr H1 9
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 9: Spatial Searches
.XE
.LP
The functions described in this chapter allow for spatial searches of
structure networks. The portion of the structure network to be searched
is specified, and a set of filters much like the invisibility and
highlight filters are specified to limit the set of eligible primitives.
A search distance is also specified. The first output primitive that
satisfies the filter criteria and is within the search distance is returned.
.NH 2
Search Context
.XS
\*(SN Search Contexts
.XE
.LP
A search context is a PEX resource that contains all the search criteria
to be used when spatially searching a structure network. Two of the
attributes that specify search criteria contain name set resource identifiers.
If name sets are created, bound to a search context, then freed, the
contents of the name sets will remain, since they are still referenced by the
search context. However, if the search context is queried, the value
.PN PEXAlreadyFreed
will be returned for any such freed name sets, since they no longer have
valid resource identifiers by which they can be referenced.
.LP
A search context resource contains the following attributes:
.ID
Search position
Search distance
Search ceiling
Model clip flag
Start path
Normal list
Inverted list
.DE
.LP
The search position
attribute specifies the search reference position in world coordinates.
.LP
The search distance
attribute specifies a distance from the search reference position in
world coordinates.
The distance specifies a search aperture. Whether the aperture is considered
to be a sphere or a cube is implementation-dependent.
If the search distance is less than or equal to zero, a primitive
must intersect the search position to be considered within the
search aperture.
.LP
The search ceiling
attribute defines the ceiling of the search operation.
The search ceiling is an index into the list of element references
contained in the search start path.
Index one refers to the first path element in the list.
Searching stops when the end of the structure specified by
the search ceiling is reached.
If the ceiling is one, the search effectively operates without
a ceiling and terminates at the end of the first structure in the start path.
.LP
The model clip flag specifies whether modeling clipping must be performed
during the search operations. If
.PN True ,
modeling clipping is performed using the modeling clipping attributes as
they are encountered during the search traversal. If
.PN False ,
no model clipping is performed and model clipping attributes encountered
during the traversal are effectively ignored.
.LP
The start path attribute
defines the structure network path used as the starting point for the search.
The search traversal begins at the element following the one
indicated by the start path.
.LP
The normal list is a
list of name set resource identifier pairs. Each pair of name sets is considered
to be a filter to be used in the search traversal. A primitive's name
set attribute must have at least one name in common with the inclusion
name set of each filter, and must have no names in common with the
exclusion name set of each filter, to be eligible for the search.
.LP
The inverted list is a
list of name set resource identifier pairs. Each pair of name sets is considered
to be a filter that is inverted and used in the search traversal. A
primitive's name set attribute must have no names in common with the
inclusion name set of each inverted filter, or must have at least one name
in common with the exclusion name set of each inverted filter, to be
eligible for the search.
.LP
The
.PN PEXSearchNetwork
function is used to perform a search operation
once all of the search criteria attributes have been established.
To search, the structure network specified is conceptually traversed,
starting at the element following the element specified by the
start path.
Each output primitive is transformed to world coordinates and
compared against the search aperture to determine proximity.
For text and annotation text primitives, only the transformed origin of the
text string is used to determine proximity. If
.IN "text" "spatial searches"
.IN "annotation text" "spatial searches"
the transformed primitive's geometry places it within the search aperture,
its name set attribute is checked against the normal list and against the
inverted list to determine eligibility.
.LP
The search is successful if an output primitive is found which satisfies
the search filter criteria and is withing the search aperture. The path
to the first such primitive found is returned, and the start path
attribute of the search context is set to the found path. This allows
the next search operation on the same search context to continue from just
after the found primitive.
.LP
If no such primitive is found before the end of the structure indicated by the
search ceiling is reached, the search is unsuccessful, NULL is returned
as the found path, and the start path attribute is not changed.
.LP
.bp
.XS
Function Descriptions
.XE
.SH
PEXChangeSearchContext - Change Search Context
.XS
PEXChangeSearchContext
.XE
.IN "PEXChangeSearchContext" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXChangeSearchContext\^(\^Display *\fIdisplay\fP\^, PEXSearchContext \fIcontext\fP\^, unsigned long \fIvalue_mask\fP\^, PEXSCAttributes *\fIvalues\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIcontext\fP 1i
The resource identifier of the search context.
.IP \fIvalue_mask\fP 1i
A mask indicating the search context attributes to be changed.
.IP \fIvalues\fP 1i
A pointer to new values for the specified search context attributes.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function modifies the attributes of the specified search context resource.
The value mask indicates which values are specified.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXSCPosition
.PN PEXSCDistance
.PN PEXSCCeiling
.PN PEXSCModelClipFlag
.PN PEXSCStartPath
.PN PEXSCNormalList
.PN PEXSCInvertedList
.DE
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXSearchContext;
.sp
typedef struct {
PEXCoord position;
float distance;
unsigned short ceiling;
Bool model_clip_flag;
PEXStructurePath start_path;
PEXListOfNameSetPair normal;
PEXListOfNameSetPair inverted;
} PEXSCAttributes;
.sp
typedef struct {
float x;
float y;
float z;
} PEXCoord;
.sp
typedef struct {
unsigned long count; /* number of elements */
PEXElementRef *elements;
} PEXStructurePath;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.sp
typedef XID PEXStructure;
.sp
typedef struct {
unsigned short count; /* number of pairs */
PEXNameSetPair *pairs;
} PEXListOfNameSetPair;
.sp
typedef struct {
PEXNameSet inclusion;
PEXNameSet exclusion;
} PEXNameSetPair;
.sp
typedef XID PEXNameSet;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.IP \fIBadPEXPath\fP 1i
The specified path is invalid.
.IP \fIBadPEXSearchContext\fP 1i
The specified search context resource identifier is invalid.
.IP \fIBadValue\fP 1i
A specified value is out of range, or an invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateSearchContext ,
.PN PEXGetSearchContext
.RE
.bp
.SH
PEXCopySearchContext - Copy Search Context
.XS
PEXCopySearchContext
.XE
.IN "PEXCopySearchContext" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXCopySearchContext\^(\^Display *\fIdisplay\fP\^, unsigned long \fIvalue_mask\fP\^, PEXSearchContext \fIsrc_context\fP\^, PEXSearchContext \fIdst_context\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIvalue_mask\fP 1i
A mask specifying which attributes are to be copied.
.IP \fIsrc_context\fP 1i
The resource identifier of the source search context.
.IP \fIdst_context\fP 1i
The resource identifier of the destination search context.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function copies attributes from the source search context
to the destination search context resource. Both must
already exist as valid search context resources.
Attributes indicated by the value mask are copied and the
remainder of the attributes are left unchanged.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXSCPosition
.PN PEXSCDistance
.PN PEXSCCeiling
.PN PEXSCModelClipFlag
.PN PEXSCStartPath
.PN PEXSCNormalList
.PN PEXSCInvertedList
.DE
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXSearchContext;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXSearchContext\fP 1i
The specified search context resource identifier is invalid.
.IP \fIBadValue\fP 1i
An invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateSearchContext
.RE
.bp
.SH
PEXCreateSearchContext - Create Search Context
.XS
PEXCreateSearchContext
.XE
.IN "PEXCreateSearchContext" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXSearchContext PEXCreateSearchContext\^(\^Display *\fIdisplay\fP\^, unsigned long \fIvalue_mask\fP\^, PEXSCAttributes *\fIvalues\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIvalue_mask\fP 1i
A mask indicating the attributes specified.
.IP \fIvalues\fP 1i
A pointer to values used to override default values in the new search context resource.
.RE
.SH
Returns
.RS
.LP
The resource identifier of the newly-created search context resource.
.RE
.SH
Description
.RS
.LP
This function creates a search context and returns the resource
identifier of the created search context resource.
The value mask indicates which values are specified to override the default
values.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXSCPosition
.PN PEXSCDistance
.PN PEXSCCeiling
.PN PEXSCModelClipFlag
.PN PEXSCStartPath
.PN PEXSCNormalList
.PN PEXSCInvertedList
.DE
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXSearchContext;
.sp
typedef struct {
PEXCoord position;
float distance;
unsigned short ceiling;
Bool model_clip_flag;
PEXStructurePath start_path;
PEXListOfNameSetPair normal;
PEXListOfNameSetPair inverted;
} PEXSCAttributes;
.sp
typedef struct {
float x;
float y;
float z;
} PEXCoord;
.sp
typedef struct {
unsigned long count; /* number of elements */
PEXElementRef *elements;
} PEXStructurePath;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.sp
typedef XID PEXStructure;
.sp
typedef struct {
unsigned short count; /* number of pairs */
PEXNameSetPair *pairs;
} PEXListOfNameSetPair;
.sp
typedef struct {
PEXNameSet inclusion;
PEXNameSet exclusion;
} PEXNameSetPair;
.sp
typedef XID PEXNameSet;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadAlloc\fP 1i
The server failed to allocate the resource.
.IP \fIBadPEXNameSet\fP 1i
The specified name set resource identifier is invalid.
.IP \fIBadPEXPath\fP 1i
The specified path is invalid.
.IP \fIBadValue\fP 1i
A specified value is out of range, or an invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXFreeSearchContext
.RE
.bp
.SH
PEXFreeSCAttributes - Free Storage Returned by PEXGetSearchContext
.XS
PEXFreeSCAttributes
.XE
.IN "PEXFreeSCAttributes" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeSCAttributes\^(\^PEXSCAttributes *\fIvalues\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIvalues\fP 1i
A pointer to the search context attribute values.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deallocates memory returned by
.PN PEXGetSearchContext .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXGetSearchContext
.RE
.bp
.SH
PEXFreeSearchContext - Free Search Context
.XS
PEXFreeSearchContext
.XE
.IN "PEXFreeSearchContext" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFreeSearchContext\^(\^Display *\fIdisplay\fP\^, PEXSearchContext \fIcontext\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIcontext\fP 1i
The resource identifier of the search context.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function deletes the search context resource and frees
memory associated with it.
.RE
.SH
Errors
.RS
.IP \fIBadPEXSearchContext\fP 1i
The specified search context resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateSearchContext
.RE
.bp
.SH
PEXGetSearchContext - Get Search Context Attributes
.XS
PEXGetSearchContext
.XE
.IN "PEXGetSearchContext" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXSCAttributes *PEXGetSearchContext\^(\^Display *\fIdisplay\fP\^, PEXSearchContext \fIcontext\fP\^, unsigned long \fIvalue_mask\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIcontext\fP 1i
The resource identifier of the search context to be queried.
.IP \fIvalue_mask\fP 1i
A mask indicating which attributes to return.
.RE
.SH
Returns
.RS
.LP
A pointer to the requested attribute values; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns the requested attribute values of the specified search
context resource. The
value mask indicates which attributes are to be returned.
The value mask is constructed by or'ing together the following constants:
.ID
.PN PEXSCPosition
.PN PEXSCDistance
.PN PEXSCCeiling
.PN PEXSCModelClipFlag
.PN PEXSCStartPath
.PN PEXSCNormalList
.PN PEXSCInvertedList
.DE
.LP
PEXlib allocates memory for the returned search context attribute values.
.PN PEXFreeSCAttributes
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXSearchContext;
.sp
typedef struct {
PEXCoord position;
float distance;
unsigned short ceiling;
Bool model_clip_flag;
PEXStructurePath start_path;
PEXListOfNameSetPair normal;
PEXListOfNameSetPair inverted;
} PEXSCAttributes;
.sp
typedef struct {
float x;
float y;
float z;
} PEXCoord;
.sp
typedef struct {
unsigned long count; /* number of elements */
PEXElementRef *elements;
} PEXStructurePath;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.sp
typedef XID PEXStructure;
.sp
typedef struct {
unsigned short count; /* number of pairs */
PEXNameSetPair *pairs;
} PEXListOfNameSetPair;
.sp
typedef struct {
PEXNameSet inclusion;
PEXNameSet exclusion;
} PEXNameSetPair;
.sp
typedef XID PEXNameSet;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXSearchContext\fP 1i
The specified search context resource identifier is invalid.
.IP \fIBadValue\fP 1i
An invalid bit is set in the value mask.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateSearchContext ,
.PN PEXChangeSearchContext ,
.PN PEXFreeSCAttributes
.RE
.bp
.SH
PEXSearchNetwork - Search Network
.XS
PEXSearchNetwork
.XE
.IN "PEXSearchNetwork" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXSearchNetwork\^(\^Display *\fIdisplay\fP\^, PEXSearchContext \fIcontext\fP\^, PEXStructurePath **\fIpath_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 \fIcontext\fP 1i
The resource identifier of the search context.
.IP \fIpath_return\fP 1i
Returns a pointer to a structure network path identifying the first primitive found.
.RE
.SH
Returns
.RS
.LP
Zero if unsuccessful; non-zero otherwise.
.RE
.SH
Description
.RS
.LP
This function searches a structure network according to the specified search
criteria. The path to the first primitive
found that satisfies the search criteria is returned.
If no primitive is found that satisfies the criteria, a null pointer is
returned.
.LP
After the search has been completed, the start path attribute of
the specified search context will be set to the path returned,
if a primitive was found.
.LP
PEXlib allocates memory for the returned structure path.
.PN PEXFreeStructurePaths
should be called to deallocate the memory.
.RE
.SH
Data Structures
.ID
.Co
typedef XID PEXSearchContext;
.sp
typedef struct {
unsigned long count; /* number of elements */
PEXElementRef *elements;
} PEXStructurePath;
.sp
typedef struct {
PEXStructure structure;
unsigned long offset;
} PEXElementRef;
.sp
typedef XID PEXStructure;
.ft P
.DE
.SH
Errors
.RS
.IP \fIBadPEXPath\fP 1i
The specified path is invalid.
.IP \fIBadPEXSearchContext\fP 1i
The specified search context resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXCreateSearchContext ,
.PN PEXChangeSearchContext ,
.PN PEXFreeStructurePaths
.RE
.bp