REQUEST LOCATOR 3(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

void
preqloc3 ( ws, dev, loc )
Pintws;workstation identifier
Pintdev;locator device number
Pqloc3∗loc;OUT requested locator data

FORTRAN Syntax

SUBROUTINE prqlc3 ( WKID, LCDNR, STAT, VIEWI, PX, PY, PZ )
INTEGERWKIDworkstation identifier
INTEGERLCDNRlocator device number
INTEGERSTATOUT status (PNONE, POK)
INTEGERVIEWIOUT view index
REALPX, PY, PZOUT 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.

locA pointer to a Pqloc3 data structure containing the status of the request and, if available, the locator data. Pqloc is defined in phigs.h as follows:

typedef struct {
Pistatusstatus;/∗ status of request ∗/
Ploc3loc;/∗ locator data ∗/
} Pqloc3;

Pistatus is defined in phigs.h as follows:

typedef enum {
PSTAT_OK,
PSTAT_NONE
} Pistatus;

Ploc3 is defined in phigs.h as follows:

typedef struct {
Pint view_index; /∗ view index ∗/
Ppoint3 position; /∗ point ∗/
} Ploc3;

Ppoint3 is defined in phigs.h as follows:

typedef struct {
    Pfloat    x;    /∗ x coordinate ∗/
    Pfloat    y;    /∗ y coordinate ∗/
    Pfloat    z;    /∗ z coordinate ∗/
} Ppoint3;

FORTRAN Input Parameters

WKIDThe workstation identifier of the workstation associated with the device.

LCDNR
The device number of the LOCATOR device. See the Available Devices section of INITIALIZE LOCATOR 3 for a description of the available devices.

STATThe request status. Valid values as defined in phigs77.h are:

• PNONE(BREAK)
• POK(OK)

VIEWI
The view index used to map the locator to world coordinates. This value is defined only if the status returned is OK.

PX,
The world coordinate locator position. This value is defined only if the status returned is OK.

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 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 NONE is returned and the locator data is undefined. If a status of 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 index and world coordinate position. The view index specifies the view representation from the workstation’s view table that was used to map the locator position from Normalized Projections Coordinates to World Coordinates. The position is the position of the locator in World Coordinates. 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