INITIALIZE PICK 3(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

INITIALIZE PICK 3 − initialize a PICK input device using 3D data.

SYNOPSIS

C Syntax

void
pinit_pick3 ( ws, dev, istat, init, pet, echo_volume, record, order )
Pintws;workstation identifier
Pintdev;pick device number
Pin_statusistat;initial pick status
Ppick_path∗init;initial pick pointer
Pintpet;prompt and echo type
Plimit3∗echo_volume;echo volume pointer
Ppick_data3∗record;data record pointer
Ppath_orderorder;pick path order

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INITIALIZE PICK 3 to set the initialization parameters of a PICK device. This function stores these parameters in the workstation state list 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.

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

typedef enum {
PIN_STATUS_NONE,
PIN_STATUS_OK,
PIN_STATUS_NO_IN
} Pin_status;

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

typedef struct {
Pintdepth;/∗ pick path_list depth ∗/
Ppick_path_elem∗path_list;/∗ pick path ∗/
} Ppick_path;

The depth indicates the number of elements in the path.

path_list is the array of path elements defining the location of the primitive in the CSS. Ppick_path_elem is defined in phigs.h as:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintpick_id;/∗ hierarchical pick identifier ∗/
Pintelem_pos;/∗ element sequence number ∗/
} Ppick_path_elem;

The struct_id, pick_id, and elem_pos 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_volume
A pointer to a Plimit3 structure spedifying the echo volume, in Device Coordinates. Plimit3 is defined in phigs.h as follows:

typedef struct {
Pfloatx_min;/∗ minimum x coordinate value ∗/
Pfloatx_max;/∗ maximum x coordinate value ∗/
Pfloaty_min;/∗ minimum y coordinate value ∗/
Pfloaty_max;/∗ maximum y coordinate value ∗/
Pfloatz_min;/∗ minimum z coordinate value ∗/
Pfloatz_max;/∗ maximum z coordinate value ∗/
} Plimit3;

recordA pointer to a Ppick_data3 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 Ppick_data3 union for prompt/echo type 1 is pet_r1.

For some prompt/echo types the data record is not used; however, the record parameter must still be specified.

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

typedef enum {
PORDER_TOP_FIRST,
PORDER_BOTTOM_FIRST
} Ppath_order;

If the order is TOP FIRST, 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, the structure specified in any pick path element is a child of the structure specified in the subsequent pick path element.

Execution

INITIALIZE PICK 3 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 path, prompt/echo type, echo volume, and input data record.

The initial path is the logical input value the device will take on whenever it is enabled. The device’s measure retains 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. The pick path, if any, describes the location of a picked primitive in the Central Structure Store (CSS).

The prompt/echo type determines how the device will be presented to the operator and respond to his actions. Each device supports one or more prompt/echo types. 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.

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 may restrict their display to this region. Some of these devices may still recognize operator input outside the region even though they don’t display there.

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 3. The current state of the device can be inquired with the function INQUIRE PICK DEVICE STATE 3.

AVAILABLE DEVICES

Device 1 - Pointer device

This device is associated with the X pointer device. The operator picks an output primitive by selecting a displayed primitive with the pointer.

When a pick is attempted by the operator, PHIGS searches the workstation’s list of posted structures for visible and pickable output primitives that intersect a 3D region around the pointer. This region is called the pick aperture. 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 in this network that intersects 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 no pickable primitive is found to intersect the aperture, the PICK device measure status is set to PIN_STATUS_NONE.

This device does not use the echo volume.

Only prompt/echo type 1 is supported.

Picking is only supported for X servers that support the full PEX extension.

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

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

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

261Ignoring function, initial value is invalid

Museum