The Java 3D API Specification |
C H A P T E R11 |
Input Devices and Picking |
11.1
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.InputDevice Interface 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
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:The Abstract Interface 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 thepoll-AndProcessInput
method) to block while the data is being accessed from the driver. TheNON_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. 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 call onlypollAndProcessInput
when thegetRead
method for one of the device's sensors 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 nonblocking 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, 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. 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; 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 thePhysicalEnvironment.removeInputDevice(InputDevice)
method.
11.1.2
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.Instantiating and Registering a New Device 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 theallInputDevices
method produces an enumeration that allows examination of all available devices within a Java 3D environment.
11.2
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).Sensors
11.2.1
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.Using and Assigning Sensors
11.2.2
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.Behind the (Sensor) Scenes
11.2.3
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.The Sensor Object
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 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 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 consist 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 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 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(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)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
A SensorRead object encapsulates all the information associated with a single reading of a sensor, including a timestamp, a transform, and, optionally, button values.The SensorRead Object public static final 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 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.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
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:Picking 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.
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
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.SceneGraphPath Object 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 theirENABLE_PICK_REPORTING
capability bit set. Theobject
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.
11.3.2
The following methods are in both the BranchGroup node class and the Locale node class:BranchGroup Node and Locale Node Pick Methods 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
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.PickShape Object public PickShape()Constructs a PickShape object.
11.3.4
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."PickBounds Object 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.
11.3.5
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."PickPoint Object 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.
11.3.6
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."PickRay Object 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 specifiedorigin
anddirection
.public void set(Point3d origin, Vector3d direction) public void get(Point3d origin, Vector3d direction)These methods set and retrieve theorigin
anddirection
of this PickRay object.
11.3.7
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."PickSegment Object 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 retrieve thestart
andend
points of this PickSegment object.
11.3.8
The PickCone object is the abstract base class for all cone pick shapes. PickCone is extended by the PickConeRay and PickConeSegment classes.PickCone Object 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
.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
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.PickConeRay Object 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.public void set(Point3d origin, Vector3d direction, double spreadAngle)This method sets the parameters of this PickCone to the specified values.
11.3.10
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.PickConeSegment Object 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.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
The PickCylinder object is the abstract base class of all cylindrical pick shapes.PickCylinder Object 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.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
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.PickCylinderRay Object 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.public void set(Point3d origin, Vector3d direction, double radius)This method sets the parameters of this PickCylinderRay to the specified values.
11.3.13
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.PickCylinderSegment Object 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.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 |