NAME

SAMPLE LOCATOR − sample the current measure of a locator device

SYNOPSIS

C Syntax

void
psample_loc ( ws, dev, view_ind, loc_pos )
Pintws;workstation identifier
Pintdev;locator device number
Pint∗view_ind;OUT view index
Ppoint∗loc_pos;OUT locator data

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use SAMPLE LOCATOR to sample the current measure of the specified locator device without waiting for operator input. The device must be in SAMPLE mode.  See SET LOCATOR MODE and INITIALIZE LOCATOR 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 for a description of the available devices. 

C Output Parameters

view_ind
The index of the view representation used to transform the Normalized Projection Coordinate (NPC) position to a World Coordinates (WC) position. 

loc_pos
Ppoint is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
} Ppoint;

Execution

SAMPLE LOCATOR samples the specified locator device. The device must be in SAMPLE mode.  See SET LOCATOR MODE and INITIALIZE LOCATOR 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 is called, the current value of the measure process for the specified device is retrieved without waiting for further input from the operator. 

A LOCATOR device measure consists of a position and a view index.  The position is the 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 WC.  See INITIALIZE LOCATOR and SET VIEW TRANSFORMATION INPUT PRIORITY for a description of how this view representation is determined.  The workstation transform is used to transform the 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 3D version of this function, SAMPLE LOCATOR 3, can be used if the value of the z coordinate is 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

SEE ALSO

INITIALIZE LOCATOR (3P)
SET LOCATOR MODE (3P)
REQUEST LOCATOR 3 (3P)
GET LOCATOR (3P)
INQUIRE LOCATOR DEVICE STATE (3P)
SET VIEW TRANSFORMATION INPUT PRIORITY (3P)
SAMPLE LOCATOR 3 (3P)

September 02, 1992