INITIALIZE PICK(3P) — SUNPHIGS LIBRARY

NAME

INITIALIZE PICK − initialize a PICK input device using 2D data

SYNOPSIS

C Syntax

void
pinitpick ( ws, dev, status, init, pet, echo_area, record, order )
Pintws;workstation identifier
Pintdev;pick device number
Ppickstatusstatus;initial pick status
Ppickpath∗init;initial pick pointer
Pintpet;prompt and echo type
Plimit∗echo_area;echo area pointer
Ppickrec∗record;data record pointer
Ppathorderorder;pick path order

FORTRAN Syntax

SUBROUTINE pinpk ( WKID, PKDNR, ISTAT, IPPD, PP, PET, XMIN, XMAX, YMIN, YMAX,
LDR, DATREC, PPORDR )
INTEGERWKIDworkstation identifier
INTEGERPKDNRpick device number
INTEGERISTATinitial status (POK, PNPICK)
INTEGERIPPDdepth of initial pick path
INTEGERPP(3,IPPD)pick path
INTEGERPETprompt/echo type
REALXMIN,XMAX, YMIN, YMAX echo area in device coordinates
INTEGERLDRdimension of data record array
CHARACTER∗80DATREC(LDR) data record
INTEGERPPORDRpick path order (PPOTOP, PPOBOT)

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

INITIALIZE PICK sets the initialization parameters of a PICK device. This function stores these parameters in the workstation description table of the workstation associated with the specified device. The specified device must be in REQUEST mode when this function is called.

The pick filter of a PICK device controls which output primitives on the device’s workstation are pickable. By default no output primitives are pickable. See SET PICK FILTER for more information on the pick filter.

C Input Parameters

wsThe workstation identifier of the workstation associated with the device.

devThe device number of the PICK device to initialize. See the Available Devices section below for a description of the available devices.

statusThe PICK status of the initial measure. Ppickstatus is an enumerated type defined in phigs.h as follows:

typedef enum {
PP_OK,
PP_NOPICK
} Ppickstatus;

initA pointer to a Ppickpath structure containing the initial pick path, if any. This value is ignored if status is PP_NOPICK. Ppickpath is defined in phigs.h as:

typedef struct {
Pintdepth;/∗ pick path depth ∗/
Ppickpathel∗pick_path;/∗ pick path list ∗/
} Ppickpath;

The depth indicates the number of elements in the measure’s path.

The pick_path is the array of path elements defining the location of the picked primitive in the CSS. Ppickpathel is defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintpick_id;/∗ pick identifier ∗/
Pintel_num;/∗ element number ∗/
} Ppickpathel;

The struct_id, pick_id, and el_num are the structure identifier, pick id, and element number, respectively, of each element in the path.

petThe prompt/echo type desired. Those supported by each device are listed in the Available Devices section below.

echo_area
A pointer to a Plimit structure defining the x and y components of the echo volume, in Device Coordinates. The z component in the workstation state list is left unchanged. Plimit is defined in phigs.h as follows:

typedef struct {
Pfloatxmin;/∗ minimum x coordinate value ∗/
Pfloatxmax;/∗ maximum x coordinate value ∗/
Pfloatymin;/∗ minimum y coordinate value ∗/
Pfloatymax;/∗ maximum y coordinate value ∗/
} Plimit;

recordA pointer to a Ppickrec union containing the data record information. The contents of the data record for each device and prompt/echo type are described below in the Available Devices section.

The members of the data record union correspond to the prompt/echo type being used. As an example, the appropriate member of the Ppickrec union for prompt/echo type 1 is record->pickpet1_datarec.

For some prompt/echo types of some PICK devices the data record is not used. The record parameter, however, must still be passed.

orderThe pick path order of paths returned by REQUEST PICK, GET PICK, and SAMPLE PICK. Ppathorder is an enumerated type defined in phigs.h as follows:

typedef enum {
PTOP_FIRST,
PBOTTOM_FIRST
} Ppathorder;

If the order is TOP FIRST, then the structure specified in any pick path element is a parent of the structure specified in the subsequent pick path element. If the order is BOTTOM FIRST, then the structure specified in any pick path element is a child of the structure specified in the subsequent pick path element.

FORTRAN Input Parameters

WKIDThe workstation identifier of the workstation associated with the device.

PKDNR
The device number of the PICK device to initialize. See the Available Devices section below for a description of the available devices.

ISTATThe pick status of the initial measure. Valid values as defined in phigs77.h are:

POKOK
PNPICKNo Pick

IPPDThe number of elements in the measure’s path. This value is ignored if ISTAT is PNPICK.

PPAn array containing the measure’s pick path. This value is ignored if ISTAT is PNPICK. This is the 2D array of path elements defining the location of the picked primitive in the CSS. Each row of the array contains the structure identifier, pick id and element number, respectively, of each element in the path.

PETThe prompt/echo type desired. Those supported by each device are listed in the Available Devices section below.

XMIN, XMAX, YMIN, YMAX
The x and y components of the echo volume, in Device Coordinates. The z component in the workstation state list is left unchanged.

LDRThe dimension of the data record array.

DATREC
A packed data record, built by PACK DATA RECORD, containing the input data record information. The contents of the data record for each device and prompt/echo type are described below in the Available Devices section.

PPORDR
The pick path order of paths returned by REQUEST PICK, GET PICK, and SAMPLE PICK. Valid values as defined in phigs77.h are:

PPOTOPTop First
PPOBOTBottom First

If the order is Top First, then the structure specified in any pick path element is a parent of the structure specified in the subsequent pick path element. If the order is Bottom First, then the structure specified in any pick path element is a child of the structure specified in the subsequent pick path element.

Execution

INITIALIZE PICK sets the initialization parameters of a PICK device. This function stores these parameters in the workstation description table of the workstation associated with the specified device. The specified device must be in REQUEST mode when this function is called.

The parameters that are initialized by this function are the initial measure, prompt/echo type, echo volume, and input data record.

The initial measure is the logical input value the device will be set to whenever it is enabled. The device’s measure will retain this value until operator input changes it. A device is enabled when the appropriate REQUEST function is called, or when its input mode is set to SAMPLE or EVENT.

A PICK device measure consists of a status and a pick path. Status indicates whether or not an initial pick path is specified. Pick path describes the location of the picked primitive, if any, in the Central Structure Store (CSS).

The prompt/echo type determines the display characteristics of the device, i.e., how it will be presented to the operator and respond to his actions. Each device supports one or more prompt/echo type. Those supported by each device are listed in the device’s description in the Available Devices section below. All devices support prompt/echo type 1. Positive prompt/echo types are defined by the PHIGS Standard. Negative types are implementation dependent. Most SunPHIGS input devices support both positive and negative prompt/echo types.

The echo volume defines the region of the display surface in which to echo the device. It is specified in Device Coordinates (DC). Devices that use the echo volume will restrict their display to this region. Some of these devices will still recognize operator input outside the region even though they don’t display there. This function only specifies the x and y components of the echo volume. The existing z component in the workstation state list is left unchanged.

The input data record contains the prompt/echo type specific information that controls the device’s appearance and characteristics. Not all the data record contents are used by some devices. The device descriptions in the Available Devices section below list the data record contents that each device recognizes.

All the initialization parameters must be specified properly or this function will generate an error. The Errors section below lists the possible error conditions.

The default initialization parameters and the list of prompt/echo types supported by a PICK input device can be inquired with the function INQUIRE DEFAULT PICK DEVICE DATA. The current state of the device can be inquired with the function INQUIRE PICK DEVICE STATE.

AVAILABLE DEVICES

Device 1 - Cursor and Left Mouse Button Down Stroke

Device 2 - Cursor and Middle Mouse Button Down Stroke

Device 3 - Cursor and Right Mouse Button Down Stroke

Device 4 - Cursor and Left Mouse Button Up Stroke

Device 5 - Cursor and Middle Mouse Button Up Stroke

Device 6 - Cursor and Right Mouse Button Up Stroke

These devices are all associated with the mouse and cursor. Using device 1, 2, and 3, the operator picks an output primitive by positioning the cursor on or near the primitive and depressing the appropriate mouse button. Using device 4, 5, and 6, the operator moves the mouse around, holds the mouse still for about 0.20 second to allow SunPHIGS to search and echo any pickable primitives around the cursor position, and selects the output primitive by releasing the appropriate mouse button at the selected position. Echoing is accomplished according to the prompt echo type.

SunPHIGS searches the workstation’s list of posted structures for visible and pickable output primitives that intersect a 3D region around the cursor position. This region is called the pick aperture. The aperture is a Device Coordinate (DC) volume of fixed depth, and width and height specified by the application as a percentage of the DC dimensions.

If the workstation’s HLHSR mode is 0 (i.e., no HLHSR processing), then the search starts at the root of the posted structure network with highest priority and continues until the entire network has been traversed. The last pickable primitive traversed in this network, which is found to intersect the aperture, is the picked primitive. If no such primitive is found the search continues with the next highest priority structure network until a primitive is found or there are no more structure networks to search.

If the workstation’s HLHSR mode is 1 (i.e., z buffer hidden surface removal), then the workstation searches all the posted structure networks. For those pickable primitives identified for HLHSR processing, the primitive which intersects the pick aperture and is the nearest to the viewer is picked. For pickable primitives not identified for HLHSR or not processed by it, the last traversed primitive to intersect the aperture is picked. See SET HLHSR MODE and SET HLHSR IDENTIFIER for more information on HLHSR processing.

If no pickable primitive is found to intersect the aperture, the PICK device measure is set to NO PICK. The device’s pick filter determines which output primitives are pickable.

The echo volume is not used by this device.

Prompt/echo types supported: 1, 2, 3, -1, -2, -3, -4

In the following PET descriptions, blinking and highlighting mean alternating the colour of the primitives involved between their intrinsic colour and the highlight colour. Like a quick update method (see SET DISPLAY UPDATE STATE), these colour manipulations disregard structure priority. Therefore, after echoing an implicit regeneration may (depending on the display update state) occur to correct the display.

PET 1Highlight the picked primitive by blinking it twice. The highlight colour is the background colour.

The data record is not used for this PET.

PET 2Highlight all the primitives in the structure with the same pick identifier as the picked primitive. The primitives are blinked highlight count times and are left displayed in each colour for highlight duration seconds. Aperture size is specified as a fraction of DC and may be different for each axis, with the limitation that the z dimension is always the full depth of the output device, regardless of the setting.

If highlight_count is negative, the absolute value is used as the number of times to blink, and the primitives are left displayed in the highlight colour. A regeneration of the workstation will return them to their intrinsic colour.

C Data Record:

A Ppickpet0002 structure defined in phigs.h as:

typedef struct {
Pinthighlight_colour;
Pinthighlight_count;/∗ number of times to blink ∗/
Pfloathighlight_duration;/∗ seconds per half blink ∗/
Ppoint3aperture_size;/∗ percent of DC ∗/
} Ppickpet0002;

FORTRAN Data Record:

The arguments passed to PACK DATA RECORD for this prompt/echo type’s data record should be:

ILThe number of integers = 2.

IAContains two integer values:

IA(1)The pick highlight colour.

IA(2)The highlight count.

RLThe number of real values = 4.

RAAn array of reals in the following order:

RA(1)The highlight duration, in seconds.

RA(2)The x aperture size.

RA(3)The y aperture size.

RA(4)The z aperture size.

SLThe number of strings = 0.

PET 3Highlight the whole posted structure network containing the picked primitive.

The data record description is the same as for PET 2. The C structure is Ppickpet0003.

PET -1Highlight the picked primitive.

The data record description is the same as for PET 2. The C structure is Pupickpet0001.

PET -2Highlight the longest contiguous interval of primitives with the same pick identifier, and containing the picked primitive. EXECUTE STRUCTURE elements may be present in the interval, but descendents are not highlighted.

The data record description is the same as for PET 2. The C structure is Pupickpet0002.

PET -3Highlight the whole structure containing the picked primitive, including descendants.

The data record description is the same as for PET 2. The C structure is Pupickpet0003.

PET -4Highlight all primitives in the same structure as the picked primitive, but do not descend.

The data record description is the same as for PET 2. The C structure is Pupickpet0004.

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

060Ignoring function, specified workstation is not of category OUTIN

250Ignoring function, the specified device is not available on the specified workstation

251Ignoring function, the function requires the input device to be in REQUEST mode

254Ignoring function, invalid echo area/volume; XMIN ≥ XMAX, YMIN ≥ YMAX, or ZMIN > ZMAX

255Ignoring function, one of the echo area/volume boundary points is outside the range of the device

260Ignoring function, one of the fields within the input device data record is in error

253Warning, the specified prompt/echo type is not available on the specified workstation. Prompt/echo type one will be used in its place

261Ignoring function, initial value is invalid

Museum