001: /*
002: * $RCSfile: InputDevice.java,v $
003: *
004: * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:25 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * InputDevice is the interface through which Java 3D and Java 3D
036: * application programs communicate with a device driver. All input
037: * devices that Java 3D uses must implement the InputDevice interface and
038: * be registered with Java 3D via a call to
039: * PhysicalEnvironment.addInputDevice(InputDevice). An input device
040: * transfers information to the Java 3D implementation and Java 3D
041: * applications by writing transform information to sensors that the
042: * device driver has created and manages. The driver can update its
043: * sensor information each time the pollAndProcessInput method is
044: * called.
045: */
046:
047: public interface InputDevice {
048:
049: /**
050: * Signifies that the driver for a device is a blocking driver and that
051: * it should be scheduled for regular reads by Java 3D. A blocking driver
052: * is defined as a driver that can cause the thread accessing the driver
053: * (the Java 3D implementation thread calling the pollAndProcessInput
054: * method) to block while the data is being accessed from the driver.
055: */
056: public static final int BLOCKING = 3;
057:
058: /**
059: * Signifies that the driver for a device is a non-blocking driver and
060: * that it should be scheduled for regular reads by Java 3D. A
061: * non-blocking driver is defined as a driver that does not cause the
062: * calling thread to block while data is being retrieved from the
063: * driver. If no data is available from the device, pollAndProcessInput
064: * should return without updating the sensor read value.
065: */
066: public static final int NON_BLOCKING = 4;
067:
068: /**
069: * Signifies that the Java 3D implementation should not schedule
070: * regular reads on the sensors of this device; the Java 3D
071: * implementation will only call pollAndProcessInput when one of the
072: * device's sensors' getRead methods is called. A DEMAND_DRIVEN driver
073: * must always provide the current value of the sensor on demand whenever
074: * pollAndProcessInput is called. This means that DEMAND_DRIVEN drivers
075: * are non-blocking by definition.
076: */
077: public static final int DEMAND_DRIVEN = 5;
078:
079: /**
080: * This method initializes the device. A device should be initialized
081: * before it is registered with Java 3D via the
082: * PhysicalEnvironment.addInputDevice(InputDevice) method call.
083: * @return return true for succesful initialization, false for failure
084: */
085: public abstract boolean initialize();
086:
087: /**
088: * This method sets the device's current position and orientation as the
089: * devices nominal position and orientation (establish its reference
090: * frame relative to the "Tracker base" reference frame).
091: */
092: public abstract void setNominalPositionAndOrientation();
093:
094: /**
095: * This method causes the device's sensor readings to be updated by the
096: * device driver. For BLOCKING and NON_BLOCKING drivers, this method is
097: * called regularly and the Java 3D implementation can cache the sensor
098: * values. For DEMAND_DRIVEN drivers this method is called each time one
099: * of the Sensor.getRead methods is called, and is not otherwise called.
100: */
101: public abstract void pollAndProcessInput();
102:
103: /**
104: * This method will not be called by the Java 3D implementation and
105: * should be implemented as an empty method.
106: */
107: public abstract void processStreamInput();
108:
109: /**
110: * Code to process the clean up of the device and relinquish associated
111: * resources. This method should be called after the device has been
112: * unregistered from Java 3D via the
113: * PhysicalEnvironment.removeInputDevice(InputDevice) method call.
114: */
115: public abstract void close();
116:
117: /**
118: * This method retrieves the device's processing mode: one of BLOCKING,
119: * NON_BLOCKING, or DEMAND_DRIVEN. The Java 3D implementation calls
120: * this method when PhysicalEnvironment.addInputDevice(InputDevice) is
121: * called to register the device with Java 3D. If this method returns
122: * any value other than BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN,
123: * addInputDevice will throw an IllegalArgumentException.
124: * @return Returns the devices processing mode, one of BLOCKING,
125: * NON_BLOCKING, or DEMAND_DRIVEN
126: */
127: public abstract int getProcessingMode();
128:
129: /**
130: * This method sets the device's processing mode to one of: BLOCKING,
131: * NON_BLOCKING, or DEMAND_DRIVEN. Many drivers will be written to run
132: * in only one mode. Applications using such drivers should not attempt
133: * to set the processing mode. This method should throw an
134: * IllegalArgumentException if there is an attempt to set the processing
135: * mode to anything other than the aforementioned three values.
136: *
137: * <p>
138: * NOTE: this method should <i>not</i> be called after the input
139: * device has been added to a PhysicalEnvironment. The
140: * processingMode must remain constant while a device is attached
141: * to a PhysicalEnvironment.
142: *
143: * @param mode One of BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN
144: */
145: public abstract void setProcessingMode(int mode);
146:
147: /**
148: * This method gets the number of sensors associated with the device.
149: * @return the device's sensor count.
150: */
151: public int getSensorCount();
152:
153: /**
154: * Gets the specified Sensor associated with the device. Each InputDevice
155: * implementation is responsible for creating and managing its own set of
156: * sensors. The sensor indices begin at zero and end at number of
157: * sensors minus one. Each sensor should have had
158: * Sensor.setDevice(InputDevice) set properly before addInputDevice
159: * is called.
160: * @param sensorIndex the sensor to retrieve
161: * @return Returns the specified sensor.
162: */
163: public Sensor getSensor(int sensorIndex);
164:
165: }
|