SensorEvent.java revision 74cde2cee9e53006a710f4e80700cd560c2d0e4d 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware;
18
19/**
20 * <p>
21 * This class represents a {@link android.hardware.Sensor Sensor} event and
22 * holds informations such as the sensor's type, the time-stamp, accuracy and of
23 * course the sensor's {@link SensorEvent#values data}.
24 * </p>
25 *
26 * <p>
27 * <u>Definition of the coordinate system used by the SensorEvent API.</u>
28 * </p>
29 *
30 * <p>
31 * The coordinate space is defined relative to the screen of the phone in its
32 * default orientation. The axes are not swapped when the device's screen
33 * orientation changes.
34 * </p>
35 *
36 * <p>
37 * The OpenGL ES coordinate system is used. The origin is in the lower-left
38 * corner with respect to the screen, with the X axis horizontal and pointing
39 * right, the Y axis vertical and pointing up and the Z axis pointing outside
40 * the front face of the screen. In this system, coordinates behind the screen
41 * have negative Z values.
42 * </p>
43 *
44 * <p>
45 * <b>Note:</b> This coordinate system is different from the one used in the
46 * Android 2D APIs where the origin is in the top-left corner.
47 * </p>
48 *
49 * <pre>
50 *   x<0         x>0
51 *                ^
52 *                |
53 *    +-----------+-->  y>0
54 *    |           |
55 *    |           |
56 *    |           |
57 *    |           |   / z<0
58 *    |           |  /
59 *    |           | /
60 *    O-----------+/
61 *    |[]  [ ]  []/
62 *    +----------/+     y<0
63 *              /
64 *             /
65 *           |/ z>0 (toward the sky)
66 *
67 *    O: Origin (x=0,y=0,z=0)
68 * </pre>
69 */
70
71public class SensorEvent {
72    /**
73     * <p>
74     * The length and contents of the values array vary depending on which
75     * {@link android.hardware.Sensor sensor} type is being monitored (see also
76     * {@link SensorEvent} for a definition of the coordinate system used):
77     * </p>
78     *
79     * <h3>{@link android.hardware.Sensor#TYPE_ORIENTATION
80     * Sensor.TYPE_ORIENTATION}:</h3> All values are angles in degrees.
81     *
82     * <ul>
83     * <p>
84     * values[0]: Azimuth, angle between the magnetic north direction and the Y
85     * axis, around the Z axis (0 to 359). 0=North, 90=East, 180=South, 270=West
86     *
87     * <p>
88     * values[1]: Pitch, rotation around X axis (-180 to 180), with positive
89     * values when the z-axis moves <b>toward</b> the y-axis.
90     *
91     * <p>
92     * values[2]: Roll, rotation around Y axis (-90 to 90), with positive values
93     * when the x-axis moves <b>toward</b> the z-axis.
94     * </ul>
95     *
96     * <p>
97     * <b>Important note:</b> For historical reasons the roll angle is positive
98     * in the clockwise direction (mathematically speaking, it should be
99     * positive in the counter-clockwise direction).
100     *
101     * <p>
102     * <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b>
103     * used in aviation where the X axis is along the long side of the plane
104     * (tail to nose).
105     *
106     * <p>
107     * <b>Note:</b> This sensor type exists for legacy reasons, please use
108     * {@link android.hardware.SensorManager#getRotationMatrix
109     * getRotationMatrix()} in conjunction with
110     * {@link android.hardware.SensorManager#remapCoordinateSystem
111     * remapCoordinateSystem()} and
112     * {@link android.hardware.SensorManager#getOrientation getOrientation()} to
113     * compute these values instead.
114     *
115     * <h3>{@link android.hardware.Sensor#TYPE_ACCELEROMETER
116     * Sensor.TYPE_ACCELEROMETER}:</h3>
117     * All values are in SI units (m/s^2) and measure the acceleration applied
118     * to the phone minus the force of gravity.
119     *
120     * <ul>
121     * <p>
122     * values[0]: Acceleration minus Gx on the x-axis
123     * <p>
124     * values[1]: Acceleration minus Gy on the y-axis
125     * <p>
126     * values[2]: Acceleration minus Gz on the z-axis
127     * </ul>
128     *
129     * <p>
130     * <u>Examples</u>:
131     * <ul>
132     * <li>When the device lies flat on a table and is pushed on its left side
133     * toward the right, the x acceleration value is positive.</li>
134     *
135     * <li>When the device lies flat on a table, the acceleration value is
136     * +9.81, which correspond to the acceleration of the device (0 m/s^2) minus
137     * the force of gravity (-9.81 m/s^2).</li>
138     *
139     * <li>When the device lies flat on a table and is pushed toward the sky
140     * with an acceleration of A m/s^2, the acceleration value is equal to
141     * A+9.81 which correspond to the acceleration of the device (+A m/s^2)
142     * minus the force of gravity (-9.81 m/s^2).</li>
143     * </ul>
144     *
145     *
146     * <h3>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
147     * Sensor.TYPE_MAGNETIC_FIELD}:</h3>
148     * All values are in micro-Tesla (uT) and measure the ambient magnetic field
149     * in the X, Y and Z axis.
150     *
151     * <h3>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h3>
152     *
153     * <ul>
154     * <p>
155     * values[0]: Ambient light level in SI lux units
156     * </ul>
157     *
158     * <h3>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:
159     * </h3>
160     *
161     * <ul>
162     * <p>
163     * values[0]: Proximity sensor distance measured in centimeters
164     * </ul>
165     *
166     * <p>
167     * Note that some proximity sensors only support a binary "close" or "far"
168     * measurement. In this case, the sensor should report its maxRange value in
169     * the "far" state and a value less than maxRange in the "near" state.
170     */
171    public final float[] values;
172
173    /**
174     * The sensor that generated this event. See
175     * {@link android.hardware.SensorManager SensorManager} for details.
176     */
177   public Sensor sensor;
178
179    /**
180     * The accuracy of this event. See {@link android.hardware.SensorManager
181     * SensorManager} for details.
182     */
183    public int accuracy;
184
185
186    /**
187     * The time in nanosecond at which the event happened
188     */
189    public long timestamp;
190
191
192    SensorEvent(int size) {
193        values = new float[size];
194    }
195}
196