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

NAME

INITIALIZE LOCATOR 3 − initialize a LOCATOR input device using 3D data

SYNOPSIS

C Syntax

void
pinit_loc3 ( ws, dev, init_view_ind, init_loc_pos, pet, echo_volume, record )
Pintws;workstation identifier
Pintdev;locator device number
Pintinit_view_ind;initial view indicator
Ppoint3∗init_loc_pos;initial locator position
Pintpet;prompt and echo type
Plimit3∗echo_volume;echo volume pointer
Ploc_data3∗record;data record pointer

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INITIALIZE LOCATOR 3 to set the initialization parameters of a LOCATOR device. This function stores these parameters in the workstation state list of the workstation associated with the device. The specified device must be in REQUEST mode when this function is called.

C Input Parameters

wsThe workstation identifier of the workstation associated with the device.

devThe device number of the LOCATOR device to initialize. See the AVAILABLE DEVICES section below for a description of the available devices.

init_view_ind
The index of the view representation in the workstation’s view table to use to map the specified initial position from World Coordinates (WC) to Normalized Projection Coordinates (NPC).

init_loc_pos
A Ppoint3 structure specifying the initial 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;

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 specifying the echo volume, in Device Coordinates (DC). 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 Ploc_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 Ploc_data3 union for prompt/echo type 1 is pet_r1.

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

Execution

INITIALIZE LOCATOR 3 sets the initialization parameters of a LOCATOR 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 parameters that are initialized by this function are initial value, prompt/echo type, echo volume, and input data record.

The initial value is the logical input value the device will be set to 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 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 representation used to transform the locator position from Normalized Projection Coordinates (NPC) to WC. This view representation is determined by selecting the highest priority representation that contains the locator position within its NPC limits. See SET VIEW TRANSFORMATION INPUT PRIORITY for more information. The workstation transform is used to transform the operator-selected position from Device Coordinates (DC) to NPC.

The initial locator position is transformed to DC by applying the view-orientation and view-mapping transforms of the specified view representation, and then applying the workstation transformation. If the view index is invalid, an error is generated.

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 DC. Devices that use the echo volume may restrict their display to this region. Some of these devices will 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 LOCATOR input device can be inquired with the function INQUIRE DEFAULT LOCATOR DEVICE DATA 3. The current state of the device can be inquired with the function INQUIRE LOCATOR DEVICE STATE 3.

AVAILABLE DEVICES

Devices 1 to 3 - Pointer devices

These devices are associated with the X pointer device, usually the mouse and cursor. Devices 1, 2, and 3 are triggered by the left, middle, and right mouse buttons respectively. The locator position in the LOCATOR device’s measure is the WC position corresponding to the pointer position in X pointer events. PHIGS computes the WC position from the two-dimensional pointer position by transforming the pointer position to a 2D NPC point, determining the highest priority view containing that point, setting the Z coordinate of the NPC point to the lower Z limit of that view, and transforming the NPC point to world coordinates.

Not all prompt/echo types use the initial locator position. Only those that need an additional point to the current pointer position use the initial position. The pointer is not moved to the initial position when the device is enabled.

This device does not use the echo volume.

Prompt/echo types supported:

PET 1Display the default cursor at the current locator position.

The data record is not used for this PET.

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

114Ignoring function, the view index value is less than zero

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.

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. Prompt/echo type one will be used in its place

261Ignoring function, initial value is invalid

Museum