ELEMENT SEARCH(3P) — SUNPHIGS LIBRARY

NAME

ELEMENT SEARCH − search for next matching element in specified structure

SYNOPSIS

C Syntax

void
pelemsrch ( struct_id, start_el, dir, incl, excl, error_ind, status, found_el )
Pintstruct_id;structure identifier
Pintstart_el;starting element pointer
Psrchdirdir;search direction
Psrcheltypelst∗incl;element incl. list
Psrcheltypelst∗excl;element excl. list
Pint∗error_ind;OUT error indicator
Psrchstatus∗status;OUT search status
Pint∗found_el;OUT found element pointer

FORTRAN Syntax

SUBROUTINE pels ( STRID, STRTEP, SRCDIR, EISN, EIS, EESN, EES, ERRIND, STATUS,
FNDEP )
INTEGERSTRIDstructure identifier
INTEGERSTRTEPstart element pointer
INTEGERSRCDIRsearch direction (PBWD, PFWD)
INTEGEREISNnumber of elements in element inclusion set
INTEGEREIS(EISN)element inclusion set
INTEGEREESNnumber of elements in element exclusion set
INTEGEREES(EESN)element exclusion set
INTEGERERRINDOUT error indicator
INTEGERSTATUSOUT status indicator (PFAIL, PSUCC)
INTEGERFNDEPOUT 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
Sequence number in the specified structure of the first element tested against the search criteria.

dirSearch direction. Valid values defined in phigs.h are PBACKWARD and PFORWARD.

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

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

typedef struct {
Pint number;/∗ number of elements ∗/
Psrcheltype∗elems;/∗ list of elements ∗/
} Psrcheltypelst;

The Psrcheltype enumeration differs from the Peltype enumeration. The special value PSEL_ALL indicates that all element types are to be included, so an exhaustive list of all element types need not be generated. The exclusion list could then be used to exclude certain element types. Psrcheltype enum includes the following supported elements:

    PSEL_ALL,
    PSEL_NIL,
    PSEL_POLYLINE3,
    PSEL_POLYLINE,
    PSEL_POLYMARKER3,
    PSEL_POLYMARKER,
    PSEL_TEXT3,
    PSEL_TEXT,
    PSEL_ANNOTATION_TEXT_RELATIVE3,
    PSEL_ANNOTATION_TEXT_RELATIVE,
    PSEL_FILL_AREA3,
    PSEL_FILL_AREA,
    PSEL_FILL_AREA_SET3,
    PSEL_FILL_AREA_SET,
    PSEL_CELL_ARRAY3,
    PSEL_CELL_ARRAY,
    PSEL_GDP3,
    PSEL_GDP,
    PSEL_POLYLINE_INDEX,
    PSEL_POLYMARKER_INDEX,
    PSEL_TEXT_INDEX,
    PSEL_INTERIOR_INDEX,
    PSEL_EDGE_INDEX,
    PSEL_LINETYPE,
    PSEL_LINEWIDTH_SCALE_FACTOR,
    PSEL_POLYLINE_COLOUR_INDEX,
    PSEL_MARKER_TYPE,
    PSEL_MARKER_SIZE_SCALE_FACTOR,
    PSEL_MARKER_COLOUR_INDEX,
    PSEL_TEXT_FONT,
    PSEL_TEXT_PRECISION,
    PSEL_CHARACTER_EXPANSION_FACTOR,
    PSEL_CHARACTER_SPACING,
    PSEL_TEXT_COLOUR_INDEX,
    PSEL_CHARACTER_HEIGHT,
    PSEL_CHARACTER_UP_VECTOR,
    PSEL_TEXT_PATH,
    PSEL_TEXT_ALIGNMENT,
    PSEL_ANNOTATION_TEXT_CHARACTER_HEIGHT,
    PSEL_ANNOTATION_TEXT_CHARACTER_UP_VECTOR,
    PSEL_ANNOTATION_TEXT_PATH,
    PSEL_ANNOTATION_TEXT_ALIGNMENT,
    PSEL_ANNOTATION_STYLE,
    PSEL_INTERIOR_STYLE,
    PSEL_INTERIOR_STYLE_INDEX,
    PSEL_INTERIOR_COLOUR_INDEX,
    PSEL_EDGE_FLAG,
    PSEL_EDGETYPE,
    PSEL_EDGEWIDTH_SCALE_FACTOR,
    PSEL_EDGE_COLOUR_INDEX,
    PSEL_PATTERN_SIZE,
    PSEL_PATTERN_REFERENCE_POINT_AND_VECTORS,
    PSEL_PATTERN_REFERENCE_POINT,
    PSEL_ADD_NAMES_TO_SET,
    PSEL_REMOVE_NAMES_FROM_SET,
    PSEL_INDIVIDUAL_ASF,
    PSEL_HLHSR_IDENTIFIER,
    PSEL_LOCAL_MODELLING_TRANSFORMATION3,
    PSEL_LOCAL_MODELLING_TRANSFORMATION,
    PSEL_GLOBAL_MODELLING_TRANSFORMATION3,
    PSEL_GLOBAL_MODELLING_TRANSFORMATION,
    PSEL_MODELLING_CLIPPING_VOLUME3,
    PSEL_MODELLING_CLIPPING_VOLUME,
    PSEL_MODELLING_CLIPPING_INDICATOR,
    PSEL_RESTORE_MODELLING_CLIPPING_VOLUME,
    PSEL_VIEW_INDEX,
    PSEL_EXECUTE_STRUCTURE,
    PSEL_LABEL,
    PSEL_APPLICATION_DATA,
    PSEL_GSE,
    PSEL_PICK_ID,
    PSEL_POLYLINE_SET3_DATA,†
    PSEL_FILL_AREA3_DATA,†
    PSEL_FILL_AREA_SET3_DATA,†
    PSEL_TRIANGLE_STRIP3_DATA,†
    PSEL_QUADRILATERAL_MESH3_DATA,†
    PSEL_POLYHEDRON3_DATA,†
    PSEL_NON_UNIFORM_B_SPLINE_CURVE,†
    PSEL_NON_UNIFORM_B_SPLINE_SURFACE,†
    PSEL_EXTENDED_CELL_ARRAY_3,†
    PSEL_TEXT_COLOUR,†
    PSEL_POLYMARKER_COLOUR,†
    PSEL_EDGE_COLOUR,†
    PSEL_POLYLINE_COLOUR,†
    PSEL_CURVE_APPROXIMATION_CRITERIA,†
    PSEL_POLYLINE_SHADING_METHOD,†
    PSEL_INTERIOR_COLOUR,†
    PSEL_BACK_INTERIOR_COLOUR,†
    PSEL_BACK_INTERIOR_STYLE,†
    PSEL_BACK_INTERIOR_STYLE_INDEX,†
    PSEL_AREA_PROPERTIES,†
    PSEL_BACK_AREA_PROPERTIES,†
    PSEL_INTERIOR_SHADING_METHOD,†
    PSEL_BACK_INTERIOR_SHADING_METHOD,†
    PSEL_INTERIOR_REFLECTANCE_EQUATION,†
    PSEL_BACK_INTERIOR_REFLECTANCE_EQUATION,†
    PSEL_SURFACE_APPROXIMATION_CRITERIA,†
    PSEL_TRIM_CURVE_APPROXIMATION_CRITERIA,†
    PSEL_FACE_DISTINGUISHING_MODE,†
    PSEL_FACE_CULLING_MODE,†
    PSEL_LIGHT_SOURCE_STATE,†
    PSEL_DEPTH_CUE_INDEX†
    PSEL_COLOUR_MAPPING_INDEX†
    PSEL_RENDERING_COLOUR_MODEL†

† This is a SunPHIGS Extension based on PHIGS+ and is not part of the PHIGS standard.

exclA pointer to a Psrcheltypelst structure containing the list of element types in the exclusion set. Psrcheltypelst 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. Valid values defined in phigs.h are PFAILURE and PSUCCESS.

found_el
A pointer to the location to store the sequence number of the element found. If status is PFAILURE, found_el is undefined.

FORTRAN Input Parameters

STRID
Identifier of the structure to search.

STRTEP
Sequence number in the specified structure of the first element tested against the search criteria.

SRCDIR
Search direction. Valid values defined in phigs77.h are PBWD (backward) and PFWD (forward).

EISNNumber of element types in the inclusion set.

EIS(EISN)
Array of element types in the inclusion set. The special value PEALL indicates that all element types are to be included, so an exhaustive list of all element types need not be generated. The exclusion list could then be used to exclude certain element types. The mapping from the FORTRAN constants in phigs77.h to the actual element type names is given below for supported elements:

PEALLInclude all elements
PENILNIL
PEPL3POLYLINE 3
PEPLPOLYLINE
PEPM3POLYMARKER 3
PEPMPOLYMARKER
PETX3TEXT 3
PETXTEXT
PEATR3ANNOTATION TEXT RELATIVE 3
PEATRANNOTATION TEXT RELATIVE
PEFA3FILL AREA 3
PEFAFILL AREA
PEFAS3FILL AREA SET 3
PEFASFILL AREA SET
PECA3CELL ARRAY 3
PECACELL ARRAY
PEGDP3GDP 3
PEGDPGDP
PEPLIPOLYLINE INDEX
PEPMIPOLYMARKER INDEX
PETXITEXT INDEX
PEIIINTERIOR INDEX
PEEDIEDGE INDEX
PELNLINETYPE
PELWSCLINEWIDTH SCALE FACTOR
PEPLCIPOLYLINE COLOUR INDEX
PEMKMARKER TYPE
PEMKSCMARKER SIZE SCALE FACTOR
PEPMCIMARKER COLOUR INDEX
PETXFNTEXT FONT
PETXPRTEXT PRECISION
PECHXPCHARACTER EXPANSION FACTOR
PECHSPCHARACTER SPACING
PETXCITEXT COLOUR INDEX
PECHHCHARACTER HEIGHT
PECHUPCHARACTER UP VECTOR
PETXPTEXT PATH
PETXALTEXT ALIGNMENT
PEATCHANNOTATION TEXT CHARACTER HEIGHT
PEATCUANNOTATION TEXT CHARACTER UP VECTOR
PEATPANNOTATION TEXT PATH
PEATALANNOTATION TEXT ALIGNMENT
PEANSTANNOTATION STYLE
PEISINTERIOR STYLE
PEISIINTERIOR STYLE INDEX
PEICIINTERIOR COLOUR INDEX
PEEDFGEDGE FLAG
PEEDTEDGETYPE
PEEWSCEDGEWIDTH SCALE FACTOR
PEEDCIEDGE COLOUR INDEX
PEPAPATTERN SIZE
PEPRPVPATTERN REFERENCE POINT AND VECTORS
PEPARFPATTERN REFERENCE POINT
PEADSADD NAMES TO SET
PERESREMOVE NAMES FROM SET
PEIASFINDIVIDUAL ASF
PEHRIDHLHSR IDENTIFIER
PELMT3LOCAL MODELLING TRANSFORMATION 3
PELMTLOCAL MODELLING TRANSFORMATION
PEGMT3GLOBAL MODELLING TRANSFORMATION 3
PEGMTGLOBAL MODELLING TRANSFORMATION
PEMCV3MODELLING CLIPPING VOLUME 3
PEMCVMODELLING CLIPPING VOLUME
PEMCLIMODELLING CLIPPING INDICATOR
PERMCLRESTORE MODELLING CLIPPING VOLUME
PEVWIVIEW INDEX
PEEXSTEXECUTE STRUCTURE
PELBLABEL
PEAPAPPLICATION DATA
PEGSEGSE
PEPKIDPICK ID
PEPSD3POLYLINE SET 3 WITH DATA†
PEFAD3FILL AREA 3 WITH DATA†
PEFSD3FILL AREA SET 3 WITH DATA†
PETRSDTRIANGLE STRIP 3 WITH DATA†
PEQMD3QUADRILATERAL MESH 3 WITH DATA†
PEPHD3POLYHEDRON 3 WITH DATA†
PENBSCNON-UNIFORM B-SPLINE CURVE†
PENBSSNON-UNIFORM B-SPLINE SURFACE†
PEECAEXTENDED CELL ARRAY 3†
PETXCTEXT COLOUR†
PEPMCPOLYMARKER COLOUR†
PEEDCEDGE COLOUR†
PEPLCPOLYLINE COLOUR†
PECACCURVE APPROXIMATION CRITERIA†
PEPLSMPOLYLINE SHADING METHOD†
PEICINTERIOR COLOUR†
PEBICBACK INTERIOR COLOUR†
PEBISBACK INTERIOR STYLE†
PEBISIBACK INTERIOR STYLE INDEX†
PEAPRAREA PROPERTIES†
PEBAPRBACK AREA PROPERTIES†
PEISMINTERIOR SHADING METHOD†
PEBISMBACK INTERIOR SHADING METHOD†
PEIREINTERIOR REFLECTANCE EQUATION†
PEBIREBACK INTERIOR REFLECTANCE EQUATION†
PESACSURFACE APPROXIMATION CRITERIA†
PETCACTRIMMING CURVE APPROXIMATION CRITERIA†
PEFDMFACE DISTINGUISHING MODE†
PEFCMFACE CULLING MODE†
PELSSLIGHT SOURCE STATE†
PEDCINDEPTH CUE INDEX†
PECMICOLOUR MAPPING INDEX†
PERCMRENDERING COLOUR MODEL†

† This is a SunPHIGS Extension based on PHIGS+ and is not part of the PHIGS standard.

EESNNumber of element types in the exclusion set.

EES(EESN)
Array of element types in the exclusion set. Valid element type constants are in phigs77.h. The mapping from the FORTRAN constants to the actual element type names is given above. Excluding all element types will result in failure to find matching elements.

FORTRAN Output Parameters

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

STATUS
The search status indicator. Valid values defined in phigs77.h are PFAIL (failure) and PSUCC (success).

FNDEP
The sequence number of the element found. If status is failure, FNDEP is undefined.

Execution

If the start element postion is less than zero, the search begins at element position zero, whose element type is considered NIL. If the start element postion is greater than the number of elements in the structure, the search begins at element position following the last element, whose element type is considered NIL. 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. If the far end of the structure is reached, a NIL element is compared to the search criteria. If it fails, 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