More improvements to the SensorManager documentation (0f791a79) · Commits · e / os / android_frameworks_base

core/java/android/hardware/Sensor.java

+15 −5

Original line number	Diff line number	Diff line
		@@ -20,24 +20,32 @@ package android.hardware;
		/**
		* Class representing a sensor. Use {@link SensorManager#getSensorList} to get
		* the list of available Sensors.
		*
		* @see SensorManager
		* @see SensorEventListener
		* @see SensorEvent
		*
		*/
		public class Sensor {

		/**
		* A constant describing an accelerometer sensor type. See
		* {@link android.hardware.SensorEvent SensorEvent} for more details.
		* {@link android.hardware.SensorEvent#values SensorEvent.values} for more
		* details.
		*/
		public static final int TYPE_ACCELEROMETER = 1;

		/**
		* A constant describing a magnetic field sensor type. See
		* {@link android.hardware.SensorEvent SensorEvent} for more details.
		* {@link android.hardware.SensorEvent#values SensorEvent.values} for more
		* details.
		*/
		public static final int TYPE_MAGNETIC_FIELD = 2;

		/**
		* A constant describing an orientation sensor type. See
		* {@link android.hardware.SensorEvent SensorEvent} for more details.
		* {@link android.hardware.SensorEvent#values SensorEvent.values} for more
		* details.
		*
		* @deprecated use {@link android.hardware.SensorManager#getOrientation
		* SensorManager.getOrientation()} instead.
		@@ -50,7 +58,8 @@ public class Sensor {

		/**
		* A constant describing an light sensor type. See
		* {@link android.hardware.SensorEvent SensorEvent} for more details.
		* {@link android.hardware.SensorEvent#values SensorEvent.values} for more
		* details.
		*/
		public static final int TYPE_LIGHT = 5;

		@@ -62,7 +71,8 @@ public class Sensor {

		/**
		* A constant describing an proximity sensor type. See
		* {@link android.hardware.SensorEvent SensorEvent} for more details.
		* {@link android.hardware.SensorEvent#values SensorEvent.values} for more
		* details.
		*/
		public static final int TYPE_PROXIMITY = 8;

core/java/android/hardware/SensorEvent.java

+118 −85

Original line number	Diff line number	Diff line
		@@ -28,17 +28,20 @@ package android.hardware;
		* </p>
		*
		* <p>
		* The coordinate space is defined relative to the screen of the phone in its
		* The coordinate-system is defined relative to the screen of the phone in its
		* default orientation. The axes are not swapped when the device's screen
		* orientation changes.
		* </p>
		*
		* <p>
		* The OpenGL ES coordinate system is used. The origin is in the lower-left
		* corner with respect to the screen, with the X axis horizontal and pointing
		* right, the Y axis vertical and pointing up and the Z axis pointing outside
		* the front face of the screen. In this system, coordinates behind the screen
		* have negative Z values.
		* The X axis is horizontal and points to the right, the Y axis is vertical and
		* points up and the Z axis points towards the outside of the front face of the
		* screen. In this system, coordinates behind the screen have negative Z values.
		* </p>
		*
		* <p>
		* <center><img src="../../../images/axis_device.png"
		* alt="Sensors coordinate-system diagram." border="0" /></center>
		* </p>
		*
		* <p>
		@@ -46,87 +49,69 @@ package android.hardware;
		* Android 2D APIs where the origin is in the top-left corner.
		* </p>
		*
		* <pre>
		* x<0 x>0
		* ^
		* \|
		* +-----------+--> y>0
		* \| \|
		* \| \|
		* \| \|
		* \| \| / z<0
		* \| \| /
		* \| \| /
		* O-----------+/
		* \|[] [ ] []/
		* +----------/+ y<0
		* /
		* /
		* \|/ z>0 (toward the sky)
		* @see SensorManager
		* @see SensorEvent
		* @see Sensor
		*
		* O: Origin (x=0,y=0,z=0)
		* </pre>
		*/

		public class SensorEvent {
		/**
		* <p>
		* The length and contents of the values array vary depending on which
		* {@link android.hardware.Sensor sensor} type is being monitored (see also
		* {@link SensorEvent} for a definition of the coordinate system used):
		* The length and contents of the {@link #values values} array depends on
		* which {@link android.hardware.Sensor sensor} type is being monitored (see
		* also {@link SensorEvent} for a definition of the coordinate system used).
		* </p>
		*
		* <h3>{@link android.hardware.Sensor#TYPE_ORIENTATION
		* Sensor.TYPE_ORIENTATION}:</h3> All values are angles in degrees.
		* <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER
		* Sensor.TYPE_ACCELEROMETER}:</h4> All values are in SI units (m/s^2)
		*
		* <ul>
		* <p>
		* values[0]: Azimuth, angle between the magnetic north direction and the Y
		* axis, around the Z axis (0 to 359). 0=North, 90=East, 180=South, 270=West
		*
		* values[0]: Acceleration minus Gx on the x-axis
		* </p>
		* <p>
		* values[1]: Pitch, rotation around X axis (-180 to 180), with positive
		* values when the z-axis moves <b>toward</b> the y-axis.
		*
		* values[1]: Acceleration minus Gy on the y-axis
		* </p>
		* <p>
		* values[2]: Roll, rotation around Y axis (-90 to 90), with positive values
		* when the x-axis moves <b>toward</b> the z-axis.
		* values[2]: Acceleration minus Gz on the z-axis
		* </p>
		* </ul>
		*
		* <p>
		* <b>Important note:</b> For historical reasons the roll angle is positive
		* in the clockwise direction (mathematically speaking, it should be
		* positive in the counter-clockwise direction).
		* A sensor of this type measures the acceleration applied to the device
		* (<b>Ad</b>). Conceptually, it does so by measuring forces applied to the
		* sensor itself (<b>Fs</b>) using the relation:
		* </p>
		*
		* <p>
		* <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b>
		* used in aviation where the X axis is along the long side of the plane
		* (tail to nose).
		* <b><center>Ad = - ·Fs / mass</center></b>
		*
		* <p>
		* <b>Note:</b> This sensor type exists for legacy reasons, please use
		* {@link android.hardware.SensorManager#getRotationMatrix
		* getRotationMatrix()} in conjunction with
		* {@link android.hardware.SensorManager#remapCoordinateSystem
		* remapCoordinateSystem()} and
		* {@link android.hardware.SensorManager#getOrientation getOrientation()} to
		* compute these values instead.
		* In particular, the force of gravity is always influencing the measured
		* acceleration:
		* </p>
		*
		* <h3>{@link android.hardware.Sensor#TYPE_ACCELEROMETER
		* Sensor.TYPE_ACCELEROMETER}:</h3>
		* All values are in SI units (m/s^2) and measure the acceleration applied
		* to the phone minus the force of gravity.
		* <b><center>Ad = -g - ·F / mass</center></b>
		*
		* <ul>
		* <p>
		* values[0]: Acceleration minus Gx on the x-axis
		* <p>
		* values[1]: Acceleration minus Gy on the y-axis
		* For this reason, when the device is sitting on a table (and obviously not
		* accelerating), the accelerometer reads a magnitude of <b>g</b> = 9.81
		* m/s^2
		* </p>
		*
		* <p>
		* values[2]: Acceleration minus Gz on the z-axis
		* </ul>
		* Similarly, when the device is in free-fall and therefore dangerously
		* accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a
		* magnitude of 0 m/s^2.
		* </p>
		*
		* <p>
		* It should be apparent that in order to measure the real acceleration of
		* the device, the contribution of the force of gravity must be eliminated.
		* This can be achieved by applying a <i>high-pass</i> filter. Conversely, a
		* <i>low-pass</i> filter can be used to isolate the force of gravity.
		* </p>
		* <p>
		* <u>Examples</u>:
		* <ul>
		* <li>When the device lies flat on a table and is pushed on its left side
		@@ -143,20 +128,20 @@ public class SensorEvent {
		* </ul>
		*
		*
		* <h3>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
		* Sensor.TYPE_MAGNETIC_FIELD}:</h3>
		* <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
		* Sensor.TYPE_MAGNETIC_FIELD}:</h4>
		* All values are in micro-Tesla (uT) and measure the ambient magnetic field
		* in the X, Y and Z axis.
		*
		* <h3>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h3>
		* <h4>{@link android.hardware.Sensor#TYPE_LIGHT Sensor.TYPE_LIGHT}:</h4>
		*
		* <ul>
		* <p>
		* values[0]: Ambient light level in SI lux units
		* </ul>
		*
		* <h3>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:
		* </h3>
		* <h4>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:
		* </h4>
		*
		* <ul>
		* <p>
		@@ -164,9 +149,57 @@ public class SensorEvent {
		* </ul>
		*
		* <p>
		* Note that some proximity sensors only support a binary "close" or "far"
		* measurement. In this case, the sensor should report its maxRange value in
		* the "far" state and a value less than maxRange in the "near" state.
		* <b>Note:</b> Some proximity sensors only support a binary <i>near</i> or
		* <i>far</i> measurement. In this case, the sensor should report its
		* {@link android.hardware.Sensor#getMaximumRange() maximum range} value in
		* the <i>far</i> state and a lesser value in the <i>near</i> state.
		* </p>
		*
		* <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION
		* Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees.
		*
		* <ul>
		* <p>
		* values[0]: Azimuth, angle between the magnetic north direction and the
		* y-axis, around the z-axis (0 to 359). 0=North, 90=East, 180=South,
		* 270=West
		* </p>
		*
		* <p>
		* values[1]: Pitch, rotation around x-axis (-180 to 180), with positive
		* values when the z-axis moves <b>toward</b> the y-axis.
		* </p>
		*
		* <p>
		* values[2]: Roll, rotation around y-axis (-90 to 90), with positive values
		* when the x-axis moves <b>toward</b> the z-axis.
		* </p>
		* </ul>
		*
		* <p>
		* <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b>
		* used in aviation where the X axis is along the long side of the plane
		* (tail to nose).
		* </p>
		*
		* <p>
		* <b>Note:</b> This sensor type exists for legacy reasons, please use
		* {@link android.hardware.SensorManager#getRotationMatrix
		* getRotationMatrix()} in conjunction with
		* {@link android.hardware.SensorManager#remapCoordinateSystem
		* remapCoordinateSystem()} and
		* {@link android.hardware.SensorManager#getOrientation getOrientation()} to
		* compute these values instead.
		* </p>
		*
		* <p>
		* <b>Important note:</b> For historical reasons the roll angle is positive
		* in the clockwise direction (mathematically speaking, it should be
		* positive in the counter-clockwise direction).
		* </p>
		*
		* @see SensorEvent
		* @see GeomagneticField
		*/
		public final float[] values;

core/java/android/hardware/SensorManager.java

+159 −87

Original line number	Diff line number	Diff line
		@@ -46,6 +46,30 @@ import java.util.List;
		* {@link android.content.Context#getSystemService(java.lang.String)
		* Context.getSystemService()} with the argument
		* {@link android.content.Context#SENSOR_SERVICE}.
		*
		* <pre class="prettyprint">
		* public class SensorActivity extends Activity, implements SensorEventListener {
		* private final SensorManager mSensorManager;
		* private final Sensor mAccelerometer;
		*
		* public SensorActivity() {
		* mSensorManager = (SensorManager)getSystemService(SENSOR_SERVICE);
		* mAccelerometer = mSensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER);
		* mSensorManager.registerListener(this, mAccelerometer, SensorManager.SENSOR_DELAY_NORMAL);
		* }
		*
		* public void onAccuracyChanged(Sensor sensor, int accuracy) {
		* }
		*
		* public abstract void onSensorChanged(SensorEvent event) {
		* }
		* }
		* </pre>
		*
		* @see SensorEventListener
		* @see SensorEvent
		* @see Sensor
		*
		*/
		public class SensorManager
		{
		@@ -678,6 +702,9 @@ public class SensorManager
		* of sensors requested
		*
		* @return a list of sensors matching the asked type.
		*
		* @see #getDefaultSensor(int)
		* @see Sensor
		*/
		public List<Sensor> getSensorList(int type) {
		// cache the returned lists the first time
		@@ -712,6 +739,9 @@ public class SensorManager
		* of sensors requested
		*
		* @return the default sensors matching the asked type.
		*
		* @see #getSensorList(int)
		* @see Sensor
		*/
		public Sensor getDefaultSensor(int type) {
		// TODO: need to be smarter, for now, just return the 1st sensor
		@@ -909,9 +939,13 @@ public class SensorManager
		*
		* @param listener
		* a SensorEventListener object
		*
		* @param sensor
		* the sensor to unregister from
		*
		* @see #unregisterListener(SensorEventListener)
		* @see #registerListener(SensorEventListener, Sensor, int)
		*
		*/
		public void unregisterListener(SensorEventListener listener, Sensor sensor) {
		unregisterListener((Object)listener, sensor);
		@@ -923,6 +957,9 @@ public class SensorManager
		* @param listener
		* a SensorListener object
		*
		* @see #unregisterListener(SensorEventListener, Sensor)
		* @see #registerListener(SensorEventListener, Sensor, int)
		*
		*/
		public void unregisterListener(SensorEventListener listener) {
		unregisterListener((Object)listener);
		@@ -950,6 +987,10 @@ public class SensorManager
		* @return <code>true</code> if the sensor is supported and successfully
		* enabled.
		*
		* @see #registerListener(SensorEventListener, Sensor, int, Handler)
		* @see #unregisterListener(SensorEventListener)
		* @see #unregisterListener(SensorEventListener, Sensor)
		*
		*/
		public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate) {
		return registerListener(listener, sensor, rate, null);
		@@ -981,6 +1022,10 @@ public class SensorManager
		*
		* @return true if the sensor is supported and successfully enabled.
		*
		* @see #registerListener(SensorEventListener, Sensor, int)
		* @see #unregisterListener(SensorEventListener)
		* @see #unregisterListener(SensorEventListener, Sensor)
		*
		*/
		public boolean registerListener(SensorEventListener listener, Sensor sensor, int rate,
		Handler handler) {
		@@ -1115,6 +1160,12 @@ public class SensorManager
		* points towards the magnetic North Pole.</li>
		* <li>Z points towards the sky and is perpendicular to the ground.</li>
		* </ul>
		*
		* <p>
		* <center><img src="../../../images/axis_globe.png"
		* alt="Sensors coordinate-system diagram." border="0" /></center>
		* </p>
		*
		* <p>
		* <hr>
		* <p>
		@@ -1221,6 +1272,10 @@ public class SensorManager
		* @return <code>true</code> on success, <code>false</code> on failure (for
		* instance, if the device is in free fall). On failure the output
		* matrices are not modified.
		*
		* @see #getInclination(float[])
		* @see #getOrientation(float[], float[])
		* @see #remapCoordinateSystem(float[], int, int, float[])
		*/

		public static boolean getRotationMatrix(float[] R, float[] I,
		@@ -1292,7 +1347,13 @@ public class SensorManager
		*
		* @param I
		* inclination matrix see {@link #getRotationMatrix}.
		*
		* @return The geomagnetic inclination angle in radians.
		*
		* @see #getRotationMatrix(float[], float[], float[], float[])
		* @see #getOrientation(float[], float[])
		* @see GeomagneticField
		*
		*/
		public static float getInclination(float[] I) {
		if (I.length == 9) {
		@@ -1373,6 +1434,8 @@ public class SensorManager
		* @return <code>true</code> on success. <code>false</code> if the input
		* parameters are incorrect, for instance if X and Y define the same
		* axis. Or if inR and outR don't have the same length.
		*
		* @see #getRotationMatrix(float[], float[], float[], float[])
		*/

		public static boolean remapCoordinateSystem(float[] inR, int X, int Y,
		@@ -1464,14 +1527,23 @@ public class SensorManager
		* <li>values[2]: <i>roll</i>, rotation around the Y axis.</li>
		* </ul>
		* <p>
		* <center><img src="../../../images/axis_device.png"
		* alt="Sensors coordinate-system diagram." border="0" /></center>
		* </p>
		* <p>
		* All three angles above are in <b>radians</b> and <b>positive</b> in the
		* <b>counter-clockwise</b> direction.
		*
		* @param R
		* rotation matrix see {@link #getRotationMatrix}.
		*
		* @param values
		* an array of 3 floats to hold the result.
		*
		* @return The array values passed as argument.
		*
		* @see #getRotationMatrix(float[], float[], float[], float[])
		* @see GeomagneticField
		*/
		public static float[] getOrientation(float[] R, float values[]) {
		/*

docs/html/images/axis_device.png

0 → 100644

+17.2 KiB

Loading image diff...

docs/html/images/axis_globe.png

0 → 100644

+8.11 KiB

Loading image diff...