INCREMENTAL SPATIAL SEARCH(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

void
pincrspasrch ( ref, dist, sp, ceil, norm, inv, len, st, error_ind, fp, tot_len )
Ppoint∗ref;search reference point
Pfloatdist;search distance
Pexecreflst∗sp;starting path list
Pintceil;search ceiling index
Pfilterlst∗norm;normal filter list
Pfilterlst∗inv;inverted filter list
Pintlen;length of application list
Pintst;starting position
Pint∗error_ind;OUT error indicator
Pexecreflst∗fp;OUT found path
Pint∗tot_len;OUT length of list in PHIGS

FORTRAN Syntax

SUBROUTINE piss ( SRPX, SRPY, SDIST, SPTHSZ, SPATH, SRCHCI, NFLN, NFLISX, NFLIS,
NFLESX, NFLES, IFLN, IFLISX, IFLIS, IFLESX, IFLES, IPTHSZ, ERRIND, FPTHSZ,
FPATH )
REALSRPX, SRPYsearch reference point (WC)
REALSDISTsearch distance
INTEGERSPTHSZnumber of elements in starting path
INTEGERSPATH(2, SPTHSZ)starting path
INTEGERSRCHCIsearch ceiling index
INTEGERNFLNnumber of normal filters
INTEGERNFLISX(NFLN)array of end indices of normal filter
inclusion sets
INTEGERNFLIS(∗)normal filter inclusion sets
INTEGERNFLESX(NFLN)array of end indices of normal filter
exclusion sets
INTEGERNFLES(∗)normal filter exclusion sets
INTEGERIFLNnumber of inverted filters
INTEGERIFLISX(IFLN)array of end indices of inverted filter
inclusion sets
INTEGERIFLIS(∗)inverted filter inclusion sets
INTEGERIFLESX(IFLN)array of end indices of inverted filter
exclusion sets
INTEGERIFLES(∗)inverted filter exclusion sets
INTEGERIPTHSZsize of found path array
INTEGERERRINDOUT error indicator
INTEGERFPTHSZOUT found path size
INTEGERFPATH(2, IPTHSZ)OUT found path

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

INCREMENTAL SPATIAL SEARCH 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 and y positions in the World Coordinate (WC) system. These positions locate the center of the (2∗dist × 2∗dist) search square. The z coordinate is assumed to be zero. The Ppoint structure is defined in phigs.h as:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
} Ppoint;

distA real value specifying the search distance.

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

typedef struct {
Pintnumber;/∗ number of execute references ∗/
Pexecref∗ers;/∗ list of execute references ∗/
} Pexecreflst;

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

Pexecref is defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintelem_num;/∗ element number ∗/
} Pexecref;

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 Pfilterlst structure containing a set of normal filter lists. Pfilterlst is defined below.

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

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

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 {
Pintlstincl_set;/∗ inclusion set ∗/
Pintlstexcl_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. Pintlst is defined in phigs.h as:

typedef struct {
Pintnumber;/∗ number of Pints in list ∗/
Pint∗integers;/∗ list of integers ∗/
} Pintlst;

lenThe length (maximum number) of the portion of the found path returned.

stThe starting position of the portion of the found path 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 Pexecreflst structure containing the found path. Pexecreflst is defined in phigs.h as:

typedef struct{
Pintnumber;/∗ number of execute references ∗/
Pexecref∗ers;/∗ list of execute references ∗/
} Pexecreflst;

The number component specifies the length of the structure path returned. The pointer ers is a pointer to a list of number long of Pexecref structures containing the structure identifier and element number of each execute reference structure element in the execute reference list.

Note: Application should allocated enough memory to allow len number of Pexecref structure to be returned.

If the length of the found path returned, which is determined by the st and the tot_len, is greater than the len, then none of the data that would be stored in the ers are returned, but 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.

FORTRAN Input Parameters

SRPXThe x coordinate in WC for the search reference point.

SRPYThe y coordinate in WC for the search reference point.

SDIST
The search distance.

SPTHSZ
The number of elements in the starting path.

SPATH
An array of integers containing the structure identifier and element position in the starting path.

SPATH(1,∗) = Structure Identifier
SPATH(2,∗) = Element Position

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

NFLNThe number of normal filters.

NFLISX
An array of integers containing the end indicies into the NFLIS array for each inclusion set in the normal filter.

NFLIS
An array of integers containing the names for the inclusion sets in the normal filter.

NFLESX
An array of integers containing the end indicies into the NFLES array for each exclusion set in the normal filter.

NFLES
An array of integers containing the names for the exclusion sets in the normal filter.

IFLNThe number of inverted filters.

IFLISX
An array of integers containing the end indicies into the IFLIS array for each inclusion set in the inverted filter.

IFLISAn array of integers containing the names for the inclusion sets in the inverted filter.

IFLESX
An array of integers containing the end indicies into the IFLES array for each exclusion set in the inverted filter.

IFLESAn array of integers containing the names for the exclusion sets in the inverted filter.

IPTHSZ
Size of the FPATH array in which the returned structure path data will be stored. If this value is smaller than the actual size of the structure path (FPTHSZ), no data will be returned in the FPATH array, but FPTHSZ will be set to indicate the array size required. If this function is called with an array size of zero, FPTHSZ is returned with the required array size. Error 2001 is returned if IPTHSZ is too small, but not if it is zero.

FORTRAN Output Parameters

ERRIND
The error number of any error detected by this function.

FPTHSZ
The number of structure path elements returned in FPATH.

FPATH
A 2 x IPTHSZ integer array containing the found path, where the (1,∗) components contain the structure identifiers, and the (2,∗) components contain the element sequence numbers.

FPATH(1,∗) = Structure Identifier
FPATH(2,∗) = Element Position

Execution

When INCREMENTAL SPATIAL SEARCH is called, the search begins at the element following the position specified by the starting path. 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 elements, the spatial extent is the enclosing rectangle calculated using the values of the geometric attributes (character height, character up vector, text path, and text alignment) arising from traversal together with the following values for the workstation dependent attributes: text font, 1; text precision, STROKE; character expansion factor, 1; and character spacing, 0. For ANNOTATION TEXT RELATIVE elements, the only proximity relationship used is closeness to the annotation reference point.

For NON-UNIFORM B-SPLINE CURVE and NON-UNIFORM B-SPLINE SURFACE, INCREMENTAL SPATIAL SEARCH uses the following values as the workstation dependent attributes: curve approximation type, PCURV_WS_DEP; curve approximation value, 1; surface approximation type, PSURF_WS_DEP; surface approximation value for u dimension, 1; surface approximation value for v dimension, 1; trimming curve approximation type, PCURV_WS_DEP; and trimming curve approximation value, 1.

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 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

Museum