ELEMENT SEARCH(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

ELEMENT SEARCH − search for next matching element in specified structure

SYNOPSIS

C Syntax

void
pelem_search ( struct_id, start_el, dir, incl, excl, error_ind, status, found_el )
Pintstruct_id;structure identifier
Pintstart_el;starting element pointer
Psearch_dirdir;search direction
Pelem_type_list∗incl; element incl. list
Pelem_type_list∗excl; element excl. list
Pint∗error_ind;OUT error indicator
Psearch_status∗status; OUT search status
Pint∗found_el;OUT found element pointer

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

ELEMENT SEARCH searches the specified structure for the next element matching the search criteria. The search starts at the specified element (or the limit of the structure) and proceeds in the direction specified. The search terminates if an element is found, or if the opposite limit of the structure is reached.

The search criteria is based on element types. An element satisfies the criteria if its element type is in the inclusion set, and not in the exclusion set.

C Input Parameters

struct_id
Identifier of the structure to search.

start_el
Position in the specified structure of the first element tested against the search criteria.

dirSearch direction. Psearch_dir is an enumerated type defined in phigs.h to have the following values:

PDIR_BACKWARD
PDIR_FORWARD

inclA pointer to a Pelem_type_list structure containing the list of element types in the inclusion set.

The Pelem_type_list structure and its sub-types are defined in phigs.h as:

typedef struct {
Pint num_elem_types;/∗ number of element types ∗/
Pelem_type∗elem_types;/∗ list of element types ∗/
} Pelem_type_list;

The Pelem_type enumeration lists all the supported element types. It is enumerated in phigs.h as follows:

typedef enum {
    PELEM_ALL,
    PELEM_NIL,
    PELEM_POLYLINE3,
    PELEM_POLYLINE,
    PELEM_POLYMARKER3,
    PELEM_POLYMARKER,
    PELEM_TEXT3,
    PELEM_TEXT,
    PELEM_ANNO_TEXT_REL3,
    PELEM_ANNO_TEXT_REL,
    PELEM_FILL_AREA3,
    PELEM_FILL_AREA,
    PELEM_FILL_AREA_SET3,
    PELEM_FILL_AREA_SET,
    PELEM_CELL_ARRAY3,
    PELEM_CELL_ARRAY,
    PELEM_GDP3,
    PELEM_GDP,
    PELEM_LINE_IND,
    PELEM_MARKER_IND,
    PELEM_TEXT_IND,
    PELEM_INT_IND,
    PELEM_EDGE_IND,
    PELEM_LINETYPE,
    PELEM_LINEWIDTH,
    PELEM_LINE_COLR_IND,
    PELEM_MARKER_TYPE,
    PELEM_MARKER_SIZE,
    PELEM_MARKER_COLR_IND,
    PELEM_TEXT_FONT,
    PELEM_TEXT_PREC,
    PELEM_CHAR_EXPAN,
    PELEM_CHAR_SPACE,
    PELEM_TEXT_COLR_IND,
    PELEM_CHAR_HT,
    PELEM_CHAR_UP_VEC,
    PELEM_TEXT_PATH,
    PELEM_TEXT_ALIGN,
    PELEM_ANNO_CHAR_HT,
    PELEM_ANNO_CHAR_UP_VEC,
    PELEM_ANNO_PATH,
    PELEM_ANNO_ALIGN,
    PELEM_ANNO_STYLE,
    PELEM_INT_STYLE,
    PELEM_INT_STYLE_IND,
    PELEM_INT_COLR_IND,
    PELEM_EDGE_FLAG,
    PELEM_EDGETYPE,
    PELEM_EDGEWIDTH,
    PELEM_EDGE_COLR_IND,
    PELEM_PAT_SIZE,
    PELEM_PAT_REF_POINT_VECS,
    PELEM_PAT_REF_POINT,
    PELEM_ADD_NAMES_SET,
    PELEM_REMOVE_NAMES_SET,
    PELEM_INDIV_ASF,
    PELEM_HLHSR_ID,
    PELEM_LOCAL_MODEL_TRAN3,
    PELEM_LOCAL_MODEL_TRAN,
    PELEM_GLOBAL_MODEL_TRAN3,
    PELEM_GLOBAL_MODEL_TRAN,
    PELEM_MODEL_CLIP_VOL3,
    PELEM_MODEL_CLIP_VOL,
    PELEM_MODEL_CLIP_IND,
    PELEM_RESTORE_MODEL_CLIP_VOL,
    PELEM_VIEW_IND,
    PELEM_EXEC_STRUCT,
    PELEM_LABEL,
    PELEM_APPL_DATA,
    PELEM_GSE,
    PELEM_PICK_ID,
    PELEM_POLYLINE_SET3_DATA,
    PELEM_FILL_AREA_SET3_DATA,
    PELEM_TRI_STRIP3_DATA,
    PELEM_QUAD_MESH3_DATA,
    PELEM_SET_OF_FILL_AREA_SET3_DATA,
    PELEM_NUNI_BSP_CURVE,
    PELEM_NUNI_BSP_SURF,
    PELEM_CELL_ARRAY3_PLUS,
    PELEM_TEXT_COLR,
    PELEM_MARKER_COLR,
    PELEM_EDGE_COLR,
    PELEM_LINE_COLR,
    PELEM_CURVE_APPROX_CRIT,
    PELEM_LINE_SHAD_METH,
    PELEM_INT_COLR,
    PELEM_BACK_INT_COLR,
    PELEM_BACK_INT_STYLE,
    PELEM_BACK_INT_STYLE_IND,
    PELEM_REFL_PROPS,
    PELEM_BACK_REFL_PROPS,
    PELEM_INT_SHAD_METH,
    PELEM_BACK_INT_SHAD_METH,
    PELEM_INT_REFL_EQN,
    PELEM_BACK_INT_REFL_EQN,
    PELEM_SURF_APPROX_CRIT,
    PELEM_FACE_DISTING_MODE,
    PELEM_FACE_CULL_MODE,
    PELEM_LIGHT_SRC_STATE,
    PELEM_DCUE_IND,
    PEL_COLR_MAPPING_IND,
    PELEM_RENDERING_COLR_MODEL,
    PELEM_NUM_EL_TYPES
} Pelem_type;

exclA pointer to a Pelem_type_list structure containing the list of element types in the exclusion set. Pelem_type_list is defined above. Excluding all element types will result in failure to find matching elements.

C Output Parameters

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

statusA pointer to the location to store the search status. Psearch_status is an enumerated type defined in phigs.h to have the following values:

PSEARCH_STATUS_FAILURE
PSEARCH_STATUS_SUCCESS

found_el
A pointer to the location to store the position of the element found. If status is PSEARCH_STATUS_FAILURE, found_el is undefined.

Execution

If the start element position is less than zero, the search begins at element position zero, whose element type is considered NIL. If the start element position is greater than the number of elements in the structure, the search begins at the last element in the open structure. Otherwise, the search starts at the specified element.

If this element satisfies the search criteria, the element position is returned along with a status indicator of success. Otherwise the next element in the direction specified is considered. The search will continue until either an element fulfills the search criteria or the far end of the structure is reached. If the search is unsuccessful, then a status indicator of failure is returned.

The current element pointer and currently open structure (if any) are not used, and are unaffected.

ERRORS

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

201Ignoring function, the specified structure does not exist

Museum