NAME

INCREMENTAL SPATIAL SEARCH 3 − search the structure network for the next occurrence of a graphical output structure element meeting the specified search criteria

SYNOPSIS

C Syntax

void
pincr_spa_search3 ( ref, dist, sp, mclip_flag, ceil, norm, inv, len, st, error_ind, fp, tot_len )
Ppoint3∗ref;search reference point
Pfloatdist;search distance
Pelem_ref_list∗sp; starting path list
Pclip_indmclip_flag;model clip flag
Pintceil;search ceiling index
Pfilter_list∗norm;normal filter list
Pfilter_list∗inv;inverted filter list
Pintlen;length of application list
Pintst;starting position
Pint∗error_ind;OUT error indicator
Pelem_ref_list∗fp; OUT found path
Pint∗tot_len;OUT length of list in PHIGS

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

INCREMENTAL SPATIAL SEARCH 3 searches a structure network for the next occurrence of a graphical output structure element that satisfies the specified search criteria. 

C Input Parameters

refA pointer to a Ppoint structure that specifies the x, y, and z coordinates, in World Coordinates (WC), of the search reference point.  The Ppoint3 structure is defined in phigs.h as:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

distA real value specifying the maximum distance that a selected primitive may be from the search reference point. 

spA pointer to a Pelem_ref_list structure that contains the starting search path.  Pelem_ref_list is defined in phigs.h as:

typedef struct {
Pintnum_elem_refs;/∗ number of element references ∗/
Pelem_ref∗elem_refs;/∗ list of element references ∗/
} Pelem_ref_list;

elem_refs is a pointer to a list of num_elem_refs long of Pelem_ref structures containing the structure identifier and element number of each execute reference structure element in the execute reference list. 

Pelem_ref is defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintelem_pos; /∗ element number ∗/
} Pelem_ref;

mclip_flag
Indicates whether model clipping should be performed during the incremental spatial search.  Pclip_ind is defined in phigs.h as follows:

typedef enum {
PIND_NO_CLIP, Do not perform model clipping
PIND_CLIP Perform model clipping
} Pclip_ind;

ceilThe search ceiling index defines a position in the starting path list.  The structure identifier at this position of the list defines a ceiling for the search. 

normA pointer to a Pfilter_list structure containing a set of normal filter lists.  Pfilter_list is defined below. 

invA pointer to a Pfilter_list structure containing a set of inverted filter lists.  Pfilter_list is defined in phigs.h as:

typedef struct {
Pintnum_filters;/∗ number of filters ∗/
Pfilter∗filters;/∗ list of filters ∗/
} Pfilter_list;

filters is a pointer to an array (num_filters) of Pfilter structures, that contains an inclusion set and an exclusion set of names. 

Pfilter is defined in phigs.h as:

typedef struct {
Pint_listincl_set;/∗ inclusion set ∗/
Pint_listexcl_set;/∗ exclusion set ∗/
} Pfilter;

The incl_set contains a set of names for the inclusion set.  The excl_set contains a set of names for the exclusion set.  Pint_list is defined in phigs.h as:

typedef struct {
Pintnum_ints; /∗ number of Pints in list ∗/
Pint∗ints;/∗ list of integers ∗/
} Pint_list;

lenThe maximum length of the portion of the found path to be returned. 

stThe starting position of the portion of the found path to be returned. If st is set to zero, then the complete found path is returned. 

C Output Parameters

error_ind
A pointer to the location to store the error number of any error detected by this function.

fpA pointer to a Pelem_ref_list structure containing the found path.  Pelem_ref_list is defined in phigs.h as:

typedef struct{
Pintnum_elem_refs;/∗ number of element references ∗/
Pelem_ref∗elem_refs;/∗ list of element references ∗/
} Pelem_ref_list;

num_elem_refs specifies the length of the structure path returned. 

elem_refs is a pointer to an array of Pelem_ref structures num_elem_refs long.  All but the last of these structures contain the structure identifier and element number of each execute reference structure element in the path to the selected output primitive. 

The application must allocate memory for len elements in the list of elem_refs.  If the length of the found path is greater than the len parameter, then no found path is returned.  In this case, tot_len will be set to indicate the total length of the found path. 

tot_len
A pointer to an integer which returns the total length of the found path.

Execution

When INCREMENTAL SPATIAL SEARCH 3 is called, a search begins at the element following the position specified by the starting path and continues until an ouput primitive meeting the search criteria is found or the search ceiling is reached.  The search is conceptually a traversal with structure elements being examined sequentially and matched against the search criteria.  Element position zero is permitted so that the search may start at the first element of the structure. 

Search filters are applied to control which output primitives structure elements in the structures searched are considered.  The filters are organized into two lists, the normal and the inverted filter lists which operate in the opposite senses.  A structure element is said to be accepted if it is declared eligible when NAME SET is applied to the filters.  To be accepted by a filter, NAME SET must have at least one name in common with the inclusion set and no names in common with the exclusion set.  For a structure element to be considered a candidate for the spatial search it must be accepted by each of the filters in the normal filter list and rejected by each of the filters in the inverted filter list.  If the normal filter list is empty, then all structure elements satisfy the acceptance criteria for normal filters.  If the inverted filter list is empty, all structure elements satisfy the rejection criteria for inverted filters.  Graphical output structure elements which satisfy the search filters are checked for proximity to the reference point. 

For TEXT structure elements, the only proximity relationship used is closeness to the text origin.  For ANNOTATION TEXT RELATIVE structure elements, the only proximity relationship used is closeness to the annotation reference point. 

The search will continue until either a graphical output structure element matches the search criteria or the end of the structure identified by the search ceiling is reached.  If a search is successful, the complete search path is returned as a found path.  An unsuccessful search returns a null found path. 

The function is incremental in that, having found a match, the search may be continued by invoking INCREMENTAL SPATIAL SEARCH 3 again with the found path as the next starting path.  This allows all elements matching the search criteria to be found for a given portion of a structure network. 

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

203Ignoring function, specified starting path not found in CSS

204Ignoring function, specified search ceiling index out of range

SEE ALSO

ADD NAMES TO SET (3P)
REMOVE NAMES FROM SET (3P)
INCREMENTAL SPATIAL SEARCH (3P)

September 02, 1992