Contents Previous Next

Java 3D API Specification


C H A P T E R10

Input Devices and Picking




JAVA 3D provides access to keyboards and mice using the standard Java API for keyboard and mouse support. Additionally, Java 3D provides access to a variety of continuous-input devices such as six-degrees-of-freedom (6DOF) trackers and joysticks.

Continuous-input devices like 6DOF trackers and joysticks have well defined continuous inputs. Trackers produce a position and orientation that Java 3D stores internally as a transformation matrix. Joysticks produce two continuous values in the range [-1.0, 1.0] that Java 3D stores internally as a transformation matrix with an identity rotation (no rotation) and one of the joystick values as the X translation and the other as 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.

10.1 InputDevice Interface

The InputDevice interface specifies an abstract input device that a developer can use in implementing a device driver for a particular device. All implementations of an InputDevice interface must implement all of its methods. Java 3D's input device scheduler uses these methods to interact with specific devices and incorporate their input. In addition to the generic methods that all InputDevices must provide, implementations of an InputDevice will contain whatever device-specific information and methods are necessary to maintain that device's proper functioning.

All input devices consist of a number of Sensor objects that have a direct one-to-one relationship with that device's physical detectors. Sensor objects serve double duty. They not only represent actual physical detectors but they also serve as abstract six-degrees-of-freedom transformations that a Java 3D application can access. The Sensor class is described in more detail in Section 10.2.3, "The Sensor Object."

10.1.1 The Abstract Interface

All input devices implement a consistent interface that allows the initialization, processing of input, and finalization of a particular input device. A device-driver programmer would implement the following methods in whatever device-specific manner is necessary to perform the specified operations.

Constants
public static final int POLLED
public static final int STREAMING
These flags are deprecated. Use one of the following three flags instead.

public static final int BLOCKING
public static final int NON_BLOCKING
public static final int DEMAND_DRIVEN
These three flags control how Java 3D schedules reads. The BLOCKING flag signifies that the driver for a device is a blocking driver and that it should be scheduled for regular reads by Java 3D. A blocking driver is a driver that can cause the thread accessing the driver (the Java 3D implementation thread calling the pollAndProcessInput method) to block while the data is being accessed from the driver. The NON_BLOCKING flag signifies that the driver for a device is a non-blocking driver and that it should be scheduled for regular reads by Java 3D. The DEMAND_DRIVEN flag signifies that the Java 3D implementation should not schedule regular reads on the sensors of this device; the Java 3D implementation will only call pollAndProcessInput when one of the device's sensors' getRead methods is called. A DEMAND_DRIVEN driver must always provide the current value of the sensor on demand whenever pollAndProcessInput is called. This means that DEMAND_DRIVEN drivers are non-blocking by definition.

Methods
public abstract boolean initialize()
This method initializes the device. It returns true if initialization succeeded, false otherwise.

public abstract void setProcessingMode(int mode)
public abstract int getProcessingMode()
These methods set and retrieve this device's processing mode, one of BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN.

public int getSensorCount()
This method returns the number of Sensor objects associated with this device.

public Sensor getSensor(int sensorIndex)
This method returns the specified Sensor associated with this device.

public abstract void setNominalPositionAndOrientation()
This method sets the device's current position and orientation as the device's nominal position and orientation (that is, establishes its reference frame relative to the "tracker base" reference frame). This method is most useful in defining a nominal pose in immersive head-tracked situations.

public abstract void pollAndProcessInput()
This method first polls the device for data values and then processes the values received from the device. For BLOCKING and NON_BLOCKING drivers, this method is called regularly and the Java 3D implementation can cache the sensor values. For DEMAND_DRIVEN drivers, this method is called each time one of the Sensor.getRead methods is called, and is not otherwise called.

public abstract void processStreamInput()
This method will not be called by the Java 3D implementation and should be implemented as an empty method.

public abstract void close()
This method cleans up the device and relinquishes the associated resources. This method should be called after the device has been unregistered from Java 3D via the PhysicalEnvironment.removeInputDevice(InputDevice) method.

10.1.2 Instantiating and Registering a New Device

A browser or applications developer must instantiate whatever system-specific input devices that he or she needs and that exist on the system. This available-device information typically exists in a site configuration file. The browser or application will instantiate the viewing environment as requested by the end user.

The API for instantiating devices is site-specific, but it consists of a device object with a constructor and at least all of the methods specified in the Input-Device interface.

Once instantiated, the browser or application must register the device with the Java 3D input device scheduler. The API for registering devices is specified in Section 8.7, "The View Object." The addInputDevice method introduces new devices to the Java 3D environment and the allInputDevices method produces an enumeration that allows examination of all available devices within a Java 3D environment.

10.2 Sensors

The Java 3D API provides only an abstract concept of a device. Rather than focusing on issues of devices and device models, it instead defines the concept of a sensor. A sensor consists of a timestamped 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 UserHead.

10.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.

Java 3D includes three special six-degrees-of-freedom (6DOF) entities. These include UserHead, DominantHand, and NondominantHand. An application developer can assign or change which sensor drives one of these predefined entities. Java 3D uses the specified sensor to drive the 6DOF entity-most visibly the View. Application developers should use this facility carefully. It is quite easy to get the effect of a WristCam-and very disconcerting as well.

10.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.

10.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 SensorRead objects. 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.

public static final int DEFAULT_SENSOR_READ_COUNT
This constant specifies the default number of SensorRead objects constructed when no SensorRead count is specified.

Constructors
The Sensor object specifies the following constructors.

public Sensor(InputDevice device)
Constructs a Sensor object for the specified input device using default parameters:

Parameter Default Value
sensorReadCount 0
sensorButtonCount 0
hotspot (0,0,0)
predictor PREDICT_NONE
prediction policy NO_PREDICTOR

public Sensor(InputDevice device, int sensorReadCount)
public Sensor(InputDevice device, int sensorReadCount, 
       int  sensorButtonCount)
These methods construct a new Sensor object associated with the specified device and consisting of either a default number of SensorReads or sensorReadCount number of SensorReads and a hot spot at (0.0, 0.0, 0.0) specified in the sensor's local coordinate system. The default for sensorButtonCount is zero.

public Sensor(InputDevice device, Point3d hotspot)
public Sensor(InputDevice device, int sensorReadCount, 
       Point3d  hotspot)
public Sensor(InputDevice device, int sensorReadCount, 
       int  sensorButtonCount, Point3d hotspot)
These methods construct a new Sensor object associated with the specified device and consisting of either sensorReadCount number of SensorReads or a default number of SensorReads and an offset defining the sensor's hot spot in the sensor's local coordinate system. The default for sensorButtonCount is zero.

Methods
public void setSensorReadCount(int count)
public final int getSensorReadCount()
public final int getSensorButtonCount()
These methods set and retrieve the number of SensorRead objects associated with this sensor and the number of buttons associated with this sensor. Both the number of SensorRead objects and the number of buttons are determined at Sensor construction time.

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 kth)
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. All times are in milliseconds.

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 int lastButtons()
public int lastButtons(int k)
Deprecated methods. Use one of the following methods instead.

public int lastButtons(int values[])
public void lastButtons(int k, int values[])
The first method places the most recent sensor reading value for each button into the array parameter. The second method places the kth most recent sensor reading value for each button into the array parameter, where 0 is the most-recent sensor reading, 1 is the next most recent sensor reading, and so on. These methods will throw an ArrayIndexOutOfBoundsException if values.length is less than the number of buttons.

public void setPredictor(int predictor)
public int getPredictor()
These methods set and retrieve the sensor's predictor policy. The predictor policy is either PREDICT_NONE or PREDICT_NEXT_FRAME_TIME.

public void setPredictionPolicy(int policy)
public int getPredictionPolicy()
These methods set and retrieve the sensor's predictor type. The predictor type is one of the following: NO_PREDICTOR, HEAD_PREDICTOR, or HAND_PREDICTOR.

public void setDevice(InputDevice device)
public InputDevice getDevice()
These methods set and retrieve the sensor's input device.

public SensorRead getCurrentSensorRead()
This method returns the current number of SensorRead objects per sensor.

public void setNextSensorRead(long time, Transform3D transform, 
       int values[])
public void setNextSensorRead(SensorRead read)
These methods set the next SensorRead object to the specified values, including the next SensorRead's associated time, transformation, and button state array.

public void setNextSensorRead(long time, Transform3D transform, 
       int buttons)
Deprecated method. Use one of the above two methods.

10.2.4 The SensorRead Object

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

Constants
public final static int MAXIMUM_SENSOR_BUTTON_COUNT
This flag determines the maximum number of sensor-attached buttons tracked on a per-sensor basis.

Constructors
The SensorRead object specifies the following constructor.

public SensorRead()
Constructs a SensorRead object with default parameters:

Parameter Default Value
numButtons 0
button values 0 (for all array elements)
transform identity
time current time

public SensorRead(int numButtons)
Constructs a SensorRead object with the specified number of buttons.

Methods
public final void set(Transform3D t1)
public final void get(Transform3D result)
These methods set and retrieve the SensorRead object's transform. 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 final void setTime(long time)
public final long getTime()
These methods set and retrieve the SensorRead object'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 final void setButtons(int values)
public final int getButtons()
Deprecated methods. Use the following set and get methods instead.

public final void setButtons(int values[])
public final void getButtons(int values[])
These methods set and retrieve the SensorRead object's button values. They allow a device to store an integer that encodes the button values into the SensorRead object, and a consumer of those values to access the state of the buttons.

10.3 Picking

Behavior nodes provide the means for building developer-specific picking semantics. An application developer can define custom picking semantics using Java 3D's behavior mechanism (see Chapter 9, "Behaviors and Interpolators"). The developer might wish to define pick semantics that use a mouse to shoot a ray into the virtual universe from the current viewpoint, find the first object along that ray, and highlight that object when the end user releases the mouse button. A typical scenario follows:

Java 3D includes helping functions that aid in intersecting various geometric objects with objects in the virtual universe by

10.3.1 SceneGraphPath Object

A SceneGraphPath object represents the path from a Locale to a terminal node in the scene graph. This path consists of a Locale, a terminal node, and an array of internal nodes that are in the path from the Locale to the terminal node. The terminal node may be either a Leaf node or a Group node. A valid SceneGraphPath must uniquely identify a specific instance of the terminal node. For nodes that are not under a SharedGroup, the minimal SceneGraphPath consists of the Locale and the terminal node itself. For nodes that are under a SharedGroup, the minimal SceneGraphPath consists of the Locale, the terminal node, and a list of all Link nodes in the path from the Locale to the terminal node. A SceneGraphPath may optionally contain other interior nodes that are in the path. A SceneGraphPath is verified for correctness and uniqueness when it is sent as an argument to other methods of Java 3D.

In the array of internal nodes, the node at index 0 is the node closest to the Locale. The indices increase along the path to the terminal node, with the node at index length-1 being the node closest to the terminal node. The array of nodes does not contain either the Locale (which is not a node) or the terminal node.

During picking and intersection tests, the user specifies the subtree of the scene graph that should be tested. The whole tree for a Locale is searched by providing the Locale to the picking or intersection tests.

The SceneGraphPath object returned by the picking methods represents all the components in the subgraph that have the capability ENABLE_PICK_REPORTING set between the root of the subtree and the picked or intersected object. All Link nodes are implicitly enabled for pick reporting. Note that ENABLE_PICK_REPORTING and ENABLE_COLLISION_REPORTING are disabled by default. This means that the picking and collision methods will return the minimal SceneGraphPath by default.

When a SceneGraphPath is returned from the picking or collision methods of Java 3D, it will also contain the value of the LocalToVworld transform of the terminal node that was in effect at the time the pick or collision occurred.

Constructors
public SceneGraphPath()
Constructs and initializes a new SceneGraphPath object with default values:

Parameter Default Value
root null
object null
list of (interior) nodes null
transform identity

public SceneGraphPath(Locale root, Node object)
public SceneGraphPath(Locale root, Node nodes[], Node object)
These construct and initialize a new SceneGraphPath object. The first form specifies the path's Locale object and the object in question. The second form includes an array of nodes that fall in between the Locale and the object in question, and which nodes have their ENABLE_PICK_REPORTING capability bit set. The object parameter may be a Group, Shape3D, or Morph node. If any other type of leaf node is specified, an IllegalArgumentException is thrown.

Methods
public final void set(SceneGraphPath newPath)
public final void setLocale(Locale newLocale)
public final void setObject(Node object)
public final void setNode(int index, Node newNode)
public final void setNodes(Node nodes[])
These methods set the path's values. The first method sets the path's interior values. The second method sets the path's Locale to the specified Locale. The third method sets the path's object to the specified object (a Group node, or a Shape3D or Morph leaf node). The fourth method replaces the link node associated with the specified index with the specified newLink. The last method replaces all of the link nodes with the new list of link nodes.

public final Locale getLocale()
public final Node getObject()
The first method returns the path's Locale. The second method returns the path's object.

public final int nodeCount()
public final Node getNode(int index)
The first method returns the number of intermediate nodes in this path. The second method returns the node associated with the specified index.

public final void setTransform(Transform3D trans)
public final Transform3D getTransform()
The set method sets the transform component of this SceneGraphPath to the value of the passed transform. The get method returns a copy of the transform associated with this SceneGraphPath. The method returns null if there is no transform associated. If this SceneGraphPath was returned by a Java 3D picking and collision method, the local-coordinate-to-virtual-coordinate transform for this scene graph object at the time of the pick or collision is recorded.

public final boolean isSamePath(SceneGraphPath testPath)
This method determines whether two SceneGraphPath objects represent the same path in the scene graph. Either object might include a different subset of internal nodes; only the internal link nodes, the Locale, and the Node itself are compared. The paths are not validated for correctness or uniqueness.

public boolean equals(SceneGraphPath testPath)
public boolean equals(Object o1)
The first method returns true if all of the data members of path testPath are equal to the corresponding data members in this SceneGraphPath. The second method returns true if the Object o1 is of type SceneGraphPath and all of the data members of o1 are equal to the corresponding data members in this SceneGraphPath and if the values of the transforms are equal.

public int hashCode()
This method returns a hash number based on the data values in this object. Two different SceneGraphPath objects with identical data values (that is, trans.-equals(SceneGraphPath) returns true) will return the same hash number. Two paths with different data members may return the same hash value, although this is not likely.

public String toString()
This method returns a string representation of this object. The string contains the class names of all nodes in the SceneGraphPath.

10.3.2 BranchGroup Node and Locale Node Pick Methods

The following methods are in both the BranchGroup node class and the Locale node class.

public final SceneGraphPath[] pickAll(PickShape pickShape)
public final SceneGraphPath[] pickAllSorted(PickShape pickShape)
public final SceneGraphPath pickClosest(PickShape pickShape)
public final SceneGraphPath pickAny(PickShape pickShape)
These methods return either an array of SceneGraphPath objects or a single SceneGraphPath object. A SceneGraphPath object describes the entire path from a Locale to a node that intersects the specified PickShape (see Section 10.3.3, "PickShape Object"). The methods that return an array either return all the picked objects or all the picked objects in sorted order starting with the objects "closest" to the eyepoint and ending with the objects farthest from the eyepoint. Methods that return a single SceneGraphPath return a single path object that specifies either the object closest to the eyepoint or any picked object (this latter method also implements the fastest pick operation possible). All ties in testing for closest objects intersected result in an indeterminate order.

10.3.3 PickShape Object

The PickShape object is an abstract class for describing a shape that can be used with the BranchGroup and Locale pick methods. The PickShape object is extended by PickBounds, PickPoint, PickRay, and PickSegment objects.

Constructors
public PickShape()
Constructs a PickShape object.

10.3.4 PickBounds Object

The PickBounds object provides a bounds to supply to the BranchGroup and Locale pick methods. See also Section 10.3.2, "BranchGroup Node and Locale Node Pick Methods."

Constructors
public PickBounds()
public PickBounds(Bounds boundsObject)
The first constructor creates a PickBounds initialized with the bounds set to null. The second constructor creates a PickBounds with the bounds set to boundsObject.

Methods
public void set(Bounds boundsObject)
public Bounds get()
These methods set and retrieve the boundsObject of this PickBounds.

10.3.5 PickPoint Object

The PickPoint object provides a point to supply to the BranchGroup and Locale pick methods. See also Section 10.3.2, "BranchGroup Node and Locale Node Pick Methods."

Constructors
public PickPoint()
public PickPoint(Point3d location)
The first constructor creates a PickPoint initialized to (0,0,0). The second constructor creates a PickPoint at the specified location.

Methods
public void set(Point3d location)
public void get(Point3d location)
These methods set and retrieve the position of this PickPoint.

10.3.6 PickRay Object

The PickRay object is an encapsulation of a ray that is passed to the pick methods in BranchGroup and Locale. See also Section 10.3.2, "BranchGroup Node and Locale Node Pick Methods."

Constructors
public PickRay()
public PickRay(Point3d origin, Vector3d direction)
The first constructor creates a PickRay initialized with an origin and direction of (0,0,0). The second constructor creates a PickRay cast from the specified origin and direction.

Methods
public void set(Point3d origin, Vector3d direction)
public void get(Point3d origin, Vector3d direction)
These methods set and retrieve the ray to point from the specified origin in the specified direction.

10.3.7 PickSegment Object

The PickSegment object is an encapsulation of a segment that is passed to the pick methods in BranchGroup and Locale. See also Section 10.3.2, "BranchGroup Node and Locale Node Pick Methods."

Constructors
public PickSegment()
public PickSegment(Point3d start, Point3d end)
The first constructor creates a PickSegment object with the start and end of the segment initialized to (0,0,0). The second constructor creates a PickSegment object from the specified start and end points.

Methods
public void set(Point3d start, Point3d end)
public void get(Point3d start, Point3d end)
These methods set and return the line segment from the start point to the end point.



Contents Previous Next

Java 3D API Specification


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