1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
/*
* Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
package javax.media.j3d;
/**
* InputDevice is the interface through which Java 3D and Java 3D
* application programs communicate with a device driver. All input
* devices that Java 3D uses must implement the InputDevice interface and
* be registered with Java 3D via a call to
* PhysicalEnvironment.addInputDevice(InputDevice). An input device
* transfers information to the Java 3D implementation and Java 3D
* applications by writing transform information to sensors that the
* device driver has created and manages. The driver can update its
* sensor information each time the pollAndProcessInput method is
* called.
*/
public interface InputDevice {
/**
* 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 defined as a driver that can cause the thread accessing the driver
* (the Java 3D implementation thread calling the pollAndProcessInput
* method) to block while the data is being accessed from the driver.
*/
public static final int BLOCKING = 3;
/**
* Signifies that the driver for a device is a non-blocking driver and
* that it should be scheduled for regular reads by Java 3D. A
* non-blocking driver is defined as a driver that does not cause the
* calling thread to block while data is being retrieved from the
* driver. If no data is available from the device, pollAndProcessInput
* should return without updating the sensor read value.
*/
public static final int NON_BLOCKING = 4;
/**
* Signifies that the Java 3D implementation should not schedule
* regular reads on the sensors of this device; the Java 3D
* implementation will only call pollAndProcessInput when one of the
* device's sensors' getRead methods is called. A DEMAND_DRIVEN driver
* must always provide the current value of the sensor on demand whenever
* pollAndProcessInput is called. This means that DEMAND_DRIVEN drivers
* are non-blocking by definition.
*/
public static final int DEMAND_DRIVEN = 5;
/**
* This method initializes the device. A device should be initialized
* before it is registered with Java 3D via the
* PhysicalEnvironment.addInputDevice(InputDevice) method call.
* @return return true for succesful initialization, false for failure
*/
public abstract boolean initialize();
/**
* This method sets the device's current position and orientation as the
* devices nominal position and orientation (establish its reference
* frame relative to the "Tracker base" reference frame).
*/
public abstract void setNominalPositionAndOrientation();
/**
* This method causes the device's sensor readings to be updated by the
* device driver. For BLOCKING and NON_BLOCKING drivers, this method is
* called regularly and the Java 3D implementation can cache the sensor
* values. For DEMAND_DRIVEN drivers this method is called each time one
* of the Sensor.getRead methods is called, and is not otherwise called.
*/
public abstract void pollAndProcessInput();
/**
* This method will not be called by the Java 3D implementation and
* should be implemented as an empty method.
*/
public abstract void processStreamInput();
/**
* Code to process the clean up of the device and relinquish associated
* resources. This method should be called after the device has been
* unregistered from Java 3D via the
* PhysicalEnvironment.removeInputDevice(InputDevice) method call.
*/
public abstract void close();
/**
* This method retrieves the device's processing mode: one of BLOCKING,
* NON_BLOCKING, or DEMAND_DRIVEN. The Java 3D implementation calls
* this method when PhysicalEnvironment.addInputDevice(InputDevice) is
* called to register the device with Java 3D. If this method returns
* any value other than BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN,
* addInputDevice will throw an IllegalArgumentException.
* @return Returns the devices processing mode, one of BLOCKING,
* NON_BLOCKING, or DEMAND_DRIVEN
*/
public abstract int getProcessingMode();
/**
* This method sets the device's processing mode to one of: BLOCKING,
* NON_BLOCKING, or DEMAND_DRIVEN. Many drivers will be written to run
* in only one mode. Applications using such drivers should not attempt
* to set the processing mode. This method should throw an
* IllegalArgumentException if there is an attempt to set the processing
* mode to anything other than the aforementioned three values.
*
* <p>
* NOTE: this method should <i>not</i> be called after the input
* device has been added to a PhysicalEnvironment. The
* processingMode must remain constant while a device is attached
* to a PhysicalEnvironment.
*
* @param mode One of BLOCKING, NON_BLOCKING, or DEMAND_DRIVEN
*/
public abstract void setProcessingMode(int mode);
/**
* This method gets the number of sensors associated with the device.
* @return the device's sensor count.
*/
public int getSensorCount();
/**
* Gets the specified Sensor associated with the device. Each InputDevice
* implementation is responsible for creating and managing its own set of
* sensors. The sensor indices begin at zero and end at number of
* sensors minus one. Each sensor should have had
* Sensor.setDevice(InputDevice) set properly before addInputDevice
* is called.
* @param sensorIndex the sensor to retrieve
* @return Returns the specified sensor.
*/
public Sensor getSensor(int sensorIndex);
}
|
