Input

Java 3D API Specification

Java 3D provides access to keyboards and mice using Java's standard API for keyboard and mouse support. Additionally, it provides access to a variety of continuous input devices such as six-degree-of-freedom (6DOF) trackers and joysticks.
Continuous input devices such as 6DOF trackers and joysticks have well defined continuous inputs. Trackers produce a position and orientation that Java 3D stores internally as a transform matrix. Joysticks produce two continuous values in the range (-1.0, 1.0) that Java 3D stores internally as a transform matrix with an identity rotation (no rotation) and one of the Joystick values as the x translation and the other the y translation component.
Unfortunately, continuous input devices do not have the same level of consistency when it comes to their associated switches or buttons. Still the number of buttons or switches attached to a particular sensing element remains constant across all sensing elements associated with a single device.

9.1 InputDevice Object

The InputDevice object defines an input device that generates SensorReads.

Methods
public Enumeration allInputDevices()
This method creates an enumerator that produces all available devices.
public int getButtonCount()
This method retrieves the InputDevice's button count.
public String getDeviceFilename()
This method retrieves the input device's deviceFilename.
public int getSensorCount()
This method retrieves the InputDevice's sensorCount.
public abstract boolean initialize()
This method initializes the device.
public abstract void boresight()
This method is used to boresight the device (establish its reference frame relative to the "TrackerBase" reference frame.
public abstract void pollAndProcessInput()
This method polls and processes the device's input.
public abstract void processStreamInput()
This method processes the devices streaming input.
public Enumeration allInputDevices()
This method creates an enumerator that produces all available devices.

9.2 Sensors

The Java 3D API provides no concept of a tracking device or joystick. Rather, it abstracts away issues of devices and device models, defining instead the concept of a sensor. A sensor consists of a time-stamped sequence of input values and the state of the buttons or switches at the time that Java 3D sampled the value. A Sensor also contains a hotspot offset specified in that sensor's local coordinate system. If not specified, the hotspot is (0.0, 0.0, 0.0).
Since a typical hardware environment contains multiple sensing elements, Java 3D maintains an array of sensors. Users can access a sensor directly from their Java code or they can assign a sensor to one of Java 3D's predefined 6DOF entities such as the UserHead.

9.2.1 Using and Assigning Sensors

Using a sensor is as easy as accessing an object. The application developer writes Java code to extract the associated sensor value from the array of sensors. The developer can then directly apply that value to an element in a scene graph or process the sensor values in whatever way necessary.
An application developer can also assign or change which sensor drives one of the predefined 6DOF entities in Java 3D. These include UserHead, DominantHand, and NondominantHand. Java 3D immediately starts using the specified sensor to drive the 6DOF entity. Application developers should use this facility carefully. It is quite easy to get the effect of a WristCam-very disconcerting as well.

9.2.2 Behind the (Sensor) Scenes

Java 3D does not provide raw tracker or joystick-generated data in a sensor. At a minimum, Java 3D normalizes the raw data using the registration and calibration parameters either provided by or provided for the end user. It additionally may filter and process the data to remove noise and improve latency. The application programmer can suppress this latter effect on a sensor-by-sensor basis.
Unfortunately, tracker or sensor hardware may not always be available or be operational. Thus, Java 3D provides both an available and an enable flag on a per-sensor basis.

9.2.3 The Sensor Object

Java 3D stores its sensor array in the PhysicalEnvironment object. Each Sensor in the array consists of a fixed number of SensorReads. Also associated with each SensorRead is its timestamp and the state of that sensor's buttons.

Constants

The Sensor object specifies the following constants.
public static final int PREDICT_NONE
public static final int PREDICT_NEXT_FRAME_TIME
These flags define the Sensor's predictor type. The first flag defines no prediction. The second flag specifies to generate the value to correspond with the next frame time.
public static final int NO_PREDICTOR
public static final int HEAD_PREDICTOR
public static final int HAND_PREDICTOR
These flags define the Sensor's predictor policy. The first flag specifies to use no prediction policy. The second flag specifies to assume that the sensor is predicting head position or orientation. The third flag specifies to assume that the sensor is predicting hand position or orientation.

Constructors

The Sensor object specifies the following constructors.
public Sensor()
Constructs a new Sensor object consisting of a set of readings and a hot spot at (0.0, 0.0, 0.0) in its own coordinate system.
public Sensor(double x, double y, double z)
public Sensor(Point3d hotspot)
Constructs a new Sensor object consisting of a set of readings and an offset defining the sensor's hot spot in its own coordinate system.

Methods
public int getSensorReadCount()
public void setSensorReadCount(int count)
These methods set and retrieve the sensor's read count. This variable is a calibration parameter. It should be set once, before initializing Java 3D.
public void getHotspot(Point3d hotspot)
public void setHotspot(Point3d hotspot)
These methods set and retrieve the sensor's hotspot offset. The hotspot is specified in the Sensor's local coordinate system.
public void lastRead(Transform3D read)
public void lastRead(Transform3D read, int k)
These methods extract the most recent sensor reading and the kth most recent sensor reading from the sensor object. In both cases, the methods copy the sensor value into the specified argument.
public void getRead(Transform3D read)
public void getRead(Transform3D read, long deltaT)
The first method computes the sensor reading consistent with the prediction policy and copies that value into the read matrix. The second method computes the sensor reading consistent as of time deltaT in the future and copies that value into the read matrix.
public long lastTime()
public long lastTime(int k)
These methods return the time associated with the most-recent sensor reading and with the kth most-recent sensor reading, respectively.
public boolean[] lastButtons()
public boolean[] lastButtons(int k)
These methods return the state of the buttons associated with the most-recent sensor reading and the kth most-recent sensor reading, respectively.
public void setPredictor(int predictor)
public int getPredictor()
These methods set and retrieve the Sensor's predictor type. The predictor type is one of: PREDICT_NONE, PREDICT_NEXT_FRAME_TIME.
public void setPredictionPolicy(int policy)
public int getPredictionPolicy()
These methods set and retrieve the Sensor's predictor policy. The predictor policy is one of: NO_PREDICTOR, HEAD_PREDICTOR, or HAND_PREDICTOR.

9.2.4 The SensorRead Object

A SensorRead object encapsulates all the information associated with a single reading of a sensor.

Constants

The SensorRead object specifies the following flag.
public static final int MAXIMUM_SENSOR_BUTTON_COUNT
The maximum number of sensor-attached buttons tracked on a per-sensor basis.

Constructors

The SensorRead object specifies the following constructor.
public SensorRead()
public SensorRead(int buttonCount)
Creates a new SensorRead object.

Methods
public void set(Transform3D t1)
public void get(Transform3D result)
These methods set and retrieve the read's transform3D. They allow a device to store a new rotation and orientation value into the SensorRead object and a consumer of that value to access it.
public void setTime(long time)
public long getTime()
These methods set and retrieve the read's timestamp. They allow a device to store a new timestamp value into the SensorRead object and a consumer of that value to access it.
public void setButtons(boolean values[])
public long getButtons(boolean values[])
These methods set and retrieve the read's button values. They allow a device to store a new array of button values into the SensorRead object and a consumer of those values to access it.
public int getButtonCount()
This methods returns the number of button values associated with the SensorRead object.

9.3 Tracker Plug-ins

Java 3D will provide the ability to define and use new trackers. Each new device should conform to the InputDevice Interface object.

Constants

The InputDevice object specifies the following constants.
public static final int POLLED
public static final int STREAMING
Developers use these flags define an InputDevice's operational mode. The first flag specifies that the device works in a polled fashion. The second flag specifies that the device operates in a streaming fashion.

Methods
public int initialize()
This methods will initialize the hardware device.
public void setNominalPositionandOrientatin()
This methods established the device's current position and orientation as device nominal.
public void pollAndProcessInput()
This methods polls the device, process the input, and adds/updates appropriate SensorRead objects within the appropriate Sensor objects.
public void processStreamInput()
This methods process the devices streaming input and adds/updates appropriate SensorRead objects within the appropriate Sensor objects.
public void setProcessingMode(int mode)
public int getProcessingMode()
These methods set and retrieve the devices Processing mode, one of POLLED or STREAMING. A polled device only responds to a query, a streaming device produces continuous updates.

Java 3D API Specification

Copyright © 1997, Sun Microsystems, Inc. All rights reserved.