SAMPLE LOCATOR 3(3P) — SUNPHIGS LIBRARY

NAME

SAMPLE LOCATOR 3 − sample the current measure of a locator device

SYNOPSIS

C Syntax

void
psampleloc3 ( ws, dev, locator )
Pintws;workstation identifier
Pintdev;locator device number
Ploc3∗locator;OUT locator data

FORTRAN Syntax

SUBROUTINE psmlc3 ( WKID, LCDNR, VIEWI, LPX, LPY, LPZ )
INTEGERWKIDworkstation identifier
INTEGERLCDNRlocator device number
INTEGERVIEWIOUT view index
REALLPX, LPY, LPZOUT locator position in WC

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use SAMPLE LOCATOR 3 to sample the current measure of the specified locator device without waiting for the device trigger to fire. The device must be in SAMPLE mode. See SET LOCATOR MODE and INITIALIZE LOCATOR 3 for more information.

C Input Parameters

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

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

locatorA pointer to a Ploc3 structure in which to store the LOCATOR measure. Ploc3 is defined in phigs.h as follows:

typedef struct {
Pintview_index;
Ppoint3position;
} Ploc3;

view index is the index of the view representation used to transform the NPC position to a WC position.

position is a Ppoint3 structure specifying the locator position in World Coordinates. Ppoint3 is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ 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.

VIEWI
The index of the view representation used to transform the NPC position to a WC position.

LPX, LPY, LPZ
The locator position in World Coordinates.

Execution

SAMPLE LOCATOR 3 samples the specified locator device. The device must be in SAMPLE mode. See SET LOCATOR MODE and INITIALIZE LOCATOR 3 for more information.

When a device is set to SAMPLE mode, a measure process is created for the device and the device is activated. When SAMPLE LOCATOR 3 is called, the current value of the measure process for the specified device is retrieved without waiting for the device’s trigger to fire.

A LOCATOR device measure consists of a position and a view index. Position is the World Coordinate (WC) point corresponding to the position on the workstation selected by the operator. The view index is the index of the view used to transform position from Device Coordinates (DC) to World Coordinates. See INITIALIZE LOCATOR 3 and SET VIEW TRANSFORMATION INPUT PRIORITY for a description of how this view representation is determined. The workstation transform is used to transform the Device Coordinate (DC) position to a NPC position.

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, SAMPLE LOCATOR, can be used if the value of the z coordinate is not needed.

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

252Ignoring function, the function requires the input device to be in SAMPLE Mode

Museum