The Java 3D API Specification Contents Previous Next Index


C H A P T E R11

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

11.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. Not only do they 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 11.2.3, "The Sensor Object."

11.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 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 poll-AndProcessInput 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 nonblocking 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 call only pollAndProcessInput when the getRead method for one of the device's sensors 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 nonblocking 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, it 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; it 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.

11.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 whatever exists 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 9.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.

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

11.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, as it is quite easy to get the effect of a WristCam-and very disconcerting as well.

11.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. Additionally, it 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.

11.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
predictionPolicy 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. They consist 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 consist 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 int getSensorReadCount()
public 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(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)
The first method sets the next sensor read to the specified values; once these values are set via this method, they become the current values returned by methods such as lastRead(), lastTime() and lastButtons(): Note that if there are no buttons associated with this sensor, then values can just be an empty array. The second method sets the next SensorRead object to the specified values, including the next SensorRead's associated time, transformation, and button state array.

11.2.4 The SensorRead Object

A SensorRead object encapsulates all the information associated with a single reading of a sensor, including a timestamp, a transform, and, optionally, button values.

Constants
public static final 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 the following 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 void set(Transform3D t1)
public 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 void setTime(long time)
public 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 void setButtons(int values[])
public 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.

public int getNumButtons()
This method returns the number of buttons associated with this SensorRead object.

11.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 10, "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


Note: Picking and scene graph update are not synchronized. In Java 3D version 1.2, the elapsed time between a scene graph update and a pick (that uses the updated scene graph) is about three frames.

11.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 Locale null
object null
nodeCount 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.

11.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 SceneGraphPath[] pickAll(PickShape pickShape)
public SceneGraphPath[] pickAllSorted(PickShape pickShape)
public SceneGraphPath pickClosest(PickShape pickShape)
public 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 11.3.3, "PickShape Object"). The methods that return an array return either 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.

11.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, PickCone, PickCylinder, PickPoint, PickRay, and PickSegment objects. The PickCylinder object is further extended by the PickCylinder and PickCylinderSegment objects. The PickCone object is further extended by the PickConeRay and PickConeSegment objects.

Constructors
public PickShape()
Constructs a PickShape object.

11.3.4 PickBounds Object

The PickBounds object provides a bounds to supply to the BranchGroup and Locale pick methods. See also Section 11.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.

11.3.5 PickPoint Object

The PickPoint object provides a point to supply to the BranchGroup and Locale pick methods. See also Section 11.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.

11.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 11.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 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 origin and direction of this PickRay object.

11.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 11.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 retrieve the start and end points of this PickSegment object.

11.3.8 PickCone Object

The PickCone object is the abstract base class for all cone pick shapes. PickCone is extended by the PickConeRay and PickConeSegment classes.

Constructors
public PickCone()
Constructs an empty PickCone. The origin and direction of the cone are initialized to (0,0,0). The spread angle is initialized to /64.

Methods
public void getOrigin(Point3d origin)
public void getDirection(Vector3d direction)
public double getSpreadAngle()
These three methods return the origin, direction, and spread angle of this PickCone, respectively.

11.3.9 PickConeRay Object

The PickConeRay object is an infinite cone pick ray shape. It can be used as an argument to the picking methods in BranchGroup and Locale.

Constructors
public PickConeRay()
public PickConeRay(Point3d origin, Vector3d direction,
       double  spreadAngle)
The first constructor creates an empty PickConeRay. The origin and direction of the cone are initialized to (0,0,0). The spread angle is initialized to /64 radian. The second constructor creates an infinite cone pick shape from the specified parameters.

Methods
public void set(Point3d origin, Vector3d direction,
       double  spreadAngle)
This method sets the parameters of this PickCone to the specified values.

11.3.10 PickConeSegment Object

The PickConeSegment object is a finite cone segment pick shape. It can be used as an argument to the picking methods in BranchGroup and Locale.

Constructors
public PickConeSegment()
public PickConeSegment(Point3d origin, Point3d end,
       double  spreadAngle)
The first constructor creates an empty PickConeSegment. The origin and end point of the cone are initialized to (0,0,0). The spread angle is initialized to /64 radians. The second constructor creates a finite cone pick shape from the specified parameters.

Methods
public void set(Point3d origin, Point3d end, double spreadAngle)
This method sets the parameters of this PickCone to the specified values.

public void getEnd(Point3d end)
This method gets the end point of this PickConeSegment.

11.3.11 PickCylinder Object

The PickCylinder object is the abstract base class of all cylindrical pick shapes.

Constructors
public PickCylinder()
This constructor creates an empty PickCylinder. The origin of the cylinder is initialized to (0,0,0). The radius is initialized to 0.

Methods
public void getOrigin(Point3d origin)
public double getRadius()
public void getDirection(Vector3d direction)
These three methods return the origin, radius, and direction of this PickCylinder object.

11.3.12 PickCylinderRay Object

The PickCylinderRay object is an infinite cylindrical ray pick shape. It can be used as an argument to the picking methods in BranchGroup and Locale.

Constructors
public PickCylinderRay()
public PickCylinderRay(Point3d origin, Vector3d direction,
       double  radius)
The first constructor creates an empty PickCylinderRay. The origin and direction of the cylindrical ray are initialized to (0,0,0). The radius is initialized to 0. The second constructor creates an infinite cylindrical ray pick shape from the specified parameters.

Methods
public void set(Point3d origin, Vector3d direction, double radius)
This method sets the parameters of this PickCylinderRay to the specified values.

11.3.13 PickCylinderSegment Object

The PickCylinderSegment object is a finite cylindrical segment pick shape. It can be used as an argument to the picking methods in BranchGroup and Locale.

Constructors
public PickCylinderSegment()
public PickCylinderSegment(Point3d start, Point3d end,
       double  radius)
The first constructor creates an empty PickCylinderSegment. The start and end points of the cylindrical segment are initialized to (0,0,0). The radius is initialized to 0.

Methods
public void set(Point3d start, Point3d end, double radius)
This method sets the parameters of this PickCylinderSegment to the specified values.

public void getEnd(Point3d end)
This method returns the end point of this PickCylinderSegment.



   The Java 3D API Specification Contents Previous Next Index


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