REQUEST LOCATOR 3(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

REQUEST LOCATOR 3 − request an operator interaction with a locator device

SYNOPSIS

C Syntax

void
preq_loc3 ( ws, dev, in_status, view_ind, loc_pos )
Pintws;workstation identifier
Pintdev;locator device number
Pin_status∗in_status;OUT input status
Pint∗view_ind;OUT view index
Ppoint3∗loc_pos;OUT locator position

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use REQUEST LOCATOR 3 to request an operator interaction with a specified locator device. The device must be in request mode. See SET LOCATOR MODE and INITIALIZE LOCATOR 3 for more information. See the Available Devices section of INITIALIZE LOCATOR 3 for a description of the available locator devices.

The request suspends PHIGS until the specified device is triggered, or the operator performs a BREAK. A BREAK is performed by typing the CONTROL and D keys simultaneously (^D).

C Input Parameters

wsWorkstation identifier. An integer specifying the workstation with which the requested locator device is associated.

devThe device number of the requested locator device. See the Available Devices section of INITIALIZE LOCATOR 3 for a description of the available locator devices.

C Output Parameters

in_status
A pointer to the location to store the status of the request. Pin_status is defined in phigs.h as follows:

typedef enum {
PIN_STATUS_NONE,
PIN_STATUS_OK,
PIN_STATUS_NO_IN
} Pin_status;

view_ind
A pointer to the location to store the view representation used to map from Device Coordinates (DC) to World Coordinates (WC).

loc_pos
A pointer to a Ppoint3 structure in which to the system stores the locator position coordinates. Ppoint3 is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

Execution

REQUEST LOCATOR 3 requests a logical input value from the specified locator device. The specified device must be in request mode. See SET LOCATOR MODE for more information.

REQUEST LOCATOR 3 creates a measure process for the specified device and suspends PHIGS until the device is triggered or the operator issues a BREAK. A BREAK is generated by the operator by depressing the Control and D keys simultaneously (^D).

If a BREAK occurs, a status of PIN_STATUS_NO_IN is returned, and the locator data is undefined. If a status of PIN_STATUS_OK is returned, the locator data is available. In either case, the measure process is then terminated and PHIGS processing resumes.

A locator measure consists of a view_ind and WC loc_pos. The view_ind specifies the view representation from the workstation’s view table that was used to map the locator position from Normalized Projections Coordinates (NPC) to WC. The loc_pos is the position of the locator in WC. Note: The 2D and 3D locator measure processes are the same except that the 2D process discards the z coordinate. The 2D version of this function, REQUEST LOCATOR, can be used if the value of the z coordinate is not needed.

See INITIALIZE LOCATOR 3 for a description of the available locator devices.

ERRORS

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

054Ignoring function, the specified workstation is not open

061Ignoring function, specified workstation is neither of category INPUT nor 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

Museum