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.public static final int POLLED public static final int STREAMINGThese 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_DRIVENThese three flags control how Java 3D schedules reads. TheBLOCKING
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 thepollAndProcessInput
method) to block while the data is being accessed from the driver. TheNON_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. TheDEMAND_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 callpollAndProcessInput
when one of the device's sensors'getRead
methods is called. ADEMAND_DRIVEN
driver must always provide the current value of the sensor on demand wheneverpollAndProcessInput
is called. This means thatDEMAND_DRIVEN
drivers are non-blocking by definition.public abstract boolean initialize()This method initializes the device. It returnstrue
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 ofBLOCKING
,NON_BLOCKING
, orDEMAND_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. ForBLOCKING
andNON_BLOCKING
drivers, this method is called regularly and the Java 3D implementation can cache the sensor values. ForDEMAND_DRIVEN
drivers, this method is called each time one of theSensor.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 thePhysicalEnvironment.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 theallInputDevices
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_TIMEThese 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_PREDICTORThese 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_COUNTThis 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 orsensorReadCount
number of SensorReads and a hot spot at (0.0, 0.0, 0.0) specified in the sensor's local coordinate system. The default forsensorButtonCount
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 eithersensorReadCount
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 forsensorButtonCount
is zero.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 theread
matrix. The second method computes the sensor reading consistent as of timedeltaT
in the future and copies that value into theread
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 ifvalues.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 eitherPREDICT_NONE
orPREDICT_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
, orHAND_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.public final static int MAXIMUM_SENSOR_BUTTON_COUNTThis 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.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:1. The application constructs a Behavior node that arms itself to awaken when AWT detects a left-mouse-button-down event.
Java 3D includes helping functions that aid in intersecting various geometric objects with objects in the virtual universe by2. Upon awakening from a left-mouse-button-down event, the behavior
a. Updates a Switch node to draw a ray that emanates from the center of the screen.
3. Upon awakening from a mouse-move event, the behaviorb. Changes that ray's TransformGroup node so that the ray points in the direction of the current mouse position.
c. Declares its interest in mouse-move or left-mouse-button-up events.
a. Changes that ray's TransformGroup node so that the ray points in the direction of the current mouse position.
4. Upon awakening from a left-mouse-button-up event, the behaviorb. Declares its interest in mouse-move or left-mouse-button-up events.
a. Changes that ray's TransformGroup node so that the ray points in the direction of the current mouse position.
b. Intersects the ray with all the objects in the virtual universe to find the first object that the ray intersects.
c. Changes the appearance component of that object's shape node to highlight the selected object.
d. Declares its interest in left-mouse-button-down events.
- Intersecting an oriented ray with all the objects in the virtual universe. That function can return the first object intersected along that ray, all the objects that intersect that ray, or a list of all the objects along that ray sorted by distance from the ray's origin.
- Intersecting a volume with all the objects in the virtual universe. That function returns a list of all the objects contained in that volume.
- Discovering which vertex within an object is closest to a specified ray.
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 thatENABLE_PICK_REPORTING
andENABLE_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.
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 theirENABLE_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, anIllegalArgumentException
is thrown.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 returnstrue
if all of the data members of pathtestPath
are equal to the corresponding data members in this SceneGraphPath. The second method returns true if the Objecto1
is of type SceneGraphPath and all of the data members ofo1
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)
returnstrue
) 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.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."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 toboundsObject
.public void set(Bounds boundsObject) public Bounds get()These methods set and retrieve theboundsObject
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."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.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."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 specifiedorigin
anddirection
.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 specifiedorigin
in the specifieddirection
.
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."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 specifiedstart
andend
points.public void set(Point3d start, Point3d end) public void get(Point3d start, Point3d end)These methods set and return the line segment from thestart
point to theend
point.
Java 3D API Specification
Copyright © 1999, Sun Microsystems, Inc. All rights reserved.